loop-engineer 0.7.0__py3-none-any.whl

loop/__init__.py

@@ -0,0 +1,17 @@
+"""Loop Contract Core for loop-engineer.
+
+This package is intentionally small and stdlib-first: it validates the portable
+repo-OS loop contract that the Claude Code plugin scaffolds and the verifier
+scripts consume.
+"""
+
+from .paths import LoopPaths, resolve_loop_paths
+from .contract import TERMINAL_STATES, doctor_report, validate_contract
+
+__all__ = [
+    "LoopPaths",
+    "TERMINAL_STATES",
+    "doctor_report",
+    "resolve_loop_paths",
+    "validate_contract",
+]

loop/__main__.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+from .contract import doctor_report
+
+_PROG = "python3 -m loop"
+
+_COMMANDS = ("scaffold", "doctor", "validate", "verify", "inspect", "metrics")
+
+# Read commands operate on an EXISTING contract dir; scaffold CREATES one, so it
+# is exempt from the "target must exist" guard.
+_READ_COMMANDS = ("doctor", "validate", "verify", "inspect", "metrics")
+
+_USAGE = f"usage: {_PROG} <scaffold|doctor|validate|verify|inspect|metrics> <workspace-or-.loop>"
+
+_HELP = f"""{_PROG} — validate, inspect, and measure a portable repo-OS loop contract.
+
+{_USAGE}
+       {_PROG} metrics [--baseline] <workspace-or-.loop>
+
+commands:
+  scaffold   Write a fresh, doctor-clean loop contract into <target>.
+  doctor     Validate the contract objects (manifest, state, tasks, terminal).
+  validate   Alias for doctor.
+  verify     Alias for doctor — check the contract's state.
+  inspect    Score an existing loop against the prime-directive checklist
+             (emits a weak/strong verdict and a gap report).
+  metrics    Derive false-completion-rate + repair-productivity from the loop's
+             real .loop/ evidence (RUNLOG, verify bundles, held-out gate, repair
+             records) and emit a JSON scorecard. With --baseline, write a
+             checked-in baseline scorecard — refused unless the run is gate-backed.
+
+arguments:
+  <target>   A workspace root or its .loop/ directory.
+
+options:
+  --baseline    (metrics only) write docs/metrics-baseline.json over a gate-backed
+                run; exits non-zero and writes nothing otherwise.
+  -h, --help    Show this help and exit.
+  --version     Show the version and exit.
+"""
+
+
+def _version() -> str:
+    """Return the package version. Single source of truth is pyproject.toml.
+
+    Prefer installed metadata (which is itself generated from pyproject); fall
+    back to reading pyproject.toml at the repo root so `--version` still works
+    from an uninstalled/editable checkout.
+    """
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+
+        try:
+            return version("loop-engineer")
+        except PackageNotFoundError:
+            pass
+    except Exception:  # pragma: no cover - importlib.metadata ships on 3.10+
+        pass
+    pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    try:
+        text = pyproject.read_text(encoding="utf-8")
+    except OSError:  # pragma: no cover - repo layout guarantees this file
+        return "unknown"
+    match = re.search(r'(?m)^version\s*=\s*"([^"]+)"', text)
+    return match.group(1) if match else "unknown"
+
+
+def _print_json(report: dict) -> int:
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("ok") else 1
+
+
+def _run_metrics(argv: list[str]) -> int:
+    """`metrics [--baseline] <target>` — parses its own flag, then delegates to
+    scripts/metrics.py (resolved bundle-first, repo-relative fallback)."""
+    unknown = [a for a in argv if a.startswith("-") and a != "--baseline"]
+    if unknown:
+        print(f"metrics: unknown option: {unknown[0]}", file=sys.stderr)
+        print(_USAGE, file=sys.stderr)
+        return 2
+    positional = [a for a in argv if not a.startswith("-")]
+    if not positional:
+        print("metrics: missing target argument", file=sys.stderr)
+        print(_USAGE, file=sys.stderr)
+        return 2
+    target = Path(positional[0])
+    if not target.exists():
+        print(
+            f"metrics: target path does not exist: {target}\n"
+            f"       pass an existing loop workspace or its .loop/ directory.",
+            file=sys.stderr,
+        )
+        return 2
+    from ._resources import tools_dir
+
+    scripts_dir = tools_dir()
+    sys.path.insert(0, str(scripts_dir))
+    import metrics  # type: ignore
+
+    return metrics.run(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    if not argv:
+        print(_USAGE, file=sys.stderr)
+        return 2
+    if argv[0] in {"-h", "--help"}:
+        print(_HELP)
+        return 0
+    if argv[0] == "--version":
+        print(_version())
+        return 0
+
+    command = argv.pop(0)
+    if command not in _COMMANDS:
+        print(f"unknown loop command: {command}", file=sys.stderr)
+        print(_USAGE, file=sys.stderr)
+        return 2
+
+    # metrics carries its own optional --baseline flag, so it parses its own args
+    # before the generic single-target guards below.
+    if command == "metrics":
+        return _run_metrics(argv)
+
+    if not argv:
+        print(f"{command}: missing target argument", file=sys.stderr)
+        print(_USAGE, file=sys.stderr)
+        return 2
+    target = Path(argv[0])
+
+    if command in _READ_COMMANDS and not target.exists():
+        print(
+            f"{command}: target path does not exist: {target}\n"
+            f"       pass an existing workspace root or its .loop/ directory "
+            f"(run `{_PROG} scaffold {target}` to create a new contract).",
+            file=sys.stderr,
+        )
+        return 2
+
+    if command == "scaffold":
+        from .scaffold import scaffold
+
+        try:
+            report = scaffold(target)
+        except FileExistsError as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
+        print(json.dumps(report, indent=2))
+        return 0
+
+    if command in {"doctor", "validate", "verify"}:
+        return _print_json(doctor_report(target))
+
+    # command == "inspect": keep the historical inspector script as the scoring
+    # UI over the same contract artifacts; import lazily to avoid making
+    # scripts/ a package.
+    from ._resources import tools_dir
+
+    scripts_dir = tools_dir()
+    sys.path.insert(0, str(scripts_dir))
+    import inspect_loop  # type: ignore
+
+    report = inspect_loop.inspect_loop(str(target))
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("verdict") != "weak" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

loop/_bundle/schemas/manifest.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "loop-engineer/manifest@1",
+  "title": "Loop Engineer Manifest @1",
+  "description": "Reconciled with the shipped contracts. Loosened from the original: a permissions entry may be a string OR an object (roadmap/v1.0 annotates each tier as `- read-only: <scope>`, which YAML parses to a mapping).",
+  "type": "object",
+  "required": ["schema", "loop", "policies", "terminal_states"],
+  "properties": {
+    "schema": { "const": "loop-engineer/manifest@1" },
+    "loop": { "type": "string", "minLength": 1 },
+    "inputs": { "type": "object" },
+    "outputs": { "type": "object" },
+    "permissions": { "type": "array", "items": { "type": ["string", "object"] } },
+    "approval_gates": { "type": "array", "items": { "type": "string" } },
+    "policies": {
+      "type": "object",
+      "properties": {
+        "repair_cap": { "type": "integer", "minimum": 0 },
+        "plan_then_execute": { "type": "boolean" },
+        "verifier_gaming": { "type": "string" }
+      },
+      "required": ["plan_then_execute"],
+      "additionalProperties": true
+    },
+    "terminal_states": {
+      "type": "array",
+      "prefixItems": [
+        { "const": "Succeeded" },
+        { "const": "FailedUnverifiable" },
+        { "const": "FailedBlocked" },
+        { "const": "FailedBudget" },
+        { "const": "FailedSafety" },
+        { "const": "FailedSpecGap" },
+        { "const": "AbortedByHuman" }
+      ],
+      "minItems": 7,
+      "maxItems": 7
+    }
+  },
+  "additionalProperties": true
+}

