# Test plans and sections

A **test plan** describes behaviors and scenarios to verify. The current executable catalog is a directory of `.snag.md` test definitions, grouped by directory and optional `section.md` configuration. It is not a separate manifest.

## Reusable definitions

A test definition has a section-local optional explicit ID (filename fallback) and a free-form Markdown body. Authoring recommends prerequisites, checkbox steps and expected outcomes. Those instructions are reusable across attempts. A test result records what happened when they were executed; it must not rewrite the original definition to fit the observation.

## Hierarchical sections

Directories create sections even without a section file. A section can add instructions, metadata, executor defaults, evidence requirements, destination settings and lifecycle hooks. Tests start in deterministic filename traversal order; numeric order has no precedence.

Instructions append root-to-leaf with explicit replacement. Tags accumulate case-insensitively with explicit removal; components and levels remain descriptive sets. Explicit test executor values override section defaults. Destination provider/project settings inherit together; a child destination replaces that pair. These are routing hints, not credentials or live provider access.

## Execution revisions

The parser fingerprints the resolved execution contract, including the free-form body, authored checklist, optional prerequisites/expectations, inherited instructions/settings and declared hooks. Metadata used only for discovery/selection does not change that revision. An explicit retry must match it; changing instructions while reusing old attempts would otherwise hide which contract was tested.

The revision fingerprint is compatibility metadata, not a cryptographic authenticity claim. A project's hook implementation still needs its own change discipline.

Inspect [the sample catalog](../../examples/test-plan.md), write a [first definition](../guides/author-test-plans.md), and consult [format/reference](../reference/test-definition-format.md) for inheritance and validation rules.