Routes
Routes are the candidate ways to satisfy work. Each route has a stable machineid, a human label, and an optional rank. Lower rank means earlier default preference when no rule has explicitly selected a route.
checks— a list of command ids that must pass before the route is usedtool_boundary— a phase-scoped permission contract (see Tool boundaries)execution_plan— an ordered sequence of named phases, each with its ownrequires,forbid, and optional sub-tool_boundary
id is a stable API identifier. Human label and description can change without breaking tests and cross-references; the id must not churn.
Rules
Rules are the conditional steering layer. Each rule has an optionalwhen predicate and a set of typed effects. Rules are evaluated in file order against the current input. When a rule matches, its effects are applied additively to the running decision state.
when clause is unconditional — it matches every input. The reason field carries a human-readable rationale that is recorded in the trace and shown in alignment reports.
Predicate fields
Thewhen predicate can combine any of these fields. Multiple fields compose with logical AND. Values inside user_says_any compose with logical OR.
Phrase matching is case-insensitive and word-boundary–aware —
"browse" matches "browse the page" but not "unobserved".
Rule effect algebra
Rules apply in file order. The algebra is additive for most fields, with two exceptions:prefersets the currently selected route — last matchingpreferwins in file order.route_orderreplaces the current ordering — a later rule can completely reorder.forbidis a union — every matched rule adds its forbidden set; nothing removes from it.elicitappends — all matched rules contribute their elicitation requests.after_successappends — all closures from matched rules accumulate.
After all rules are evaluated, if no rule has set a route via
prefer, the first route in the current route_order is selected. This is the default_route_order basis, which appears in the decision trace.Elicitations
Elicitations are bounded questions. They are used when the skill should ask for a specific missing decision instead of guessing or asking open-ended questions. A rule requests an elicitation by adding its id toelicit. The elicitation itself lives in the elicitations mapping and defines the choices, an optional default, and an optional cap on how many choices may be selected.
sets— write named facts into the decision contextroute— steer to a specific route if selectednext— advance to a named state in the state machinesafety— classify the consequence of this choice (read_only,local_write,destructive, etc.)
required_when describes when the elicitation is mandatory — for example, when the selected route matches a given id, or when a named fact is absent from the context.
Tool boundaries
Tool boundaries are phase-scoped permission contracts. They can appear at three levels, inherited from outer to inner:
A boundary does not enforce by itself — it gives the harness a concrete pre-tool-call checklist. Any action outside the rendered boundary requires explicit user permission before use.
Complete example
The following contract is drawn from thebefore-after example. It shows routes, a steering rule, an elicitation, and scenario tests that prove the composed decision: