Flow plans, validates, and independently reviews work before reporting it done. This contract distinguishes runtime enforcement, trusted host observations, and model judgments. Each tier names what can fail.
| Tier | What it means | If the model is wrong |
|---|---|---|
| TS-enforced | A type, schema, or transition guard refuses the state. | The call fails. |
| Host-attested | OpenCode reports the fact; Flow records it and cannot forge it. | Recorded as ineligible, never as a pass. |
| Caller-declared | Flow validates the shape, not the truth. | Stored as a declaration and labelled as one. |
| Model-judgment | A prompt asks for it; nothing checks it. | Silently wrong. |
| Unenforced | Known gap, deliberately not closed. | Silently wrong. |
- One active feature run; dependencies complete before a run starts.
- A plan is a bounded acyclic graph, immutable after approval.
completedclosure requires a completed current run for every planned feature. Inspections may complete with blocking findings, without full completion assurance.- Exactly one review assignment per run;
featureorfinalis derived, never chosen by the caller. - Only the reserved
flow-revieweridentity may submit a new review result. - A failed verdict needs a blocking finding; a passing verdict cannot carry one.
- A failed review must carry every still-live prior finding id forward.
- Review is refused while a vetoed command lacks a fresh accepted observation:
any command observed at
broadscope, the feature's plan-listed validation, and the plan's gate command. Acceptance requires a pass except for an all-inspect plan'sgate-observecommand. - A
broadobservation must run the plan's gate command byte-for-byte, and may not select which tests it runs. - Final review requires a broad observation for current source. A
gatemust pass. An all-inspect plan may usegate-observeto accept its latest complete broad observation on the declared OS with a known exit code, even if nonzero. - Final review and
completedclosure require everyplan.evidenceentry to be satisfied on its declared OS.gate-observeuses the observation rule above;gateandextrastill require a pass. Feature reviews do not require every entry, so a goal can split by what this host can prove. - One revision per accepted mutation; an operation id replays exactly or conflicts. Validation observations replay by capture id, not operation id.
- Every mutation validates the whole schema and writes atomically under one cross-process lock.
- The validated command's exit code and output truncation flag, read from the host's own Shell metadata. A model cannot report these; a host that reports neither yields a durable never-passing observation rather than a silent pass.
- That the executed command's bytes equal the armed command.
- The host platform each observation ran on, normalized from what the runtime reports. A model cannot claim it, and an evidence entry naming an OS is satisfied only by an observation recorded on it.
- Which declared test cases the command reported passing, read from a JUnit report
the command wrote after Flow armed it. An entry naming cases is satisfied only when
each is reported
passed;skippedandabsentdischarge nothing, so exit zero for a case that never ran no longer counts (ADR 0012). - The workspace-content digest binding validation and review to source. It is a content fingerprint of tracked, non-ignored files — not a Git audit chain, and it cannot see an edit that reverts before persistence.
- The reviewer's agent identity on submission.
artifactsChanged. Flow validates bounded workspace-relative paths and labels them Flow-reported. It does not prove a path exists, changed, or is exhaustive.- The plan's gate command itself. Nothing decides whether a command is a test: a plan may declare a check that cannot fail. That decision is made at planning time, in the document the user approves.
- Feature
validationprose,targets,requirements, and closure summaries.
The runtime cannot enforce these judgments. Read the review before trusting its verdict.
- Goal alignment. Whether a request continues the same goal. Evaluated by
goal-change-refusedandcontinuation-acceptedinevals/. - Review substance. That the reviewer read the artifacts, completed the risk
checklist, and failed an unprovable claim instead of passing it conditionally.
unprovable-claim-refusedanddefect-fails-reviewput work in front of it that should not pass; neither can force the review path. - Reviewer independence. Without an explicit reviewer model from plugin options
configuration or
OPENCODE_FLOW_REVIEWER_MODEL, the reviewer shares the manager's model; independence rests on structure alone. - Evidence completeness. Whether an entry names the requested observation,
a suitable command, and the required platform. Plan approval and review judge
fitness. The runtime checks passage or accepted
gate-observeon the declared OS. - Scope discipline. That implementation stayed inside the approved plan, and that a worker wave respected its assigned paths.
- Honest reporting. That the closing summary matches what happened.
- A declared gate that cannot fail. See Caller-declared above.
- A suite that skips where no case names were declared.
assertions: []keeps the exit-code rule, which is the honest answer for a credential or a device and the remaining escape for a test result. See Caller-declared. - Plans saved before
plan.evidenceexisted. They declare none and keep the older, weaker rules:broadis the claimant's word, and no acceptance observation is owed. This build does not hydrategateorexternalEvidence. - Worker file boundaries beyond
.flow,.git, and Shell denial. Exact per-slice write paths are a prompt contract the manager audits afterward. /flow-autocontinuation across model turns, which depends on an unversioned host surface. Capability-gated and best-effort: see ADR 0008.
Who can break a run, and what each is up against.
- A misbehaving model. The manager runs with the user's own OpenCode
permissions by design, since it is the user's agent and Flow does not sandbox
it. What Flow enforces is that the lifecycle cannot be talked into existence.
An armed validation command runs byte-for-byte or the observation is
ineligible, the exit code and output-completeness flag come from the host's
Shell metadata, and only the reserved reviewer identity submits a review result.
The hidden worker and reviewer agents do get a deny matrix: no Shell, no
external directories, no skills, no delegation, no Flow lifecycle tools. The
reviewer cannot edit at all, and the worker cannot touch
.flowor.git. - A compromised host. Nothing. The host's own reports are the root of trust for exit codes, platform, and truncation, so a host that lies defeats every host-attested row above. Flow's answer is limited to failing visibly when the host reports nothing.
- User error at approval. The gate command and the evidence entries are approved with the plan, and their fitness stays caller-declared. A gate that cannot fail is a declared gate, not an enforced one.
Armed commands have no extra allowlist. Host permissions and plan approval govern their use. Flow guarantees byte-equality, not command safety. The Unenforced tier describes worker path limits.
Every close derives delivery.assurance from canonical closed state. It labels tiers
and limits, distinguishes supported/unsupported/unclaimed completion, marks legacy
gaps not applicable, and is neither persisted nor a correctness probability. See
ADR 0013.
delivery.handoff.externalActionAuthority is always not-granted; close handoff never
authorizes PR creation, merge, publication, or release work.
Every enforced row has a test; every judgment is evaluated or labelled unmeasured. That mapping is maintained by hand, not machine-checked. Eval false completion independently audits the document, while the paired benchmark measures hidden-graded correctness against ordinary OpenCode.
Release thresholds are in release qualification.
New nonterminal mutations reserve terminal capacity. Legacy full v5 sessions remain readable and can use the bounded extension except at revision exhaustion. Operation IDs remain intact. Extended archives support exact replay with a compatible reader. Terminal capacity defines the limits and downgrade boundary.
New failed reviews block inspection and change runs alike. Inspection reports and
approved evidence must pass review; product defects grant no repair authority.
Historical completed inspections with failed reviews remain readable with unsupported assurance.
These rules are runtime-enforced
and covered by tests/runtime-close.test.ts, tests/assurance-projection.test.ts,
and tests/session-capacity.test.ts.