DevRunbook-Public/docs/28-conditions-and-policy-dsl.md

28 — Conditions and policy DSL

Goal

Conditional inputs, guardrails, workflow steps, checks and incompatibilities use a declarative data structure. Implementations must never execute condition text through JavaScript, a shell, template helpers or another general-purpose expression evaluator.

Condition forms

A condition is exactly one of:

fact:
  path: inputs.migrationRequired
  operator: eq
  value: true

all:
  - fact: { path: repository.stack.languages, operator: contains, value: TypeScript }
  - fact: { path: repository.capabilities, operator: contains, value: build-command }

any:
  - fact: { path: composition.workMode, operator: eq, value: execute }
  - fact: { path: composition.workMode, operator: eq, value: recovery }

not:
  fact: { path: inputs.preserveCompatibility, operator: truthy }

Allowed roots

• inputs — normalized declared playbook inputs;
• repository — allowlisted normalized Repository Profile facts;
• composition — work mode, autonomy, output format and resolved scope facts;
• platform — safe platform capabilities and non-secret policy facts.

No path may reference environment variables, integration secrets, raw repository files, database queries or arbitrary object prototypes.

Operators

• exists
• truthy
• falsy
• eq
• neq
• in
• not-in
• contains
• gt
• gte
• lt
• lte

Operator compatibility is type-checked. Numeric comparison does not coerce strings. contains supports arrays and strings. in tests whether the fact value is present in the supplied array.

Three-valued evaluation

Evaluation returns true, false or unknown.

Unknown occurs when:

• a path does not exist;
• the value has the wrong type;
• a required repository profile is absent;
• an adapter cannot provide a declared capability.

Handling:

Context	Unknown behavior
Blocking guardrail	Include the guardrail and add a warning; fail closed
Incompatible condition	Treat as not proven incompatible and show compatibility unknown
Required workflow/check	Include and warn
Optional workflow/check	Exclude and warn
Input visibility	Show the field so required context is not hidden
Export readiness	Block only when the unresolved condition affects a required input or safety decision

Policy precedence

Conditions decide whether a rule applies; they do not change precedence. Final policy order remains:

1. platform non-overridable policy;
2. workspace policy;
3. repository policy;
4. playbook guardrail;
5. user-selectable option.

A false lower-priority condition cannot disable a higher-priority rule.

Capability vocabulary

Playbooks may require only the governed capabilities in schemas/playbook.schema.json.

test-command is satisfied by at least one confirmed unit, integration or end-to-end test command. More specific capabilities require the corresponding command role.

A command marked safeForAgentSuggestion: false may satisfy compatibility but must not be rendered as an instruction to execute without explicit user confirmation.

Determinism

• Object key order does not affect the result.
• Array order for all and any does not affect the boolean result, but stored source order is preserved for provenance.
• No current time, network call or mutable external state is available to the evaluator.
• Every fact access is recorded in the provenance result.

Validation failures

The package importer rejects:

• unknown roots or operators;
• paths to undeclared inputs;
• eq or comparison conditions with an incompatible literal type when the input type is known;
• empty all or any groups;
• nesting deeper than 12 levels;
• more than 100 total condition nodes per package;
• conditions that would require secret values.