Invariants

The musketeer check command validates a set of structural invariants on run state. These are the rules that are actually enforced today.

Enforced invariants

Required files exist

Rule: Every run directory must contain all five YAML files: intent.yml, constraints.yml, plan.yml, progress.yml, handoff.yml.

If any file is missing, check reports an error for that run.

Replay ID consistency

Rule: The replay_id field in each of the five YAML files must match the run directory name.

This prevents files from being moved or copied between runs without updating their contents.

Progress sequence integrity

Rule: The seq values in progress.yml entries must start at 1 and be strictly increasing.

This ensures the progress log has no gaps, duplicates, or out-of-order entries.

Plan task uniqueness

Rule: All task IDs in plan.yml must be unique.

No two tasks may share the same id value.

How check works

The check command validates a single run. By default it picks the lexicographically last run ID (the latest). You can target a specific run with --replay <id>.

musketeer check                  # Check latest run
musketeer check --replay <id>    # Check specific run

If all invariants hold, check exits with code 0. If any fail, it prints errors and exits with a non-zero code.

Policy rules (not yet enforced)

The following are design goals described in the trio model but not currently enforced by musketeer check:

• File ownership - the Executor should not modify intent.yml or constraints.yml
• Atomic writes - writes use temp-file-plus-rename to prevent corruption (this is implemented in the write layer but not validated by check)

What invariants do not guarantee

Invariants are about structural consistency, not application correctness. Musketeer does not guarantee:

• Your code is bug-free
• Your logic is correct
• External systems behave as expected

Musketeer guarantees that run state is structurally valid and internally consistent.