Looptimal

from objective to verified outcome

CI License: MIT GitHub stars Skill Audit

Most "autonomous agent" failures aren't prompt problems. They're missing-loop-component problems: no durable state, no objective gate, no stop condition, the maker grading its own work. Looptimal fixes that at two levels.

No clone required — this runs the real Stage-6 outer verifier against a fixture, tampers with the fixture, and confirms the tamper is caught:

uvx --from git+https://github.com/Renn-Labs/Looptimal@v2.2.0 verify-outcome --selftest

SELFTEST GREEN

That single line is the whole pitch: an honest bundle round-trips GREEN, then the same fixture is tampered (the artifact the loop claims to have fixed is reverted) with contract_hash left untouched — and the outer verifier catches it. A maker's self-reported GREEN can't buy a pass here; only a live re-check can. This is why maker ≠ checker isn't a slogan in Looptimal — it's the literal thing verify-outcome.py does on every run, including this one.

From a checkout, the offline teaching demo at examples/first-30-minutes/ is a controlled maker/verifier demonstration: a deliberately induced RED on a frozen candidate defect (wrong source_manifest_sha256 in stale-candidate.json; the verifier recomputes the digest from the immutable source pin — it does not branch on attempt number), durable state, a resume that repairs that invariant and binds the prior RED evidence once, a validated product outcome receipt before ACCEPTED, and one honest terminal (ACCEPTED, EXHAUSTED, or BLOCKED) bound to internal run provenance digests. "First 30 minutes" is an operator budget, not a measured wall-clock guarantee — and not external customer proof, demand evidence, or a ship-to-production seal. Independent maker≠checker product approval is outside this demo; the embedded subprocess is not that authority.

bash examples/first-30-minutes/run_demo.sh

Read that example's README before treating any file as acceptance: attempt evidence (kind: attempt-evidence) is not an accepted outcome receipt (looptimal-receipt.json from scripts/verify-outcome.py, validated before ACCEPTED is committed). An install/doctor verdict is a third thing. Missing or unresolved source pins fail closed as BLOCKED — the demo never silently falls back to main.

At the loop level, it refuses to blueprint a loop until all four atoms are real:

Plus one rule that ties them together: maker ≠ checker — nothing is "done" until something other than the thing that produced it says so.

This isn't a hunch. SpecBench measures reward hacking as the pass-rate gap between a coding agent's visible validation tests and a held-out set covering the same requirements, and finds that gap widens ~28 percentage points for every ×ばつ increase in code size — even as agents saturate the visible suite. ImpossibleBench found cheating rates as high as 76% when test files are visible (even mutated), dropping to near zero once they're simply hidden from the model. And Cursor's own SWE-bench Pro study found 63% of Opus 4.8 Max's "successful" resolutions had been retrieved from git history or the public web rather than derived. A maker that can see or grade its own gate will, on average, find the gate — not the fix.

At the outcome level, Looptimal goes further: it frames a sealed acceptance suite, picks or rejects the right loop archetype, war-games the plan before you commit, dispatches maker and checker agents, and re-runs the sealed suite against live state before anything is called done. "Done" means the outcome is proved against live state by a separate verifier — not asserted by the agent that did the work.

The loop-design wizard (formerly the standalone LoopPrint) is embedded as Stage 2: Design-loop. It also runs as a direct fast-path when you only want a loop blueprint. One product, one /looptimal skill.

Looptimal: an honest verify-outcome selftest passes GREEN, then a worked critic-panel example runs a quorum PASS followed by a deliberate fail-flip that correctly gates RED

Every line of output above is real — recorded by actually running scripts/verify-outcome.py --selftest and examples/critic-panel/run_demo.sh (see scripts/record-demo.py, and assets/demo.cast for the raw asciinema recording). Nothing is scripted sales copy; it's the outer verifier and the critic-panel quorum doing exactly what SECURITY.md and the pitch above claim, on this exact codebase.

The most valuable thing Looptimal does is sometimes tell you not to build a loop. A loop only pays off when:

1. It recurs — the setup cost amortizes over many runs.
2. An objective gate can reject bad output — you can write the verifier.
3. The budget absorbs retries — iterating is cheaper than getting it right once by hand.
4. The agent can run what it writes — there's a real feedback signal, not a human in every cycle.

If recurrence fails, the honest answer is not always "stop." It means "not a reusable loop blueprint yet." A one-time objective with a real verifier can still route to a mission / goal run, using the same discipline: durable state, bounded retries, maker != checker, and a stop condition. If retries are not useful, route to a single verified pass. If no verifier or human checkpoint exists, reject the automation claim. The metric that matters is cost-per-accepted-change, not tokens spent.

Ralph loops, Claude Code's native loop support, and similar patterns run a loop — they're the execution engine. Looptimal is the layer around whichever one you're already using: the Tier-0 decision gate that says whether a loop is even worth building before you build it, the sealed definition of "done" frozen before the loop starts, and the independent verifier that re-proves the outcome once it's finished. Maker ≠ checker applied to whatever loop you're already running — not a replacement for it.