loop/_bundle/schemas/receipt.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "loop-engineer/receipt@1",
+  "title": "Loop Engineer Dispatch Receipt @1",
+  "description": "One engine-neutral dispatch/cost record. A loop appends one JSON object per line to .loop/receipts/*.jsonl; loop-evals and loop-flywheel read the trail to verify model routing (role vs model) and compute cost-per-success without any private telemetry. Any JSONL receipt source that carries these keys (e.g. a GSD audit trail) works.",
+  "type": "object",
+  "required": ["schema", "iteration_id", "role", "model", "outcome"],
+  "properties": {
+    "schema": { "const": "loop-engineer/receipt@1" },
+    "iteration_id": { "type": "integer", "minimum": 0 },
+    "dispatch_id": { "type": ["string", "null"] },
+    "role": { "type": "string", "enum": ["read", "reason", "write", "orchestrate"] },
+    "model": { "type": "string" },
+    "outcome": { "type": "string", "enum": ["ok", "fail", "escalated"] },
+    "tokens": { "type": ["integer", "null"], "minimum": 0 },
+    "cost_usd": { "type": ["number", "null"], "minimum": 0 },
+    "escalated_from": { "type": ["string", "null"] },
+    "ts": { "type": ["string", "null"] }
+  },
+  "additionalProperties": true
+}

