121 lines
3.8 KiB
Markdown
121 lines
3.8 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
fact:
|
|
path: inputs.migrationRequired
|
|
operator: eq
|
|
value: true
|
|
```
|
|
|
|
```yaml
|
|
all:
|
|
- fact: { path: repository.stack.languages, operator: contains, value: TypeScript }
|
|
- fact: { path: repository.capabilities, operator: contains, value: build-command }
|
|
```
|
|
|
|
```yaml
|
|
any:
|
|
- fact: { path: composition.workMode, operator: eq, value: execute }
|
|
- fact: { path: composition.workMode, operator: eq, value: recovery }
|
|
```
|
|
|
|
```yaml
|
|
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.
|