Spec-driven tools like GitHub spec-kit and AWS Kiro write a spec, which is a real and different problem. Neither verifies the built thing against a live outcome once the spec is implemented — that's exactly what Stage 6 (Verify-outcome) exists to close. If a target repo already has spec-kit or Kiro artifacts, scripts/looptimal-frame-ingest.py is an optional Stage-0 Frame helper that surfaces them as candidate acceptance-criteria text for a human to accept or edit — it never auto-seals anything into a real contract.

If you just want a loop that runs, those tools are great at that. Looptimal is for when you need to prove what it claims when it's done — CI for agent done-claims, not another way to write or run one.

The Design-loop wizard also runs as a direct fast-path when you only want a loop blueprint — say "design a loop" or "loop wizard" and Looptimal jumps to Stage 2 without outcome orchestration.

A loop owns one recurring unit of work. A graph makes several loops understandable as one outcome: dependencies, authority boundaries, evidence expectations, and a graph-level acceptance gate. Graphs wire the work. Loops keep each node honest. Receipts prove the run.

The starter kit is deliberately practical and deliberately non-authoritative. It can create, validate, inspect, and render graph manifests, but it does not execute nodes, approve H1/H2 actions, or promote evidence. Start from a packaged pattern:

looptimal graph starters
looptimal graph init my-change --starter product-development-system
looptimal graph validate my-change
looptimal graph inspect my-change
looptimal graph render my-change -o my-change/graph.mmd

Included starters: verified code change, customer signal to roadmap, reviewed content publishing, product development system (key product/dev Loop Store starter), and GTM lightning PMF hunt (key GTM Loop Store starter). Every loop node pins an immutable loop://slug@x.y.z reference and carries Goal / State / Verifier / Stop. Human-gated actions remain explicit nodes. See the graph v1 contract before adapting a starter.

/plugin marketplace add Renn-Labs/Looptimal
/plugin install looptimal@renn-labs

Invoke as /looptimal (v2.0.0). Say "design a loop for ..." for the wizard fast-path.

Other harnesses. Looptimal is a self-contained folder skill (SKILL.md + templates/ + references/ loaded on demand). Clone once and symlink where your harness discovers skills:

Just the tooling, no clone. The doctor/lint/verify scripts are also installable as ordinary console commands via uv/pipx — useful if you only want to run looptimal-lint/verify-outcome against your own mission files, not install the skill itself:

uvx --from git+https://github.com/Renn-Labs/Looptimal@v2.2.0 verify-outcome --bundle path/to/evidence-bundle.json

