Specification Reference

An Orvienm specification is a YAML file declaring one structure: a name, and the directories that should exist beneath it. The format is deliberately small and closed — four root keys, two of them optional — and it grows only as the engine implements more.

This page documents what the engine accepts today. For what each command does with a specification, see the CLI Reference.

version: 1

structure:
  name: platform
  directories:
    - core
    - data

Applying this creates platform/ containing core/ data/, relative to the directory the command runs in.

version: 1

style: enterprise        # optional: enterprise | technical | hybrid

structure:
  name: platform         # required — the directory the engine creates
  directories:           # required — non-empty list of strings
    - core
    - data
    - docs

policy:                  # optional
  forbid:
    - secrets

The root must be a YAML mapping. Exactly four keys are recognised.

• version — required. Declares the format the file is written against. The value is recorded in the fingerprint and the lock file, but is not range-checked.
• structure — required. A mapping; see below.
• style — optional. See below.
• policy — optional. See below.

The root key set is closed. Any other key is a validation error: Unknown field at root level: 'x'. This is why keys borrowed from older drafts or from other tools — relationships among them — will fail rather than be ignored.

• structure.name — required. Names the directory the engine creates and inspects. It is resolved relative to the working directory, so running a command from inside that directory would create a second nested root.
• structure.directories — required. A list of strings, which must not be empty. Each entry is a directory beneath the root. An entry may contain forward slashes, in which case the intermediate directories are created too.

Optional. Accepts enterprise, technical hybrid; any other value is a validation error. When omitted it is treated as enterprise.

style does not change what the engine creates, but it does participate in the fingerprint — changing it changes the specification's identity and therefore counts as drift.

Optional. Only one rule is implemented: policy.forbid, a list of names.

policy:
  forbid:
    - secrets

The orvienm policy command reads that list and reports any of those names found inside the declared structure, at any depth, with the path relative to the structure root. Nothing is ever blocked or removed. By default the command exits 0 even when it finds a violation, so adding a policy block cannot turn a green pipeline red; orvienm policy --strict exits 2 on a violation when you want it to gate. policy is not part of validation, and no other command consults it.

Each entry in structure.directories is checked individually after normalisation. All of the following are validation errors.

• A value that is not a string, or a string that is empty or only whitespace.
• An absolute path — /data C:\data. A specification cannot reach outside the workspace.
• A path containing ... Traversal is rejected for the same reason.
• Any of the characters < > : " \ | ? *. Forward slashes are permitted.
• Two entries that normalise to the same path — a and ./a collide.

Entry order is irrelevant. The fingerprint sorts the list, so reordering directories produces the same identity.

Because forward slashes are allowed, an entry such as core/products validates and applies correctly — the engine creates the intermediate directories.

Every command reasons over the same expanded set. A declared path contributes itself and each of its ancestors, so plan reports keep for all of them after a successful apply, verify checks all of them, and doctor does not treat an intermediate directory the engine created as undeclared.

Entry order never matters: the fingerprint sorts the list, and the expansion collapses ancestors shared by siblings.

plan, apply, graph policy accept an optional file argument. When it is omitted they use the first of these found in the working directory:

.orvienm.yaml
orvienm.yaml
orvienm.yml

validate, verify, status, doctor fingerprint require the file argument explicitly and will error without it.

On a successful apply, the engine writes .orv.lock in the working directory.

{
    "orvienm_version": "0.3.0",
    "generated_at": "2026-08-27T04:12:51.638274Z",
    "fingerprint": "810ce0ae93772eb7ed941e811c7f66ab4bcf9e8eef1c2b2d8b676246cda5963f",
    "structure_name": "platform",
    "schema_version": 1,
    "style": "enterprise"
}

The fingerprint field is a SHA-256 over a canonical manifest built from exactly four inputs: version, style, structure.name and the sorted directory list. Comments, key order and whitespace do not affect it.

Drift means the current specification's fingerprint differs from the one recorded in the lock — that is, the specification changed, not the filesystem. When it does, apply refuses to run and exits 3. Delete .orv.lock to accept the new specification, then apply again. Because drift is compared at the fingerprint level rather than field by field, deleting the lock accepts every change in the file at once.

A successful apply records the specification the workspace now stands on, whether it created the structure or found it already compliant. A failed apply records nothing, and a blocked one leaves the existing lock untouched, so evidence of drift is never overwritten before it is acknowledged.

The lock is the engine's only persisted state: there is no state directory, snapshot store or run history in the CLI.

These appear in older material and in adjacent tools. None of them is accepted by the current validator, and using them produces an error rather than being ignored.

• Nested YAML mappings as structure syntax — directories are a flat list of paths.
• _requires, references and dependency declarations.
• relationships and declarative graph edges.
• Appendices, profiles beyond the style values, and OSL.
• Cycle detection, naming conventions and constraint rules.
• Warning severities — every validation finding is an error.

When a specification fails, see Troubleshooting.