> ## Documentation Index
> Fetch the complete documentation index at: https://kowshik-93.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Governance & gates

> The human-in-the-loop model — what's gated, what's autonomous, and what's never autonomous regardless.

`shipflow.config.md` → `governance` controls exactly how much shipflow does before checking in with
you. There are three independent layers, and they don't override each other — the strictest
applicable rule always wins.

## Layer 0 — profile (a preset for Layer 1)

```yaml theme={null}
profile: careful   # careful | balanced | yolo-safe
```

A named shorthand for the four gates below, so you don't have to hand-tune all four every time.
An explicit `gates` block always wins over `profile` — set `profile` for the default, or `gates`
for full control.

| Profile             | `after_context` | `after_plan` | `after_verify` | `before_workitem_update` |
| ------------------- | --------------- | ------------ | -------------- | ------------------------ |
| `careful` (default) | true            | true         | true           | true                     |
| `balanced`          | false           | false        | true           | true                     |
| `yolo-safe`         | false           | false        | false          | true                     |

No profile ever touches Layer 3 (`never_autonomous`) — push, open-PR, update-state, and merge
always need a human, at every profile.

## Layer 1 — gates (pause and wait)

```yaml theme={null}
gates:
  after_context: true
  after_plan: true
  after_verify: true
  before_workitem_update: true
```

Each `true` gate makes the orchestrator **stop and summarize**, waiting for your explicit approval
before continuing. A vague or silent reply is never treated as approval for a side-effecting phase.

<Tip>
  Setting a gate to `false` skips the *pause*, not the phase itself — `feature-verify` still runs
  and still produces a report; it just won't wait for you to read it before `feature-pr` proceeds.
  Layer 3 below still applies regardless of any gate setting.
</Tip>

## Layer 2 — autonomous (default: on, but logged)

```yaml theme={null}
autonomous:
  create_branch: true
  write_code: true
  run_tests: true
  commit: true
```

What the agent may do without asking, assuming no gate above stops it first — still recorded in
`.shipflow/{id}/state.json` either way.

## Layer 3 — never\_autonomous (absolute, no config can turn these on)

```yaml theme={null}
never_autonomous:
  - push_to_remote
  - open_pull_request
  - update_work_item_state
  - merge
```

These four always need a human, full stop — regardless of how the gates or autonomous settings
above are configured. There is no config combination that makes shipflow push, open a PR, move
tracker state, or merge without you saying so.

## Where each layer shows up

| Phase               | Gate                                                                          | Never-autonomous items it respects                               |
| ------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `feature-preflight` | — (BLOCKED halts before phase 1)                                              | —                                                                |
| `feature-context`   | `after_context`                                                               | —                                                                |
| `feature-plan`      | `after_plan`                                                                  | —                                                                |
| `feature-implement` | —                                                                             | — (branches + commits are `autonomous`)                          |
| `feature-tests`     | —                                                                             | — (commits are `autonomous`)                                     |
| `feature-verify`    | `after_verify`                                                                | Blocks `feature-pr` outright on a NOT READY verdict              |
| `feature-repair`    | requires an explicit human choice to run, then loops back into `after_verify` | branches + commits are `autonomous`, same as `feature-implement` |
| `feature-pr`        | gated regardless of config                                                    | `push_to_remote`, `open_pull_request`, `update_work_item_state`  |

Merging is never in scope for any phase — shipflow opens the pull request; humans review and merge
it, every time.

## NOT READY isn't a dead end

When `feature-verify` grades any AC PARTIAL or MISSING, the orchestrator does not silently stop —
it offers you a choice: run `feature-repair` (a scoped fix targeting only the cited gaps, then a
re-test and a full re-verify), defer the item, or fix it yourself. `feature-repair` never touches
an AC already graded MET, and if its own re-verify is still NOT READY on the same AC after one
attempt, it surfaces that as a blocker rather than retrying silently.

## Resuming

`.shipflow/{id}/state.json` (per `workspace.files.state`) records phase, status, and — per touched
repo in polyrepo — branch, commit progress, test result, and PR URL. If it exists when you invoke
`/shipflow` again, that's a **resume**: the orchestrator continues from the last incomplete phase
rather than redoing completed work. Run `/feature-status` any time — with or without a work-item
id — to see exactly where things stand before deciding to resume.