This is a convenience layer over the same scripts/*.py, not a separate implementation — pin to a tagged ref (@v2.2.0, not @main) so the command doesn't silently move under you. Not yet on PyPI; the uvx --from git+... form works today without one.

From a checkout that includes the grouped entry point, you can also smoke-test the loop-design tools without waiting for the next tag:

uv run --with-editable . looptimal verify-outcome --selftest
uv run --with-editable '.[yaml]' looptimal library search secret

python3 scripts/looptimal-lint.py --selftest # plan-time gate self-test
python3 scripts/verify-outcome.py --selftest # Stage-6 outer verifier self-test (tamper → RED)
python3 scripts/loopprint-lint.py examples/ci-triage/loop-spec.yaml # loop-design wizard gate (GREEN)
python3 scripts/looptimal-doctor.py # install health check
# Worked example round-trip against live state — sealed with a demo HMAC key (see
# examples/issue-to-pr-bugfix/DEMO-KEY-NOT-SECRET.hex; loudly non-secret, never reuse it):
K=examples/issue-to-pr-bugfix/DEMO-KEY-NOT-SECRET.hex
python3 scripts/looptimal-lint.py examples/issue-to-pr-bugfix/mission.yaml --key-file "$K"
python3 scripts/verify-outcome.py --bundle examples/issue-to-pr-bugfix/evidence-bundle.json \
 --workdir examples/issue-to-pr-bugfix --repeat 3 --key-file "$K"
# Opt-in: on GREEN, also emit a public verification receipt (references/receipt.md). Keyed here,
# so it is HMAC-signed; bare --receipt writes <workdir>/looptimal-receipt.json (never on RED):
python3 scripts/verify-outcome.py --bundle examples/issue-to-pr-bugfix/evidence-bundle.json \
 --workdir examples/issue-to-pr-bugfix --repeat 3 --key-file "$K" --receipt
# Re-verify an existing receipt from first principles (re-derive its hashes, re-check the HMAC
# signature, and RE-RUN the sealed suite live) — a keyed receipt needs its key or it fails loud:
python3 scripts/verify-outcome.py --check-receipt examples/issue-to-pr-bugfix/looptimal-receipt.json \
 --workdir examples/issue-to-pr-bugfix --repeat 3 --key-file "$K"

The outer verifier (verify-outcome.py) is deliberately hostile to the maker: it loads the sealed contract the bundle points at (never a maker-supplied one), refuses non-sealed paths, canonicalizes and matches the contract hash, re-runs every criterion authoritatively (the bundle's self-reported results can only lose), requires each check to invoke a sealed, workdir-contained oracle script, and re-hashes artifacts.

Disclosed limit: by default, with no framer key configured, canonical_contract_hash() is an unkeyed sha256 self-digest over the contract mapping, and sealing rests on OS permissions — the framer owning sealed/, the checker controlling --workdir; the residual is that anyone who can write sealed/ can also recompute a matching hash after tampering. Passing a framer key (--key-file or the LOOPTIMAL_FRAMER_KEY env var) switches to a keyed HMAC-SHA256 digest folded over every file under sealed/ — the in-toto "materials" pattern — binding the oracle scripts a criterion actually invokes, not just the contract text naming them, so tamper-then-recompute no longer produces a matching hash. The residual that remains even when keyed is key custody: the key must live outside every maker-writable root, which is the checker's responsibility exactly like --workdir control already is. Do not over-claim tamper-proofness.

Loop blueprints generated by the Design-loop wizard (run-this-loop.sh, verify.sh) are executable code parameterized by loop-spec.yaml — treat them as code, not data. See SECURITY.md.

From the Design-loop wizard (Stage 2 / design fast-path), a self-contained runnable package per loop:

• loop-spec.yaml — four atoms + pattern + budget, machine-readable
• maker.sh — the maker step, run as a separate process from the verifier (maker ≠ checker)
• verify.sh — the external verifier (exit-code gate)
• state.md — the durable State artifact, updated every iteration
• run-this-loop.sh — engine-agnostic runner; emits metrics.jsonl + state.jsonl each iteration
• safety-checklist.md — human checkpoints + budget limits + checker identity
• flow.mmd — Mermaid diagram of the loop

From the full pipeline, additionally: acceptance-suite.yaml + acceptance-suite.sha256, Capability Manifest, local-capability-inventory.yaml, route.md, mission.yaml, consensus task graph, Simulate report, and evidence bundle.

Tooling: loopprint-lint.py gates the loop spec; loopprint-ls.py reports health of every loop in the repo (rot radar) — --update-index opts a repo's loops into an append-only, local-only ~/.loopprint/index.jsonl, and loopprint-ls.py --global reads it back ranked by cost-per-accepted-change across every repo that's opted in, flagging ROTTEN loops; deleting the index loses nothing, it's a rebuildable pointer cache; loopprint-report.py computes cost-per-accepted-change from metrics.jsonl; loopprint-skillify.py promotes a GREEN loop to a reusable skill. Verifier recipes: templates/verifier-library.yaml. Schema contract: references/schema.md.

python3 scripts/loopprint-update.py # dry-run: shows what would change, does nothing
python3 scripts/loopprint-update.py --apply # performs it

Symlinked installs (Claude Code folder skill, OpenCode, OpenClaw/EClaw, Hermes) update for free the moment you git pull the clone they point at. Copy-based installs (Codex/OMX: cp -r ~/looptimal ~/.codex/skills/looptimal) don't — loopprint-update.py git pulls the clone and re-syncs any copy-based install it finds at a known path, reporting exactly what changed (never anything untracked — .omc//.buildlog/-style local state is never synced). Dry-run by default; nothing is touched without --apply.

python3 scripts/looptimal-doctor.py # diagnose, copy-pasteable fix per problem
python3 scripts/looptimal-doctor.py --fix # apply safe repairs (chmod +x, relink dangling symlink)
python3 scripts/loopprint-doctor.py # diagnose the loop-design wizard install
python3 scripts/loopprint-doctor.py --fix

Full symptom→cause→fix map per install type: references/troubleshooting.md.

• The skill is the system. Looptimal encodes components and gates, not a personality. It does not demand a banner on every reply or a confirmation incantation. A loop works because its parts are real, not because the model recites a mantra.
• Stack-agnostic core. The methodology and artifacts stand alone. Heavier orchestration (isolated sub-agent dispatch, a separate plan/judge reviewer, cross-repo leasing) is described generically — wire in whatever you use.
• Honest gates. A verifier the maker can satisfy by self-assessment is not a verifier. Looptimal always points the gate at something external.
• Outcome, not completion. "Tests pass" is not the bar; live-state re-verification against a sealed acceptance suite is.

Built by Erik Ford at Renn Labs — an AI research & advisory firm. Looptimal distills one lesson from building autonomous agents: reliability comes from loop components and verified outcomes — durable state, external verification, stop conditions, maker ≠ checker — not from clever prompts.

MIT © Renn Labs LLC