Assertions

Assertions encode your design standards. The pipeline uses them to strip conformant values and annotate deviations.

Example

assertions:
  - id: no-latest
    assert: Image tags must not use latest
    match:
      path: services.*.image
      pattern: "^(?!.*:latest$)"
    rationale: Reproducible deployments
    severity: must
    example: "nginx:1.25.3"

  - id: restart-policy
    assert: Containers must use unless-stopped restart policy
    match:
      path: services.*.restart
      value: unless-stopped
    rationale: Proper restart behaviour
    severity: must

  - id: healthcheck-required
    assert: All containers must have health checks
    match:
      path: services.*.healthcheck
      exists: true
    rationale: Monitoring and orchestration readiness
    severity: must

Fields

Field	Required	Description
id	Yes	Unique identifier.
assert	Yes	Human-readable description.
rationale	Yes	Why this standard exists.
severity	Yes	must, should, or may. Only must triggers stripping.
match	No	Machine-evaluable condition. Without it, the assertion is LLM context only.
exceptions	No	Documented exceptions.
example	No	Conformant value example.
related	No	Related assertion IDs.
source	No	Standard source.

Match conditions

The match field requires a path and one condition type:

Condition	Description	Example
value	Exact match (case-insensitive).	value: json-file
pattern	Regex match.	pattern: "^(?!.*:latest$)"
range	Numeric range [min, max].	range: [1, 65535]
contains	List must contain item.	contains: http
not_value	Must NOT equal.	not_value: latest
exists	Key must exist (or not).	exists: true

Path patterns

Pattern	Matches
services.web.image	Exact path.
services.*.image	* matches one segment.
**.managedFields	** matches any depth.
metadata.**.name	** in the middle.

Severity behavior

Severity	Conformant values	Deviations
must	Stripped (removed)	Annotated with # [!]
should	Kept	Annotated with # [!]
may	Kept	LLM context only

Bundled assertions

decoct ships with deployment standard assertions for Docker Compose (12 rules from OPS-DOCKER-001):

• must: pinned image tags, restart policy, container naming, healthcheck presence, logging driver, log rotation, no privileged containers
• should: no-new-privileges security option, resource limits, named networks, no host 0.0.0.0 port bindings

Use them via the bundled profile:

decoct compress docker-compose.yaml --profile docker-compose

See Bundled Assertions Reference for details on each assertion.

LLM-assisted assertion learning

Derive assertions from standards documents, examples, or a corpus of configs:

decoct assertion learn -s team-standards.md -p docker-compose -o assertions.yaml
decoct assertion learn -c configs/*.yaml -p docker-compose -o learned.yaml

Corpus mode (-c) analyses cross-file patterns to discover implicit standards. Requires pip install decoct[llm]. See Assertion Authoring for full details.