> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orkestral.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Proven delivery

> Done is proven, not claimed. The deterministic gates that actually run before any issue is marked complete.

Every agent wants to say it finished. Orkestral does not take its word: it **proves** it.
Before an [issue](/en/issues) is completed, deterministic gates run for real and block
hollow work, even if the agent swears it passed.

## Why this matters

Without these gates, an agent can mark a task as "done" with no code, write a route in the
wrong place, or fake a "QA passed" without running anything. The result looks ready and is
not. The gates below make "done" verifiable.

## The gates

<CardGroup cols={2}>
  <Card title="The build really runs" icon="hammer">
    QA validation runs `npm run build` (or the stack's typecheck) and reads the exit code.
    If the build fails, the verdict becomes rejected and the real error is attached. The
    agent's word does not override the exit code.
  </Card>

  <Card title="No phantom code" icon="ghost">
    A code issue that finishes without changing a single file is not marked "done": it is
    marked unverified, with a warning. Claiming done with no diff does not count.
  </Card>

  <Card title="Files in the right place" icon="folder-tree">
    In a Next.js project, a route outside `app/` is ignored by the framework, so the route
    does not exist. QA rejects orphan route files with a list of what to move.
  </Card>

  <Card title="A base that already builds" icon="layer-group">
    Greenfield projects start from the official scaffolders (Next 15, React 19, Tailwind v4,
    shadcn/ui). Setup escalates once to the premium, which runs the real CLI, instead of the
    local model writing a half-finished base.
  </Card>
</CardGroup>

## The Capsule contract

Every [Capsule](/en/capsule) carries a **contract**: predicates the machine checks after
execution, with no model cost.

| Predicate         | What it checks                              |
| ----------------- | ------------------------------------------- |
| `file_contains`   | The requested symbol appears in the file.   |
| `imports_intact`  | No top-level import was removed.            |
| `no_shrink`       | The file did not shrink beyond expectation. |
| `build`           | `npm run build` / typecheck passes.         |
| `route_placement` | Routes live under `app/`, not orphaned.     |

<Note>
  The cheap asserts are guard-rails: they catch regression (symbol gone, imports eaten),
  they do not prove behavior. The hard proof of behavior is the **build gate in QA**, which
  runs the real build and rejects if it breaks.
</Note>

## The decision machine: retry local, escalate premium, conclude

When a run fails validation, the error is fed back and the Forge tries again, now with the
matching pitfall. If it persists, it escalates to the premium model, which receives the
history (what it tried, in which tier, which error) and re-compiles the Capsule instead of
starting from scratch. Only when the contract passes is the issue completed.

```mermaid theme={null}
flowchart TD
    R["Forge executes"] --> V{"Contract<br/>passed?"}
    V -->|yes| D["Completed<br/>and proven"]
    V -->|no| L["Feeds the error<br/>back as a pitfall"]
    L --> R
    L -.->|attempts exhausted| P["Escalates to premium<br/>with the history"]
```

## Where you see it

* On the [issue](/en/issues): system comments mark rejections, pitfalls and the QA verdict.
* In [code review](/en/code-review): the final review on the epic checks the whole set before the merge.
* In [logs and observability](/en/observability): each gate shows up in the execution trace.

## See also

<CardGroup cols={2}>
  <Card title="The Capsule" icon="cube" href="/en/capsule">
    How intent becomes a unit with a verifiable contract.
  </Card>

  <Card title="Approvals" icon="circle-check" href="/en/approvals">
    When work needs your OK before it proceeds.
  </Card>
</CardGroup>