Validation Model

Validation is not only the validate command. Every command that reads a specification — plan, apply, verify, status, doctor, fingerprint — parses and validates it first and stops on failure. There is no way to reach the filesystem with a specification that does not validate.

A specification can fail in two distinct places, and they report differently.

parse      file missing, empty, malformed YAML,
           or a root that is not a mapping     → exit 4

validate   schema and path rules below         → exit 1

Parse failures are about the file. Validation failures are about what the file says.

• The root must be a mapping.
• version must be present. Its value is recorded but not range-checked.
• structure must be present and must be a mapping.
• structure.name must be present.
• structure.directories must be present, must be a list, and must not be empty.
• style, if present, must be one of enterprise, technical hybrid. It defaults to enterprise.
• The root key set is closed. Only version, structure, style policy are accepted; anything else is reported as an unknown field.

Each entry in structure.directories is checked individually, after normalisation.

• It must be a string, and must not be empty or whitespace.
• It must be relative. Absolute paths are rejected, so a specification cannot reach outside the workspace.
• It must not contain ... Path traversal is rejected for the same reason.
• It must not contain the characters < > : " \ | ? *. Forward slashes are allowed.
• Two entries must not normalise to the same path. Duplicates are rejected.

Validation collects every problem it finds and reports them together, one per line, rather than stopping at the first. A single run tells you everything wrong with the file.

Validation failed:
Missing required field 'structure.name'.
'structure.directories' cannot be empty.
Unknown field at root level: 'relationships'.

Messages name the field and the fault. They do not carry line numbers, character positions or suggested fixes, so locate the field by name in your file.

Validation reads the specification only. It never looks at the filesystem, so it cannot tell you whether the structure exists, is complete, or has drifted.

There is no rule engine, no cross-reference checking, no dependency or cycle analysis, and no naming-convention enforcement beyond the character rules above. A specification that validates is well-formed — not necessarily the structure you intended.

Every key and rule enumerated above is listed field by field in the Specification Reference, and each message is explained in Troubleshooting.

For questions about the workspace rather than the file, use verify, status doctor. Policy rules declared under policy.forbid are checked by the separate policy command, not by validation.