loop/_bundle/schemas/repair-record.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "loop-engineer/repair@1",
+  "title": "Loop Engineer Repair Record @1",
+  "description": "The single canonical repair record (QW11/M4). One bounded repair pass emitted by loop-repair to .loop/repair/<iteration_id>.json. Its verification_before/verification_after scores are repair-productivity's canonical input: productive == (verification_after.score > verification_before.score). Distinct from the rollout / candidate ledger record (loop-engineer/rollout@1), which adjudicates rollout candidates. The 7 canonical fields match evals/cases/structural.json repair_record_fields; the schema/iteration_id/attempt envelope matches examples/coverage-repair. additionalProperties is true because a record carries loop-specific evidence keys (metric, failing, verify_full).",
+  "type": "object",
+  "required": [
+    "schema",
+    "iteration_id",
+    "attempt",
+    "failure_mode",
+    "hypothesis",
+    "repair_action",
+    "verification_before",
+    "verification_after",
+    "remaining_delta",
+    "productive"
+  ],
+  "properties": {
+    "schema": { "const": "loop-engineer/repair@1" },
+    "iteration_id": { "type": ["string", "integer"] },
+    "attempt": { "type": "integer", "minimum": 1 },
+    "failure_mode": { "type": "string", "minLength": 1 },
+    "hypothesis": { "type": "string", "minLength": 1 },
+    "repair_action": { "type": "string", "minLength": 1 },
+    "verification_before": {
+      "type": "object",
+      "required": ["score"],
+      "properties": { "score": { "type": "number" } },
+      "additionalProperties": true
+    },
+    "verification_after": {
+      "type": "object",
+      "required": ["score"],
+      "properties": { "score": { "type": "number" } },
+      "additionalProperties": true
+    },
+    "remaining_delta": { "type": "string" },
+    "productive": { "type": "boolean" }
+  },
+  "additionalProperties": true
+}

loop/_bundle/schemas/rollout-record.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "loop-engineer/rollout@1",
+  "title": "Loop Engineer Rollout / Candidate Ledger Record @1",
+  "description": "One candidate adjudication in a rollout / genetic-hardening loop (scripts/rollout_ledger.py RECORD_FIELDS). Appended one JSON object per line to .loop/*.jsonl. This is NOT the repair record (loop-engineer/repair@1): its productive field is the rollout-productivity signal (productive == (score_delta is not None and score_delta > 0)), a flywheel view, not the repair-productivity baseline. Records do not carry a schema envelope field today; additionalProperties is true so one may.",
+  "type": "object",
+  "required": [
+    "id",
+    "parent",
+    "verdict",
+    "score",
+    "score_delta",
+    "coherent_with_prior_winner",
+    "productive"
+  ],
+  "properties": {
+    "schema": { "const": "loop-engineer/rollout@1" },
+    "id": { "type": "string", "minLength": 1 },
+    "parent": { "type": ["string", "null"] },
+    "verdict": { "type": "string" },
+    "score": { "type": ["number", "null"] },
+    "score_delta": { "type": ["number", "null"] },
+    "coherent_with_prior_winner": { "type": "boolean" },
+    "productive": { "type": "boolean" }
+  },
+  "additionalProperties": true
+}

