validate
Verify forge module changes compile, run, and meet API contracts before merging. Checks files, syntax, commands, and cross-module dependencies, tracking progress across attempts.
Instructions
Run full verification for a forge module against a specific working directory. Executes the module's verify commands in a subprocess, checks that required files exist on disk, runs AST-level syntax validation for .js/.mjs/.cjs/.py/.ts/.tsx files, and performs cross-module API contract checks (importer references matched against exporter symbols). Tracks attempts across retries, detects stagnation when the same failure set recurs, measures score velocity across attempts, and flags oscillation when the current failures match any of the last four attempts. Returns a structured pass/fail verdict with a per-check breakdown and a recommendation field (PROCEED, RETRY, ESCALATE).
Behaviour:
MUTATION. Appends an attempt entry to the module's iteration state at
.forge/iterations/<runId>/<moduleId>.jsonwhen runId is provided, or the legacy flat path otherwise. Also emits atool_calland avalidateevent to the current run's JSONL log.No authentication, no network calls, no rate limits.
Verify commands run with a 2-minute per-command timeout; AST syntax checks get 60 seconds each. Commands execute through the shell (
execSync) so plan-generated commands can use pipes and redirects — plans are human-approved before execution.The
cwdargument (v0.4.0+) redirects file existence checks, syntax checks, contract checks, and command execution to a specified directory. Precedence:args.cwd > FORGE_CWD env > process.cwd(). Workers running in isolated git worktrees MUST pass their worktree path ascwd— otherwise validation silently checks the main project root, and every worker DONE report would be meaningless.Nonexistent
cwdreturns acwd_checkfailure withrecommendation: "ESCALATE"and a clear diagnostic, rather than letting every command fail with an opaque ENOENT.
Use when:
The orchestrator has received a DONE report from a worker agent and needs to verify that the changes actually compile, run, and honor any cross-module API contracts before merge-back.
A module has just been retried by the debugger agent and you want to know whether the attempt count has crossed the stagnation threshold.
A user invokes
/forge-validate <moduleId>manually to re-run checks on a completed or in-progress module.
Do NOT use for:
Plan-level structural checks (DAG cycles, missing commands) — use
validate_planinstead.Querying past validation attempts without bumping a counter — use
forge_logsoriteration_statewithaction: "get".Running commands outside the context of a known moduleId — this tool mutates per-module iteration state.
Returns: A JSON text block with
{ passed, score, results[], attempt, stagnant, velocity, oscillating,
recommendation, sameAsPrev }
where results[] is a list of per-check objects tagged with type
(file_check, syntax_check, contract_check, command,
cwd_check) and their pass/fail metadata.
Example: validate({ moduleId: "m3", runId: "2026-04-15-1", files: ["src/auth.mjs", "src/auth.test.mjs"], commands: ["node --test src/auth.test.mjs"], cwd: "/tmp/forge-worktrees/m3" }) → { "passed": true, "score": 1.0, "recommendation": "PROCEED", "results": [ ... ], "attempt": 1, "stagnant": false }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| moduleId | Yes | Module ID (e.g. m1, m2) | |
| runId | No | Optional run ID (plan slug). Scopes iteration state so attempts from different forge runs don't pollute each other. Strongly recommended — without it, attempts accumulate across all runs forever. | |
| cwd | No | Optional absolute path to redirect file checks and command execution. Workers running in git worktrees should pass their worktree path here so validation sees their changes. Precedence: args.cwd > FORGE_CWD env > process.cwd(). Must exist when provided — nonexistent paths return a cwd_check failure with recommendation=ESCALATE. | |
| commands | Yes | Shell commands to run as verification checks | |
| files | No | File paths (relative to the validation working dir — `cwd` if provided, else server CWD) that should exist after module completion | |
| contractChecks | No | Optional cross-module API contract checks — verifies importer references match exporter exports |