A pull request lands once CI has run

Each file can be read, and holds a YAML mapping of fields.

awml is "0.8". An older file is upgraded with awml convert.

Each file, scope, part, line, implementation, block and comment has the fields it needs and no others, and each list is a list of mappings.

Each part and line has a kind the spec defines.

Scope, part, block and comment ids are unique across the file.

An id is letters, digits and underscores, starting with a letter, and a block's platform is a company id or owner/platforms/slug.

Ids, labels, kinds and references are text, not something YAML read as true, false, a number or a date.

Each in, from and to, each part a block names and each part a comment ties names a scope, block or part the file has.

Following in from any scope or block never leads back to it.

A comment moves nothing, so only a tie, or a hidden line, may touch it.

A tie links a comment to what it explains, so one of its ends is a comment.

A trigger only starts its own workflow, so no line but a tie or a hidden one goes into it. A workflow starts another with an outside action whose ref names the other's trigger.

• the line from "ci" to "tryfailed" goes into trigger "tryfailed": a trigger only starts its own workflow, so start another workflow with an outside action whose ref names its trigger

An op is one of the operations the spec lists, on an ai, code or person step.

A step that leads to an outside action, straight or through a review or a standing approval, is a do step.

An answer step and a check step read contexts and speak on surfaces, but never write to a context.

An outside action's label ends with Allow, Ask or Block after a colon.

An Ask action has a review, a standing approval or a person's own step on every way in, an Allow action has no review or standing approval in front of it, and only red lines lead to a Block action.

A standing approval leads to the surface where each action it covers is listed.

A scope's processing is any, none, or a map from company ids to any or a list of known operations.

A scope inside another allows no company or operation that the outer scope doesn't.

platform belongs to a block of an implementation, never to a scope.

wait is an ISO 8601 duration in weeks, days, hours, minutes or seconds, given only on a trigger.

at is a relative path of plain names, given only on a context.

untrusted is true or false, and is true only on a trigger, connector or context.

cleans is true or false, and is true only on a code step, since strangers' text can steer an AI step however it's written.

Text from a part marked untrusted reaches an outside action only past a review, a person's own step or a code step marked cleans, which stops it, or through a standing approval in front of the action, which accepts the risk. Workflows given together are followed through the parts they share and the workflows they start.

A ref is owner/slug#id for a published workflow, or a path to a file alongside, ending .yaml, then # and the part's id.

Workflows share the contexts, connectors and surfaces both reach, and an outside action names the trigger of the workflow it starts. A trigger belongs to the workflow it starts, so it never refers.

• part "tryfailed" has a ref, but a trigger belongs to the workflow it starts: start another workflow with an outside action whose ref names its trigger

Each part sits in at most one block of each implementation.

Every part but a trigger or comment sits in a block of each implementation.

A ref to a workflow given with it names a part that workflow has. A ref to a workflow not given is left alone.

A context, connector or surface that refers to another workflow's has the same kind, label and at, and a scope with the same people and terms.

An outside action that refers to a workflow given with it names that workflow's trigger, which it starts.

A ref names a part of another workflow, never its own, and following refs from any copy ends at the one that owns the part, rather than going round in a circle.

A do step should be code acting on what an earlier step decided; this warns and never fails.

A do step should lead to one change, counting each outside action and surface and all contexts together as one; this warns and never fails.

A trigger's run is every part its start lines reach, and triggers whose runs share a part are one workflow, so triggers in more than one group mean the file should be split at its triggers; this warns and never fails.

Following lines either way from the triggers, leaving out comments and their ties, reaches every part; this warns and never fails.

A comment explains what it is tied to, so each has a tie; this warns and never fails.

Each step, review and standing approval is in some trigger's run, the parts its start lines reach; this warns and never fails.

A context that workflows given together share is written by only one of them, since each may change what another relies on; this warns and never fails.

A connector that workflows given together share brings items in for only one of them, since each may take an item another expects; this warns and never fails.

platform is a mapping, off_for_up_to a duration, steps code or agent, agents and calls lists of company ids, and holds a list.

Skipped because no file given is a platform description.

A platform description's id is a company id or owner/platforms/slug, its company ids are lower-case letters, digits and hyphens, and what it holds are relative paths.

Skipped because no file given is a platform description.