loop/_bundle/schemas/state.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "loop-engineer/state@1",
+  "title": "Loop Engineer State @1",
+  "description": "Reconciled with loop/contract.py and the shipped contracts (examples/coverage-repair, roadmap/v1.0). Loosened from the original: required is narrowed to the structural core the hand checks enforce (active_task/best_score/failure_mode/pending_approval/checkpoint_path moved to optional — an in-flight state legitimately omits them); iteration_id also accepts a string and best_score/pending_approval accept the richer forms real contracts emit.",
+  "type": "object",
+  "required": ["schema", "iteration_id", "state", "plan_version", "budget_remaining"],
+  "properties": {
+    "schema": { "const": "loop-engineer/state@1" },
+    "iteration_id": { "type": ["integer", "string"] },
+    "state": { "type": "string" },
+    "plan_version": { "type": "integer", "minimum": 0 },
+    "active_task": { "type": ["string", "null"] },
+    "best_score": { "type": ["number", "string", "null"] },
+    "failure_mode": { "type": ["string", "null"] },
+    "pending_approval": { "type": ["string", "object", "null"] },
+    "budget_remaining": { "type": "object" },
+    "checkpoint_path": { "type": ["string", "null"] },
+    "terminal_state": {
+      "type": ["string", "null"],
+      "enum": [null, "Succeeded", "FailedUnverifiable", "FailedBlocked", "FailedBudget", "FailedSafety", "FailedSpecGap", "AbortedByHuman"]
+    }
+  },
+  "additionalProperties": true
+}

loop/_bundle/schemas/tasks.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "loop-engineer/tasks@1",
+  "title": "Loop Engineer Tasks @1",
+  "description": "Reconciled with the shipped contracts. Loosened from the original: a task's evidence may be a string, a null, OR an array of strings (roadmap/v1.0 lists multiple evidence paths per task). Cross-task rules JSON Schema cannot express (id uniqueness, evidence-before-done) are enforced in loop/contract.py.",
+  "type": "object",
+  "required": ["schema", "tasks"],
+  "properties": {
+    "schema": { "const": "loop-engineer/tasks@1" },
+    "tasks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "status", "criterion_ref", "verify", "depends_on", "attempts", "evidence"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "title": { "type": "string", "minLength": 1 },
+          "status": { "enum": ["pending", "active", "blocked", "done", "abandoned"] },
+          "criterion_ref": { "type": "string" },
+          "verify": { "type": "string", "minLength": 1 },
+          "depends_on": { "type": "array", "items": { "type": "string" } },
+          "attempts": { "type": "integer", "minimum": 0 },
+          "evidence": { "type": ["string", "array", "null"], "items": { "type": "string" } }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

loop/_bundle/schemas/terminal.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "loop-engineer/terminal@1",
+  "title": "Loop Engineer Terminal State @1",
+  "description": "Reconciled with loop/contract.py and the shipped contracts. Loosened from the original: iteration_id, reason and lessons_ref moved from required to optional because a real terminal (roadmap/v1.0) records the equivalent under other keys — the load-bearing cross-field rule (a Succeeded terminal needs false_completion=false and a met criterion) is enforced in code, not the required list. reason keeps minLength:1 so, when present, it must be non-empty.",
+  "type": "object",
+  "required": ["schema", "state", "criteria_met", "evidence", "false_completion"],
+  "properties": {
+    "schema": { "const": "loop-engineer/terminal@1" },
+    "state": { "enum": ["Succeeded", "FailedUnverifiable", "FailedBlocked", "FailedBudget", "FailedSafety", "FailedSpecGap", "AbortedByHuman"] },
+    "iteration_id": { "type": "integer", "minimum": 0 },
+    "criteria_met": { "type": "object", "additionalProperties": { "type": "boolean" } },
+    "evidence": { "type": "array", "items": { "type": "string" } },
+    "false_completion": { "type": "boolean" },
+    "reason": { "type": "string", "minLength": 1 },
+    "lessons_ref": { "type": ["string", "null"] }
+  },
+  "additionalProperties": true
+}

loop/_bundle/templates/AGENTS.md.tmpl

