# Agent execution loop

Use this loop exactly. It is designed for a smaller model that can act well
when each decision is grounded in the previous command's output.

## 1. Orient

Read `README.md`, `STATE.md`, and the current task only. Inspect `git status
--short` before editing. Treat all pre-existing changes as user-owned.

State the current hypothesis in one sentence. A hypothesis must predict an
observable result, for example: "the linker cannot find `libxml2` because the
dynamic sysroot is absent from target link flags."

## 2. Choose the cheapest discriminating command

Run the smallest command that can disprove the hypothesis. Prefer, in order:

1. static inspection of one relevant file;
2. one unit test or one fixture build;
3. one runtime import test;
4. the focused suite;
5. the full suite only at a milestone gate.

Never rerun a long build unchanged. If a command failed, inspect its decisive
error first and change either the hypothesis or the implementation.

## 3. Classify the result

Use `DECISION-TREE.md`. Every failure must be classified before code changes.
If there is not enough evidence, gather more evidence rather than guessing.

## 4. Make one coherent change

Change the smallest architectural seam that removes the demonstrated failure
class. Do not add a package-name conditional to the generic builder. A package
patch belongs in an explicit recipe patch directory, with a comment explaining
the upstream assumption it replaces.

Use `apply_patch` for hand edits. Do not overwrite files with shell redirects.
Do not alter generated ABI files directly.

## 5. Verify in layers

Run the focused check that failed. If it passes, run the task's exit gate.
Compilation is never the final gate for an extension: install and import it in
the owned CPython runtime and exercise at least one native behavior.

## 6. Record and advance

Update `STATE.md` with compact evidence. If the task exit gate passes, set its
checkboxes, point `Current task` to the next task in `ROADMAP.md`, and continue
if budget remains.

## Stop conditions

Stop and request a user decision when:

- the next action requires credentials, deployment, paid infrastructure, or
  publishing outside the repository;
- fulfilling the task requires changing the ABI contract rather than fixing a
  consumer of it;
- an upstream license is unclear or incompatible;
- a destructive action, history rewrite, or discard of existing work appears
  necessary;
- the same failure class survives three evidence-driven attempts;
- a design choice changes public API or materially increases shipped runtime
  size without an already-stated budget.

When stopping, preserve logs and state the smallest exact decision needed.

## Escalation packet for the user

When a stop condition is reached, prepare a compact packet containing:

- intended invariant;
- exact command;
- final 80-150 relevant log lines;
- files and functions involved;
- three attempted hypotheses and what disproved each;
- the decision required.

Do not send entire build logs or the full repository history. Wait for the
user's decision, record it in `STATE.md`, and then resume this same loop.