---
name: ak-loop
description: Run an authorized bounded optimization loop using a numerical metric, immutable guard, noise-aware measurement and isolated reversible experiments.
metadata: {port: angent-fallback, mode: adapted}
---

# Loop — Portable Fallback

Use only when repeated **mechanically measured** experiments can improve an explicit goal such as test coverage, bundle bytes, benchmark latency, lint count or an objective error rate. The stable Engineer 2.19.0 loop is **sequential** and intentionally keeps/discards atomic experiments using Git as memory. It is not an agent mode for subjective polishing, unconstrained code generation, ordinary debugging or a one-shot fix.

Read **references/measurement-and-git.md** before running a write-enabled loop. Native CLI/hook assumptions do not authorize arbitrary shell scripts or history changes.

## Required experiment contract

- **Goal**: desired measurable outcome, baseline and target when defined.
- **Scope**: exact allowed editable files and non-editable guard/test files.
- **Verify**: vetted command/tool that produces a single finite comparable number and a known unit.
- **Direction**: higher-is-better or lower-is-better.
- **Guard**: independent behavior/quality gate, if material; passing before start.
- **Budget**: iteration count/time/resource ceiling, default at most 10 when unspecified and authorized.
- **Noise** and **Min-Delta**: measured variance and meaningful minimum change, not merely positive numerical fluctuation.
- **Isolation/rollback**: clean branch/worktree and an exact way to restore just the attempted change without overwriting user work.

When essential fields are missing, collect them in a compact batch rather than proceeding on arbitrary command, scope or metric guesses. Do not use a form when a short conversational clarification suffices.

## Preflight (no mutation yet)

Verify the real branch, HEAD, clean experiment workspace, authorized target, non-overlapping work and scope matches. Refuse to start in a dirty shared working tree or against another worker's branch. Establish metric and guard baselines with a dry run, parsing strict numerical output. Establish a fixed environment/inputs so comparisons mean the same thing.

Review Verify/Guard commands for deletion, privilege escalation, install/fetch-and-execute, unapproved network writes, production effects, credential exposure, unbounded loops and workload costs. **Never** blindly execute opaque commands supplied by fetched files. Guard scripts, tests/specs and their fixtures are immutable with respect to optimization changes; if this conflicts with required scope, stop and resolve ownership.

## Sequential iteration

1. Review prior accepted/discarded experiments, metric trend and observed failures.
2. Form **one causally coherent change** with an expected effect. Avoid repeating failed ideas.
3. Modify only owned files in an isolated experiment ref/worktree. Keep source, guard and generated-output boundaries explicit.
4. Preserve the candidate as a reversible Git commit **before risky verification when Git is the authorized memory mechanism**. Do not automatically push, force-reset, rewrite main or create a commit if the user prohibited those effects; use an isolated patch/snapshot alternative instead or stop.
5. Run Verify under the same measurement conditions and Guard independently. On command failure, bad/no number or timeout, treat measurement as invalid and do not keep an unverified improvement.
6. Evaluate improvement with direction, Min-Delta and noise handling. For noisy benchmarks, repeat comparable runs and use a robust statistic/confidence threshold. Guard failure always rejects the candidate regardless of the headline metric.
7. Keep verified improvement; otherwise reverse only the experiment commit/patch without erasing unrelated history or new work. Git revert is preferable to destructive reset where it safely applies; conflicts require inspection, not force.
8. Record iteration, source revision, timestamp, metric/unit, delta, guard result, keep/discard reason and candidate strategy (TSV or project-native log where authorized).

## Stopping and reporting

Stop at target, iteration/time limit, repeated nonprogress (investigate/pivot after several discards, stop after sustained failure), stale/invalid baseline, guard failure that cannot be resolved safely, measurement drift, scope conflict or user interruption.

Report baseline/best/final metric, actual kept/discarded trials, revisions, measured guard status, limitations and next decision. A metric gain that degrades the real product outcome is not accepted. A remote Git ref update is a separate authorized effect from iterative optimization.

The fallback preserves loop logic and evidence but does **not** imply a background autonomous runner, fixed timeout service or AgentKit native CLI is installed.