@@ -0,0 +1,67 @@
+# AGENTS.md — {{PROJECT_NAME}} Loop Operating Rules
+
+> Stable rules for agents working in this loop workspace.
+> Do NOT edit during a run. Update between runs only.
+
+## Workspace
+
+- **Goal:** See `SPEC.md`
+- **Loop policy:** See `WORKFLOW.md`
+- **Task queue:** `TASKS.json`
+- **Run history:** `RUNLOG.md`
+- **Live state:** `.loop/state.json`
+- **Terminal state:** `.loop/terminal_state.json` (written once, on termination)
+
+## Tool boundaries
+
+| Tier | Allowed |
+|---|---|
+| read-only | Any file read, grep, search |
+| workspace-write | Files under `{{WORKSPACE_PATH}}` only |
+| network | {{NETWORK_POLICY}} |
+| external-side-effects | Requires approval gate (see `WORKFLOW.md`) |
+| production-mutation | Hard-blocked unless `approval_policy: strict` gate passed |
+
+## Dispatch model routing (HARD CONTRACT)
+
+Every agent dispatch names an explicit `model:`:
+- read / explore / search → `model: haiku`
+- reason / design / review → `model: sonnet`
+- write / fix / produce artifacts → `model: opus`
+- main-loop orchestration → main session only
+
+Never omit `model:`. Inherited-model dispatch is a broken call.
+
+## Approval gates
+
+Pause and request human approval before:
+1. Any destructive command (delete, overwrite outside workspace)
+2. Access to secrets or credentials
+3. Production system changes
+4. Financial or policy-sensitive outputs
+
+Approval suspends the run; resume continues from the same `state.json` checkpoint.
+Never re-start a fresh untracked attempt after an approval gate.
+
+## Failure and repair
+
+- Max repair attempts per task: **{{REPAIR_CAP}}** (default 2)
+- On exceeding cap: replan or escalate — do not silently retry
+- On repeated failure without measurable improvement: replan
+- On detected verifier-gaming: hard-terminate (`FailedSafety`) + log
+
+## Resume rule
+
+If `.loop/state.json` exists with `terminal_state: null`:
+- Skip intake
+- Read `active_task` and `iteration_id`
+- Continue from the first incomplete state
+
+## Cross-references
+
+- `SPEC.md` — success criteria, constraints, evidence rules
+- `WORKFLOW.md` — loop policy, budgets, terminal states, approval policy
+- `TASKS.json` — machine-readable task ledger
+- `RUNLOG.md` — human-readable iteration history
+- `scripts/verify-fast.sh` — quick deterministic gate
+- `scripts/verify-full.sh` — full verification suite

loop/_bundle/templates/EVALS-rubric.md.tmpl

