Gates and rules

Ark gets its autonomy from its gates, not despite them. Every gate below exists because skipping it has already burned us at least once.

Person gates (non-negotiable)

Align	A person confirms problem, outcome, metrics, and constraints and sets `status: aligned` before `os run` will execute. The cheapest correction point in the whole lifecycle.
Merge	Builders never merge. Every MR is reviewed and merged by a person, on every repo.
Accept	A person reviews the Verifier's measured verdict before an intent may be marked proven.
Architecture	Work touching auth, secrets, payments, or tenant isolation always runs lane `full` with person architecture sign-off.

Delivery gates for customer-bound fixes

For fix and full lanes shipping code a customer will run. Both gates were written after a real incident: a defect fix passed its Apex test gate while the customer's actual UI flow still failed, and QA bounced the ticket.

Gate 1: the fix is verified on an org

A green unit or Apex gate is necessary but never sufficient. The fix is deployed to a scratch org seeded with customer-shaped data, and the original reported reproduction is re-run through the same surface the customer used: the UI flow, the API call, the wizard path.

Read-only access to a shared QA org is for probing only. If the runner lacks scratch-org capability, the environment doctor says so. The answer is to fix the environment or hand verification to a runner that has it, never to skip the doctor.

Gate 2: the MR carries a SIT handover

The intent declares its pre-release checks in a verification.pre_release block. os verify-pre-release runs them and writes the SIT report. The MR description then carries the full QA handover, self-sufficient for reviewer and QA alike:

what was tested and the verdict, per layer
on which org and dataset, with the seeding recipe named
a decision table for anything reconciled during review
honest outstanding scope: what was not tested, and why

On combo branches carrying several tickets in one MR, each absorbed ticket appends its handover to the same description, so the MR always reflects the tested state of the whole branch.

Board rules

No single-ticket intents

A defect ticket joins its per-release patch-family intent, or the standing patch line. Lint-enforced: the board index fails on an active intent scoped to one defect. See Intents, not tickets.

Residuals return to the family

When QA reopens a ticket that an intent already owns, the residual work goes back to that intent, on the same branch and MR. It never mints a new board entry.

Granularity exceptions are owner-gated

A granularity_exception in front matter is a request, not a waiver. It requires board-owner sign-off recorded in the run log before the run starts.

Folded intents stay readable

Superseded intents keep their spec as grounding and carry a machine-readable superseded_by pointer, lint-enforced, so every fold leads the reader to the surviving outcome.

The artefact, not chat history, is the durable state

Decisions, evidence, and verdicts live in the intent spec's append-only run log. If it is not in the artefact, it did not happen.

Where the rules live

The enforceable versions of these rules are Cursor rules in the kaptio-ark repo (.cursor/rules/), loaded by every agent working there. This site is the readable mirror; when the kernel or the rules change, the changelog here changes with them.