Testing, validation, and execution in a Map
Maps are tools agents can use to guide implementation and verify the result. The plan holds the outcome, dependencies, acceptance criteria, declared checks, and recorded evidence together. An agent reads that context, performs authorized work, and explicitly invokes the checks for ready steps.
MapForge supplies the planning and verification operations. Your agent or host coordinates implementation; the library does not autonomously implement a plan.
Define checks before implementation
Write each step's instructions and acceptance criteria in its step.md. Declare automated checks in map.yaml, with a stable check ID, command, and implementation-relative working directory.
For example, this manifest defines a step whose acceptance check is the project's test suite:
version: 1
title: Verify authentication
steps:
auth:
title: Implement and verify authentication
status: todo
depends_on: []
checks:
- id: auth-tests
command: npm test
cwd: .
evidence: []
Supply map.md and steps/auth/step.md alongside this manifest. Replace npm test with the project's actual acceptance check. A step can declare multiple checks, such as unit tests and integration tests. All prerequisites must be complete before the step can be in progress or done.
Validate the plan
From the MapForge checkout, inspect the plan before working on it:
node dist/cli.js validate /absolute/project api-release
node dist/cli.js status /absolute/project api-release
Validation checks the plan's structure and managed planning workspace, including document requirements, dependency references, cycles, prerequisite completion, and the evidence required for done steps. The updater also validates candidate changes before accepting them.
Validation reads the plan. It does not execute the declared checks or establish that the implementation passes them.
Execute ready checks
After implementing a step, the agent can invoke its declared checks when that execution is within the authorized task:
node dist/cli.js test /absolute/project api-release auth
Omit the step ID to select all currently ready automated checks:
node dist/cli.js test /absolute/project api-release
The runner executes checks sequentially, in each declared working directory within the implementation checkout. Each check has a two-minute timeout. It supplies MAP_ROOT for the Map directory in the planning worktree and MAP_SOURCE_ROOT for the implementation checkout.
Blocked steps and steps requiring manual verification are skipped. A nonzero exit or timeout is recorded as a failure. The CLI exits nonzero for failures, skipped work, or no runnable checks.
Commands are ordinary scripts. The agent must inspect them and keep execution within the requested task. Reading or updating a Map does not start those scripts.
Keep evidence with the tested revision
The runner appends evidence through the shared updater. Evidence identifies the check, pass or failure, source commit and dirty-change digest, planning revision and fingerprint, command, working directory, and exit outcome. Terminal output stays in the terminal.
Source or plan changes during a run prevent results from being recorded against the wrong snapshot. Reconcile the change before rerunning. An update receipt records the resulting plan mutation; testing does not stage, commit, or publish the Map.
Review completion and revalidate changes
Passing checks do not automatically mark a step done. The agent reviews acceptance criteria and updates the step through the normal updater. Every required check needs its latest evidence to pass before a step can be done. A step without automated checks requires explicit passing manual evidence that identifies who reviewed which criteria.
A failed rerun resets the affected step and dependent completion to todo. After relevant source or check changes, the agent must rerun verification and reset affected completion as needed. Schema v1 does not automatically invalidate evidence for arbitrary later source changes; recorded evidence is an assertion about the tested revision.
For the exact schema, see Map format & protocol. For agent instructions, see Run verification and Update a Map.