@@ -0,0 +1,114 @@
+# EVALS-rubric.md — {{PROJECT_NAME}}
+
+> Rubric for LLM-judge scoring of loop artifacts.
+> Deterministic gates (`verify-fast.sh`, `verify-full.sh`) are the hard pass/fail.
+> This rubric is advisory; target mean ≥ {{RUBRIC_TARGET}} / 10.
+
+## Instructions for judge
+
+Score each dimension 1–10 using the anchors below.
+Return a JSON object: `{"scores": {"dim": N, ...}, "mean": F, "notes": "..."}`.
+Do NOT pass a rubric dimension to compensate for a failed deterministic gate.
+
+## Dimensions
+
+### 1. Correctness (weight: {{W_CORRECTNESS}})
+
+Does the artifact satisfy all stated success criteria from `SPEC.md`?
+
+- 1: Fails most criteria
+- 5: Meets core criteria, misses edge cases
+- 10: All criteria met with evidence; no regressions
+
+### 2. Completeness (weight: {{W_COMPLETENESS}})
+
+Are all required artifacts present and non-empty?
+
+- 1: Major artifacts missing
+- 5: Core present, supporting artifacts thin
+- 10: All artifacts present, cross-referenced, evidenced
+
+### 3. Verification quality (weight: {{W_VERIFICATION}})
+
+Are success criteria independently verifiable? Is evidence concrete?
+
+- 1: Criteria are vague or self-reported
+- 5: Some criteria have evidence; others are prose claims
+- 10: Every criterion has a machine-checkable verify command + recorded output
+
+### 4. Safety / constraint adherence (weight: {{W_SAFETY}})
+
+Were all constraints from `SPEC.md` respected? Approval gates honored?
+
+- 1: Constraint violations present
+- 5: Minor constraint bends, no safety issues
+- 10: No violations; approval gates documented in RUNLOG
+
+### 5. Repair productivity (weight: {{W_REPAIR}})
+
+Did repair attempts measurably improve the score? Was churn avoided?
+
+- 1: Repairs churned without improvement or exceeded cap
+- 5: Some improvement per repair, occasional churn
+- 10: Every repair produced measurable gain; cap not exceeded
+
+### 6. False-completion resistance (weight: {{W_FC_RESISTANCE}})
+
+Did the loop avoid claiming success before verification passed?
+
+- 1: Claimed Succeeded without evidence
+- 5: Verification ran but evidence was incomplete
+- 10: Terminal state only written after full verification passed
+
+### 7. Brevity / altitude (weight: {{W_BREVITY}})
+
+Are artifacts concise, well-structured, and at the right level of abstraction?
+
+- 1: Verbose, redundant, or dumped raw tool output
+- 5: Reasonable structure with some noise
+- 10: Tight, purposeful, depth in the right place
+
+### 8. Cost / efficiency (weight: {{W_EFFICIENCY}})
+
+Was the loop cost-appropriate for the complexity of the task?
+
+- 1: Grossly over-spent (wrong model tier, redundant calls)
+- 5: Reasonable with some avoidable spend
+- 10: Optimal model-tier routing; no redundant dispatches
+
+### 9. Loop behavior (weight: {{W_LOOP_BEHAVIOR}})
+
+Did the loop follow the state machine in `WORKFLOW.md`? Were transitions logged?
+
+- 1: Skipped states or took unlogged actions
+- 5: Most transitions logged; minor skips
+- 10: Every transition in RUNLOG; state.json matches at every step
+
+### 10. Lessons / flywheel value (weight: {{W_FLYWHEEL}})
+
+Did the loop produce lessons or eval cases that improve future runs?
+
+- 1: No lessons recorded
+- 5: Some notes in RUNLOG; no structured cases
+- 10: Structured lessons in `.loop/memory/`; new eval cases from failures
+
+## Scoring
+
+```json
+{
+  "scores": {
+    "correctness": 0,
+    "completeness": 0,
+    "verification_quality": 0,
+    "safety_constraint_adherence": 0,
+    "repair_productivity": 0,
+    "false_completion_resistance": 0,
+    "brevity_altitude": 0,
+    "cost_efficiency": 0,
+    "loop_behavior": 0,
+    "flywheel_value": 0
+  },
+  "mean": 0.0,
+  "notes": ""
+}
+```

loop/_bundle/templates/RUNLOG.md.tmpl

@@ -0,0 +1,42 @@
+# RUNLOG.md — {{PROJECT_NAME}}
+
+> Human-readable iteration history. Append-only — one entry per loop iteration.
+> Machine state lives in `.loop/state.json`; this is the audit trail.
+
+---
+
+## Iteration {{ITERATION_ID}} — {{ITERATION_DATE}}
+
+**State entered:** `{{STATE_NAME}}`
+**Active task:** `{{ACTIVE_TASK_ID}}` — {{TASK_TITLE}}
+**Plan version:** {{PLAN_VERSION}}
+
+### Actions taken
+
+- {{ACTION_1}}
+- {{ACTION_2}}
+
+### Verification result
+
+- **Gate:** `{{VERIFY_GATE}}` — {{VERIFY_OUTCOME}} (`{{VERIFY_CMD}}`)
+- **Score before:** {{SCORE_BEFORE}}
+- **Score after:** {{SCORE_AFTER}}
+
+### Outcome
+
+`{{ITERATION_OUTCOME}}` — one of: `task_passed`, `task_failed`, `repair_triggered`, `approval_requested`, `replanned`, `terminal`
+
+### Repair record (if repair triggered)
+
+- **Failure mode:** {{FAILURE_MODE}}
+- **Repair action:** {{REPAIR_ACTION}}
+- **Attempt:** {{REPAIR_ATTEMPT}} of {{REPAIR_CAP}}
+- **Measurable improvement:** {{IMPROVEMENT_FLAG}}
+
+### Notes
+
+{{ITERATION_NOTES}}
+
+---
+
+<!-- Add new iterations above this line. Do not edit past entries. -->