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)

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)

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.

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.

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

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)

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.