Review code changes before push with no-mistakes

# no-mistakes `no-mistakes` is a local gate that validates your code changes through a pipeline (intent, rebase, review, test, document, lint, push, PR, CI) before they reach the configured push target. You drive it through the `no-mistakes axi` command family, which prints machine-readable [TOON](https://toonformat.dev) to stdout and progress to stderr. ## Active validation-step boundary A no-mistakes validation-step agent is already inside an active outer run. It must inspect, fix, and return only its assigned phase. It must never initialize, start, reattach, rerun, respond to, synchronize, abort, eject, or directly push a no-mistakes pipeline. Delivery requirements in user intent remain acceptance context, but the outer executor alone performs the other validation, push, PR, and CI phases. `NO_MISTAKES_GATE` is fast diagnostic evidence, not authorization by itself. The runtime combines managed Git identity with authenticated process ancestry. If a pipeline-control command returns `error.code: nested_gate_context`, stop immediately and return control to the outer executor. Safe inspection remains available through `no-mistakes axi status`, `no-mistakes axi logs`, help, and `no-mistakes doctor`. When the user invokes `/no-mistakes`, report the outcome at the end. If the user asks for something specific, translate that request into the matching `axi run` flags yourself - for example, "skip the lint step" becomes `--skip=lint`. Run `no-mistakes axi run --help` to see the available flags. ## Two ways to invoke `/no-mistakes` works in two modes, depending on whether the user hands you a task along with the command: - **Validate-only** - bare `/no-mistakes` (optionally with flag-style requests like "skip the lint step"). The user's code changes are already committed; validate them and report the outcome. - **Task-first** - `/no-mistakes <task>`, e.g. `/no-mistakes add a --json flag to the status command`. First carry out the task yourself, then validate the result through the pipeline: 1. **Check scope.** Inspect `git status` before you change or commit anything. Preserve unrelated pre-existing uncommitted changes, and when you commit, commit only the changes that belong to the user's task. 2. **Do the work.** Make the changes the task describes, then **commit them on a feature branch**. If the user is on the repository's default branch, create a feature branch first - the gate validates committed history on a non-default branch, so the work must land there before you run. 3. **Then validate**, passing the user's task as explicit intent. The task text is exactly what the user set out to accomplish, in their own words, so it *is* the intent - preserve requirements stated directly by the user, including constraints, exclusions, acceptance criteria, and later decisions; do not condense them into a diff summary or drop them while adding implementation context. Enrich it with the decisions and tradeoffs you made while doing the work (see [Intent is required](#intent-is-required)). ## Test-quality rule Never add a test whose only evidence is that it opens, reads, greps, parses, or snapshots implementation source code and finds or omits particular strings, tokens, lines, commands, function names, prompt phrases, regex matches, AST shapes, or incidental snapshots. That does not prove behavior: matching text can be dead or commented out, and a behavior-preserving refactor can change it. Instead execute a public or executable interface and assert observable behavior, state, output, side effects, and failure modes. For machine-consumed declarative artifacts such as workflow YAML, JSON, policy, .gitignore, or generated configuration, invoke the real consumer when feasible or parse into a typed or normalized semantic model and assert meaning. A raw substring or regex over the file is still the anti-pattern. Reading a file is legitimate when the file is itself generated public output, a serialized protocol, persisted state, an intentional snapshot, or another explicitly owned text or byte contract. Name that contract, and do not use its contents as a proxy that unrelated code works. A natural-language prompt or instruction is not proven effective because its source contains a sentence. Deterministic CI may test the final emitted prompt delivered to an agent as an intentional generated interface; model interpretation belongs in development-only evaluation, not live-LLM CI. Use an independent oracle: the expected result must come from somewhere other than the code under test, such as a specification, worked example, published constant, external contract, or independently justified property. Name the public behavior, the oracle's source, and a plausible wrong behavior the test would reject. Do not only check your own mocks, compare a result to itself, or copy the implementation's expected-value rule: a shared mistake can pass both sides. External-boundary mocks, constants, snapshots, and computed expectations remain legitimate when they check an independent contract. For a regression, reproduce the reported failure when feasible: the test should fail before the fix and pass after it. Everything below - preconditions, intent, the validate-and-decide loop - applies the same way once the work is committed on a feature branch. ## Before you start - The work you want validated must be **committed** on a branch. The gate validates committed history, not your uncommitted working tree. - You must be on a **feature branch**, not the repository's default branch. - The repository must already be initialized with `no-mistakes init`. - The daemon must have a runnable configured pipeline agent: a supported native agent binary, the `agent: cursor` or `agent: devin` ACP alias, or an explicit `acp:<target>` through `acpx`. You are the AXI driver, not an implicit pipeline-agent backend. If none is available, the run fails before its first step; `no-mistakes doctor` reports the configuration problem. If any of these is not met, `axi run` returns an `error:` with the exact command to fix it - read it and act on it (commit your work, or create a branch). If the repository is not initialized, run `no-mistakes init` first; if the `no-mistakes` command itself is missing or misbehaving, `no-mistakes doctor` reports what is wrong. Before starting, run `no-mistakes axi` (home view). If it shows an active run on your current branch, inspect it with `no-mistakes axi status`. If it is parked at a gate, drive it with `no-mistakes axi respond`. Reattach an in-flight run by re-running `no-mistakes axi run` when it still matches your current `HEAD` - either as the submitted head or as the current pipeline head. Only `no-mistakes axi abort` it when you mean to discard that run before starting over; aborting is a between-runs action, never a way to take over or bypass a gate while a run is still going (see [Validate and decide](#validate-and-decide)). If it shows an active run on another branch, leave that run alone and start validation for your current branch with `no-mistakes axi run --intent "..."`. ## Intent is required When you start a new run you must supply explicit intent through exactly one of `--intent TEXT`, `--intent-file PATH`, or `--intent -` (stdin until EOF): **what the user set out to accomplish** - the goal or request behind this work, in their terms. This is not a description of the diff or the files you changed; it is the objective the change is meant to achieve. You know it from the conversation, so pass it directly - no-mistakes uses the supplied intent instead of inferring it from local agent transcripts. Empty or whitespace-only input is rejected, never inferred. For input handling, whitespace preservation, and reattachment semantics, see the [CLI intent input reference](https://kunchenguid.github.io/no-mistakes/reference/cli/#intent-input). Err on the side of completeness, not brevity. The review step uses explicit intent to tell a deliberate decision apart from a mistake, so a thin one-line summary makes it flag things the user already chose. Capture the nuance: the user's goal, the specific decisions and tradeoffs they made along the way, any constraints or approaches they ruled in or out, and anything they explicitly asked for that might otherwise look surprising in the diff. A few sentences to a short paragraph is normal - write down what you learned from the conversation that a reviewer reading only the diff would not know. ## Validate and decide Run the pipeline and decide on its findings as they come up: 1. Start the run. It blocks until the first decision point or the end: ```sh no-mistakes axi run --intent "<what the user set out to accomplish>" ``` `axi run` and every `axi respond` block synchronously - the review, test, and CI steps can each take **several minutes**, so a single call may not return for a while. That is normal; do not cancel or re-issue the command because it seems slow. Both commands default to `--wait 8m` so a harness with a 10-minute tool cap gets a structured return instead of an unbounded hang. If the command returns because that wait elapsed, it is not a failed run and does not mean the daemon is dead: inspect with `no-mistakes axi status` and re-run `axi run` or `axi respond` to reattach. A slow live daemon is retried after a health probe rather than treated as I/O failure. To check progress without disturbing the run, use `no-mistakes axi status` from a separate call. A long-running call is working, not stalled - background it if your harness needs to, but the run **never advances past a gate on its own**. Read every return; on a `gate:`, respond; loop until an `outcome:`. Never idle-wait for the run to move forward by itself. When that status output includes `awaiting_agent: parked <duration>` under the run, the run is parked at an approval or fix-review gate and waiting for you to send `axi respond`. The field is observability only: it does not change gate resolution, auto-resume the run, or make `--yes` the default. While a step is actively `running` or `fixing`, `axi status` may include `active_steps` with step-scoped `active_for`, current-round `round_active_for`, `last_activity`, a native `agent_pid` when a subprocess agent is running, and the current round such as `round 1`, `auto-fix 1/3`, or `fix 2`. If `last_activity` is prefixed with `quiet`, no step log or native-agent lifecycle activity has arrived for longer than `step_quiet_warning`. Treat that as a liveness clue, not as permission to cancel, rerun, or edit the worktree yourself. 2. If the output contains a `gate:` object, the pipeline is waiting on you. Read its `findings` table. Each finding has an `id`, `severity`, `file`, `description`, and an `action` that tells you how the pipeline classified it: - `auto-fix` - mechanical and low-risk; you can authorize the fix on your own judgment by responding with `--action fix`. - `no-op` - informational only; nothing to do. - `ask-user` - the finding challenges the user's deliberate intent or touches product behavior. This is a call only the user can make - see [Escalate `ask-user` findings](#escalate-ask-user-findings) below. **Review auto-fix is disabled by default** (`auto_fix.review: 0`; a repo or global `auto_fix.review > 0` override re-enables it), so blocking and ask-user review findings park for your decision rather than being silently self-fixed. (Other steps such as test and lint may auto-fix within the pipeline and re-run before they ever gate.) Choose one response: ```sh # accept the step as-is and continue no-mistakes axi respond --action approve # have the pipeline fix specific findings, then continue no-mistakes axi respond --action fix --findings <id1,id2> --instructions "<optional guidance>" # skip this step no-mistakes axi respond --action skip ``` While a run is active, never fix findings by editing the code yourself - the pipeline owns both the findings and the fixes. Your job at a gate is to decide and respond; `--action fix` has the pipeline apply the fix and re-review the result. For the same reason, while a run is active do **not** `abort` or `rerun` to go fix a finding yourself - even a real bug in your own code - because that discards the pipeline's in-flight work and forces a full re-validation. `abort` and `rerun` are for *between* runs (after a `failed` or `cancelled` outcome), never to circumvent a gate. Each `respond` blocks until the next `gate:`, `checks-passed` decision point, or final outcome, subject to the same default `--wait 8m` hold. A review gate whose findings are `question-<id>` rows is waiting on answers to its reviewer's questions, not on a verdict: answer each with `no-mistakes axi answer --question <id> --answer "<one of its options>"` instead of approving or fixing. The answer that closes the last open question blocks exactly like `respond` and returns the next `gate:` or outcome; any other answer returns at once. Extra flags on `respond`: - `--wait` bounds the hold (default 8m). - `--reason "the operator's explanation"` records an explicitly authorized Test exception with `--step test --action approve`. This does not grant approval authority; escalate ask-user findings as before. Without a reason, Test approval remains effective; an approval past a failing command, `no-go`, or `inconclusive` verdict is reported as an exception with no operator reason supplied. - `--add-finding '<json>'` (with `--action fix`) folds a finding you spotted yourself - one the pipeline did not surface - into the fix round, as a JSON finding object. Use it for a problem you noticed that is not in the gate's own `findings` table. - `--step <name>` responds to a specific step instead of the one currently awaiting approval. You rarely need this; omit it to answer the active gate. 3. Repeat step 2 until the output has an `outcome:` instead of a `gate:`. The outcomes are: - `checks-passed` - the change is validated and CI is green (or the trusted default-branch config declares `no_ci: true` and no checks are registered - the help line names that declaration when it applies), but the PR is not merged yet. **You are done driving the pipeline.** Do not wait for the merge: tell the user the PR is ready and ask them to review and merge it (the PR link is in the `help` line). A generic empty forge check list without that declaration is not ready. no-mistakes keeps monitoring the PR in the background until it is merged, closed, or its configured idle timeout elapses, so a human can watch it in the TUI. - `passed` - the pipeline completed under the requested steps, including any explicit per-run skips. This alone is not evidence that a PR was merged. - `passed-with-override` - the pipeline completed with an explicitly approved Test exception or CI failure. Report the exception, not a clean pass. Test evidence is in `run.test_override_reason`, including when CI readiness returns `checks-passed`; do not omit it from the summary. - `passed-with-skips` - publication or CI verification automatically skipped. Report the missing evidence and its cause from `run.automatic_skips`, bound to the full `run.head_sha`. This is neither CI readiness nor a failing code verdict. Explicit per-run skips retain their existing behavior. - `failed` or `cancelled` - they did not; read the output and address it. Follow the custody guidance below before fixing whatever the output points at (a failing test, a lint error, a finding you skipped). Commit the fix on the same feature branch, then submit it with `no-mistakes axi run --intent "..."`. A fresh run or `rerun` is a *between-runs* action, correct only after a terminal outcome like this - never mid-run to circumvent a gate. Do not leave the user at a `failed` outcome without either retrying or explaining what blocks it. `no-mistakes rerun` keeps its existing head selection: the gate head, or the latest terminal run's verified unpublished preserved head while custody remains outstanding. If a known clean caller `HEAD` differs from that selected head, it refuses before starting or superseding any run and reports both full SHAs. It never substitutes the caller head or moves either branch to make them match. On refusal, inspect `no-mistakes axi status` and follow the custody guidance below. Dirty callers and callers without clean-head evidence retain existing selection behavior. Before any post-pipeline local commit or fresh run, read the structured `branch_sync` object returned by AXI home, status, or a drive result. Only when its `next_action.code` is `sync`, run `no-mistakes axi sync` first. That guarded sync may be a strict fast-forward or a content-equivalent diverged advance that anchors the pre-sync head before moving the branch with reset semantics; genuine divergence stays blocked. If it reports `next_action.code` is `continue_active_run`, the pipeline still owns the branch: run the reported command, keep driving the active run, and do not make local follow-up commits. When `next_action.code` is `recover_custody`, run its exact `next_action.command` rather than reconstructing one. That is `no-mistakes axi sync --recover` to take a still-available preserved pipeline head, or `no-mistakes axi sync --recover --keep-local` in two keep-local cases: when an accessible gate confirms the verified preserved head is missing and you are explicitly discarding those unpublished commits, or when a bound archive proves divergent later work remains preserved while recovery keeps the branch at the exact reported required head and never selects, merges, or replays the archive. Do not substitute plain `--recover` or `rerun` for a reported keep-local action. `no-mistakes rerun` can resume validating a still-available ordinary preserved head instead, subject to the clean-head check above. Ordinary recovery takes that head by fast-forward, or by adopting a diverged preserved head proven to carry every local change - the ordinary result of the pipeline rebasing your commits onto a newer base - after anchoring your pre-recovery head under `refs/no-mistakes/recover-local/<run>`. The ordinary containment proof is deliberately narrow, so a rebase whose fix rounds also rewrote your own lines refuses instead of being adopted: when nothing can tell a deliberate pipeline fix from a dropped change, the decision is yours. When `next_action.code` is `recover_remote_rewritten`, the configured push target was force-rewritten outside the pipeline after a terminal run: run exact `no-mistakes axi sync --recover`. It re-verifies the live target, anchors the superseded pipeline head under `refs/no-mistakes/recover-rewritten/<run>/<generation>`, and rebinds only the recorded push binding to the verified live head; it never moves your branch, the gate, or the remote. It refuses `--keep-local`, a live head or target that changes during recovery, a head it cannot anchor, and a merged or closed PR. Afterwards follow the ordinary `next_action` it reports. When `next_action.code` is `adopt_published`, a custody-returned branch was rebased after its gate lane stopped moving: run `no-mistakes axi sync --adopt-published`. It verifies the configured push target already has the exact rebased local head, preserves the old lane head, and updates only that stale gate lane. If the target differs or changes during verification, it refuses without replacing the lane. A `branch_sync.state` of `user_owned` means the run went terminal before changing the submitted head and cancellation released the branch: the exact branch and head are yours and immediately usable for whichever delivery path is authorized - no sync action is needed, and a repeated `--recover` there is a harmless no-op. A dirty worktree, or divergence that cannot be proven contained, makes the recovery refuse with explicit choices; `--keep-local` keeps your current head while the preserved commits stay anchored under `refs/no-mistakes/recover/<run>`. The same flag is the recovery when an accessible gate confirms that the verified preserved head is missing and recovery refs are compatible: it returns custody at the current local head without requiring that object. If synchronization is blocked, process that structured state instead of improvising reset, stash, merge, rebase, force, or branch replacement. After synchronization, commit the follow-up on top and re-run `no-mistakes axi run --intent "..."` with the original user intent. This preserves every prior gate-fix commit regardless of its configured subject. The CI step deliberately keeps watching the PR after checks pass, so `axi run` returns `checks-passed` the moment checks are green (or a trusted `no_ci: true` declaration covers a zero-check repository) rather than blocking on the human merge. Never poll or re-run waiting for the merge yourself. Never treat "no CI checks reported" alone as green. Because that monitor stays live, a PR that falls behind the default branch or hits a merge conflict after checks pass - commonly because another PR merged first - needs **no command from you**: never hand-rebase. When the CI monitor sees an actual conflict it **rebases onto the base, resolves it, revalidates from Review because rebasing cannot prove continuity with the reviewed head, and re-pushes the branch through Push**; a PR that is merely behind but still clean needs nothing either, since the platform merges it. The one exception is when that monitor is no longer running - the PR was closed, the run was aborted or superseded, it idle-timed-out, or its auto-fix attempts were exhausted - in which case recover with `no-mistakes rerun`, subject to the clean-head check above. An accepted rerun cancels the stale monitor and re-runs the full pipeline including a deterministic rebase step. Do **not** reach for `no-mistakes axi run` to refresh a still-active PR: after `checks-passed` it reattaches to the running monitor (HEAD unchanged) and returns its output without rebasing. On a successful outcome (`checks-passed` or `passed`), close the loop with the user: summarize what happened during the pipeline in a concise, easily readable format - what was validated and what was found. If the output includes a `fixes` table, the pipeline fixed findings your original change missed: acknowledge those misses and explicitly list each fix so the user can easily review them. ## Escalate `ask-user` findings A gate whose findings are all `auto-fix` or `no-op` is safe to drive on your own judgment: respond with `--action fix` or `--action approve` as appropriate. But a finding marked `ask-user` is a decision that belongs to the user, not you - the pipeline flagged it because it challenges their deliberate intent or changes product behavior. Do not approve, fix, or skip it on your own. Instead, stop and bring it to the user before you respond: - Relay each `ask-user` finding to them as the pipeline wrote it - its `id`, `file`, and full `description` verbatim. Do not paraphrase, summarize away the detail, or pre-judge the answer. - Ask how they want to proceed, then translate their decision into the matching `respond` call: `--action fix` (pass their guidance through `--instructions`), `--action approve`, or `--action skip`. The exception is `--yes` (below): it is the user's standing consent to drive eligible gates unattended, so under `--yes` you resolve ordinary `ask-user` findings automatically instead of stopping to ask. If you have clear consent to drive the run automatically, pass `--yes` to `axi run` or `axi respond`. For eligible gates, it treats actionable findings - `auto-fix` and `ask-user` alike - as consent to fix it, selects every current finding for one fix round, accepts the resulting fix review, and approves gates with only `no-op` findings. Only use it when the user has asked you to drive the whole run without checking back. A `protected-path-refusal` gate still requires an explicit operator response under `--yes`. Relay its path and rule; do not automatically fix, approve, or skip it. Approval is rejected. Have the operator inspect and resolve the reported edit, then send `--action fix` to retry the unfinished step. The [protected-path reference](https://kunchenguid.github.io/no-mistakes/reference/repo-config/#protected_paths) owns the staging guard's scope and limitations. A `test-agent-unvalidated-work` finding means a timed-out Test agent left commits or changes no Test turn validated. Approval is rejected, so `--yes` stops at that gate without responding. Relay what the finding names and do not skip Test, which would publish that work. Ask the operator to choose: `--action fix` spends another agent budget to validate the work, and `no-mistakes axi abort` stops the run. ## Inspecting state ```sh no-mistakes axi # home view: current branch, active runs, next steps no-mistakes axi status # full detail plus cached branch_sync when relevant no-mistakes axi sync --check # freshly verify an offered synchronization plan no-mistakes axi sync # apply only an offered guarded synchronization no-mistakes axi sync --recover # return custody after a terminal run left unpublished pipeline commits no-mistakes axi sync --adopt-published # adopt an exactly published rebased head into its stale gate lane no-mistakes axi logs --step <name> --full # one step's recorded findings, complete summary, and full log no-mistakes axi abort # cancel the current-branch active run