Decision policy

The decision policy decides which stages run. Same inputs, same decisions.

How the policy works

Before executing any stage, VAR evaluates a policy that considers:

Factor	Question
Change significance	How important are the changes?
Cost budget	How much work is the developer willing to do?
Stage prerequisites	Has the previous stage passed?

The policy produces a per-stage decision: RUN, SKIP, or BLOCK, each with a rationale string explaining why.

Change significance

VAR classifies the overall change set into one of three significance levels:

Level	When	Pipeline depth
HIGH	Source changes in core logic or effect-heavy areas	Full pipeline (all stages)
MEDIUM	Source changes in boundaries/contracts, or test-only changes	Check + test
LOW	Only docs, config, or generated files changed	Discovery only

Significance is computed from the file categories and code areas found in Stage 1. A single source file change in a core module raises significance to HIGH.

Cost budget

The --max-cost flag lets you cap how deep the pipeline goes:

Budget	What runs
low	Discovery and check only
medium (default)	Discovery, check, and test
high	Everything including mutation and review (if enabled)

The budget interacts with significance. A HIGH significance change with a low budget still only runs discovery and check, but the terminal state will be PARTIAL (not COMPLETE) because more validation was warranted.

Stage prerequisites

Stages run in strict order. If check fails, the policy may still allow test to run (to gather more information), but the terminal state will be BLOCKED regardless. Mutation and review require their respective --include-mutation and --include-review-packet flags.

Rationale strings

Every decision includes a rationale string, visible in --dry-run --explain and JSON output:

[RUN]  discovery   Detect changed files
[RUN]  check       Source files changed, static analysis required
[RUN]  test        3 test files cover changed modules
[SKIP] mutation    Not enabled (use --include-mutation)
[SKIP] review      Not enabled (use --include-review-packet)

The rationale is intended for both human readers and LLM agents that use vary var output to decide what to do next.

Dry-run mode

vary var --dry-run evaluates the policy and prints the plan without executing any stages. Add --explain for significance, per-stage decisions, scoped file lists, and rationale:

vary var --dry-run --explain

Significance: HIGH (source changes in PURE_LOGIC area)
Budget: medium

  [RUN]  discovery  files=9
  [RUN]  check      files=4 (src/app.vary, src/lib.vary, ...)
  [RUN]  test       files=3 (tests/test_app.vary, ...)
  [SKIP] mutation   Budget capped at medium
  [SKIP] review     Not enabled

Preview what VAR plans to do before committing to a full run.

JSON output

In --json mode, the policy section includes the full decision tree:

{
  "significance": "high",
  "significance_rationale": "Source changes in PURE_LOGIC area",
  "stages": [
    {
      "stage": "check",
      "action": "run",
      "rationale": "Source files changed, static analysis required",
      "files": ["src/app.vary", "src/lib.vary"]
    }
  ]
}