loop-engineer 0.7.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. loop/__init__.py +17 -0
  2. loop/__main__.py +176 -0
  3. loop/_bundle/schemas/manifest.schema.json +41 -0
  4. loop/_bundle/schemas/receipt.schema.json +21 -0
  5. loop/_bundle/schemas/repair-record.schema.json +42 -0
  6. loop/_bundle/schemas/rollout-record.schema.json +27 -0
  7. loop/_bundle/schemas/state.schema.json +25 -0
  8. loop/_bundle/schemas/tasks.schema.json +30 -0
  9. loop/_bundle/schemas/terminal.schema.json +19 -0
  10. loop/_bundle/templates/AGENTS.md.tmpl +67 -0
  11. loop/_bundle/templates/EVALS-rubric.md.tmpl +114 -0
  12. loop/_bundle/templates/RUNLOG.md.tmpl +42 -0
  13. loop/_bundle/templates/SPEC.md.tmpl +61 -0
  14. loop/_bundle/templates/TASKS.json.tmpl +23 -0
  15. loop/_bundle/templates/WORKFLOW.md.tmpl +84 -0
  16. loop/_bundle/templates/extract-trace-metrics.sh +27 -0
  17. loop/_bundle/templates/judge-rubric.sh +28 -0
  18. loop/_bundle/templates/manifest.yaml.tmpl +47 -0
  19. loop/_bundle/templates/state.json.tmpl +38 -0
  20. loop/_bundle/templates/terminal_state.json.tmpl +13 -0
  21. loop/_bundle/templates/verify-fast.sh +27 -0
  22. loop/_bundle/templates/verify-full.sh +34 -0
  23. loop/_bundle/templates/verify-safety.sh +35 -0
  24. loop/_bundle/tools/anticheat_scan.py +490 -0
  25. loop/_bundle/tools/holdout_gate.py +121 -0
  26. loop/_bundle/tools/inspect_loop.py +669 -0
  27. loop/_bundle/tools/metrics.py +725 -0
  28. loop/_resources.py +43 -0
  29. loop/contract.py +577 -0
  30. loop/emit.py +258 -0
  31. loop/paths.py +77 -0
  32. loop/scaffold.py +131 -0
  33. loop_engineer-0.7.0.dist-info/METADATA +470 -0
  34. loop_engineer-0.7.0.dist-info/RECORD +37 -0
  35. loop_engineer-0.7.0.dist-info/WHEEL +4 -0
  36. loop_engineer-0.7.0.dist-info/entry_points.txt +3 -0
  37. loop_engineer-0.7.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,470 @@
1
+ Metadata-Version: 2.4
2
+ Name: loop-engineer
3
+ Version: 0.7.0
4
+ Summary: Portable Loop Contract Core: validate and inspect repo-native operating contracts for agent loops.
5
+ Project-URL: Homepage, https://github.com/SollanSystems/loop-engineer
6
+ Project-URL: Repository, https://github.com/SollanSystems/loop-engineer
7
+ Author: Sollan Systems
8
+ License: MIT License
9
+
10
+ Copyright (c) 2026 Sollan Systems
11
+
12
+ Permission is hereby granted, free of charge, to any person obtaining a copy
13
+ of this software and associated documentation files (the "Software"), to deal
14
+ in the Software without restriction, including without limitation the rights
15
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
16
+ copies of the Software, and to permit persons to whom the Software is
17
+ furnished to do so, subject to the following conditions:
18
+
19
+ The above copyright notice and this permission notice shall be included in all
20
+ copies or substantial portions of the Software.
21
+
22
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
25
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
27
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
28
+ SOFTWARE.
29
+ License-File: LICENSE
30
+ Keywords: agent,agentic,claude-code,eval,harness,loop,orchestration,repair,self-improvement,verification
31
+ Requires-Python: >=3.10
32
+ Provides-Extra: schemas
33
+ Requires-Dist: jsonschema>=4; extra == 'schemas'
34
+ Provides-Extra: yaml
35
+ Requires-Dist: pyyaml>=6; extra == 'yaml'
36
+ Description-Content-Type: text/markdown
37
+
38
+ # Loop Engineer
39
+
40
+ **Your AI agent says it's done. Loop Engineer makes it prove it.**
41
+
42
+ [![CI](https://github.com/SollanSystems/loop-engineer/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/SollanSystems/loop-engineer/actions/workflows/ci.yml)
43
+ [![Python 3.10–3.12](https://img.shields.io/badge/python-3.10%E2%80%933.12-blue)](https://www.python.org/downloads/)
44
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
45
+ [![Release](https://img.shields.io/badge/release-0.7.0-blue)](https://github.com/SollanSystems/loop-engineer/tags)
46
+
47
+ Long-running agents commit **false completion**. After context compaction they
48
+ forget what "done" meant, optimize to the visible test, patch in circles, and
49
+ report success with no independent evidence — and no typed way to say *blocked*,
50
+ *unverifiable*, or *underspecified* instead.
51
+
52
+ Loop Engineer is a **proof-of-done** layer that sits above your agent runtime. It
53
+ ships, on disk and runnable today:
54
+
55
+ - a **contract validator** (`doctor`) and **inspector** (`inspect`) that grade a
56
+ loop's proof machinery on *invocation evidence*, not on a self-asserted flag;
57
+ - a **held-out gate** and an **anti-cheat scan** built to catch a loop gaming its
58
+ own verifier;
59
+ - a runnable example whose `false_completion: false` is backed by a committed,
60
+ real gate verdict — `.loop/artifacts/holdout-verdict.json`, not a hand-set flag.
61
+
62
+ ![The inspector scores a self-asserted DIY loop 0/weak, then the gate-backed example 90/strong — both runs live](docs/demo.gif)
63
+
64
+ <sub>Filmed on the real tools ([`docs/demo.cast`](docs/demo.cast)); reproduce both
65
+ verdicts yourself: `python3 -m loop inspect examples/naive-loop` then
66
+ `examples/coverage-repair`.</sub>
67
+
68
+ ```bash
69
+ # Score a loop's proof-of-done in 5 seconds — no install, no agent, no API key:
70
+ git clone https://github.com/SollanSystems/loop-engineer.git
71
+ cd loop-engineer
72
+ python3 -m loop inspect examples/coverage-repair
73
+ ```
74
+
75
+ ## Where it sits
76
+
77
+ ┌──────────────────────────────────────────────────────────────┐
78
+ │ Tier 3 · REFERENCE RUNNER │
79
+ │ 9 Claude Code skills: design → contract → run → repair → │
80
+ │ flywheel │
81
+ ├──────────────────────────────────────────────────────────────┤
82
+ │ Tier 2 · PROOF TOOLCHAIN │
83
+ │ doctor · inspect · holdout_gate · anticheat_scan · │
84
+ │ runtime_monitor │
85
+ ├──────────────────────────────────────────────────────────────┤
86
+ │ Tier 1 · PORTABLE CONTRACT │
87
+ │ .loop/ state + SPEC/WORKFLOW/TASKS + schemas/ + templates/ │
88
+ └──────────────────────────────────────────────────────────────┘
89
+
90
+ Tiers 1–2 are runtime-neutral: pure-stdlib Python over files on disk, readable by
91
+ any tool. Tier 3 (the 9 Claude Code skills) is the *reference* runner, not a
92
+ requirement — bring your own runtime (LangGraph, ruflo, OpenHands, native Claude
93
+ Code) and keep the contract and proof layer above it.
94
+
95
+ ## How it compares
96
+
97
+ Different tools, different objects. The rows below are checkable facts, not
98
+ opinions.
99
+
100
+ | Project | ★ | What it is | Enforced proof-of-done? |
101
+ |---|---:|---|---|
102
+ | **Loop Engineer** (this repo) | — | operating contract + proof toolchain | **Yes** — 7 typed terminal states, held-out gate + anti-cheat scan, graded on invocation evidence |
103
+ | [cobusgreyling/loop-engineering](https://github.com/cobusgreyling/loop-engineering) | 4.9K | prompt-native loop-*design guidance*; owns the term "loop engineering" | Different object — design guidance, not a runtime or gate |
104
+ | [obra/superpowers](https://github.com/obra/superpowers) | 244K | phase-gating dev methodology (brainstorm → TDD → review) | No — gates dev phases, not a typed completion contract |
105
+ | [langchain-ai/langgraph](https://github.com/langchain-ai/langgraph) | 36K | stateful agent-graph runtime + checkpointing | No — completion is whatever the terminal node returns |
106
+
107
+ <sub>★ counts fetched via `gh api` on 2026-07-02; they drift over time.</sub>
108
+
109
+ What this suite owns:
110
+
111
+ - **7 typed terminal states** — a contract primitive, so no run ends in a silent "completed."
112
+ - **`false-completion-rate`** — measurable with the bundled held-out gate and anti-cheat scan; **0.0** on the shipped gate-backed example (see [Measured baseline](#measured-baseline)).
113
+ - **`repair-productivity`** — the fraction of repair attempts that measurably move verification forward; **1.0** on that example.
114
+ - **Repo-native loop state** — survives compaction, crashes, and handoff.
115
+ - **Deterministic-gate-before-rubric ordering** — model judges are advisory, not the first line of proof.
116
+
117
+ What is table-stakes rather than oversold: on-disk contracts, bounded repair
118
+ caps, and deterministic verification gates are shared with mature harnesses. Loop
119
+ Engineer's claim is the proof-of-done framing plus the typed termination and
120
+ loop-health metrics on top. It composes with those tools; it does not replace
121
+ their execution engines.
122
+
123
+ ### Measured baseline
124
+
125
+ The two metrics are **derived by a tool, not quoted from prose.** The checked-in
126
+ scorecard [`docs/metrics-baseline.json`](docs/metrics-baseline.json) is computed
127
+ by `python3 -m loop metrics` over the gate-backed `examples/coverage-repair` run —
128
+ its `false_completion:false` is backed by a real `holdout_gate.py` verdict, and
129
+ its `productive` flag is recomputed from the repair record's own score delta, not
130
+ trusted:
131
+
132
+ | Metric | Baseline | Source |
133
+ |---|---:|---|
134
+ | `false-completion-rate` | **0.0** | RUNLOG success-claims × verify bundles, cross-checked against the held-out gate flag (both agree) |
135
+ | `repair-productivity` | **1.0** | one repair pass, `verification_after.score` 0.83 > `before` 0.74 (recomputed, agreed) |
136
+
137
+ The number ships with a `provenance` block naming every input file (including the
138
+ held-out verdict's sha256), so a skeptic can re-derive it. That committed verdict
139
+ is *evidence, not proof*: it is validated structurally, but a fully-fabricated,
140
+ internally-consistent artifact defeats offline shape-checking by construction —
141
+ tamper detection of the artifact itself belongs to the anti-cheat layer; the tool
142
+ does not claim the verdict is tamper-proof. Reproduce (and refuse to publish over a
143
+ non-gate-backed, inconsistent, vacuous, or unanchored run):
144
+
145
+ ```bash
146
+ python3 -m loop metrics examples/coverage-repair # print the scorecard
147
+ python3 -m loop metrics --baseline examples/coverage-repair # rewrite docs/metrics-baseline.json
148
+ ```
149
+
150
+ ---
151
+
152
+ ## Proof-of-done, not self-assertion
153
+
154
+ The `inspect` and `doctor` commands accept either a workspace root or its `.loop/`
155
+ directory, and need no agent runtime to run.
156
+
157
+ `doctor` validates the contract objects (the real output also includes a
158
+ `paths` block listing every resolved contract file; omitted here for brevity):
159
+
160
+ ```json
161
+ {
162
+ "ok": true,
163
+ "validation_mode": "structural-fallback",
164
+ "schemas_checked": [
165
+ "loop-engineer/manifest@1",
166
+ "loop-engineer/state@1",
167
+ "loop-engineer/tasks@1",
168
+ "loop-engineer/terminal@1"
169
+ ],
170
+ "issues": []
171
+ }
172
+ ```
173
+
174
+ `validation_mode` reports what actually ran: the pure-stdlib structural checks by
175
+ default, or real JSON-Schema validation against `schemas/*.json` when the
176
+ optional `jsonschema` dependency is present (`pip install -e ".[schemas]"`), in
177
+ which case it reads `"jsonschema"`.
178
+
179
+ `inspect` is a static contract linter: it scores the loop contract's structure —
180
+ what proof machinery is present and what is missing — without running the loop:
181
+
182
+ ```json
183
+ {
184
+ "target": "examples/coverage-repair",
185
+ "score": 90,
186
+ "terminal_states_covered": 7,
187
+ "present": [
188
+ "defines verifiable success criteria",
189
+ "independent verification",
190
+ "approval gates on side-effects",
191
+ "false-completion defense (invoked)",
192
+ "all 7 terminal states reachable"
193
+ ],
194
+ "gaps": [
195
+ "no plan-then-execute discipline for untrusted/web reads (prompt-injection surface)"
196
+ ],
197
+ "verdict": "strong"
198
+ }
199
+ ```
200
+
201
+ Note: `false-completion defense` credit is graded on *invocation evidence*, not
202
+ self-assertion. This example earns it the honest way — `scripts/verify-full`
203
+ invokes the real held-out gate (`scripts/holdout_gate.py`) over the toy target in
204
+ `examples/coverage-repair/target/`, and `run-example` records a Succeeded verdict
205
+ to `.loop/artifacts/holdout-verdict.json` — so a self-asserted flag is never what
206
+ scores. The one remaining gap is honest too: this low-risk, workspace-write loop
207
+ declares `plan_then_execute: false`, so it earns no prompt-injection-discipline
208
+ credit (correct for a loop that reads no untrusted input).
209
+
210
+ The prime directive:
211
+
212
+ > If a loop cannot define success, verification, or a terminal state, it stops
213
+ > as `FailedSpecGap` instead of pretending the next completion is done.
214
+
215
+ ---
216
+
217
+ ## Honest termination model
218
+
219
+ Loop Engineer does not allow a vague "completed." Every run exits through
220
+ exactly one named state:
221
+
222
+ | State | When |
223
+ |---|---|
224
+ | `Succeeded` | Verification passes; all acceptance criteria are met. |
225
+ | `FailedUnverifiable` | Success or failure cannot be confirmed because verification is insufficient. |
226
+ | `FailedBlocked` | The loop cannot proceed because of a tool, permission, dependency, or external blocker. |
227
+ | `FailedBudget` | Time or cost budget is exhausted. |
228
+ | `FailedSafety` | Safety, policy, or approval risk is detected. |
229
+ | `FailedSpecGap` | The objective is underspecified; success criteria cannot be defined. |
230
+ | `AbortedByHuman` | The operator explicitly stops the run. |
231
+
232
+ ---
233
+
234
+ ## Contract anatomy
235
+
236
+ A loop contract is a repo-native directory — a small on-disk "repo-OS" — that
237
+ externalizes intent, queue state, runtime state, verification, approvals, and
238
+ terminal outcome:
239
+
240
+ ```text
241
+ <workspace>/
242
+ AGENTS.md # short entrypoint: where to find the contract
243
+ SPEC.md # what done means: success criteria + evidence rules
244
+ WORKFLOW.md # gates, budgets, repair cap, terminal states
245
+ TASKS.json # machine-readable task queue
246
+ RUNLOG.md # append-only iteration history
247
+ EVALS/ # datasets, rubrics, regressions, traces
248
+ scripts/
249
+ verify-fast # cheap deterministic gate
250
+ verify-full # full deterministic gate
251
+ verify-safety # safety / approval / injection checks
252
+ judge-rubric # advisory rubric judge
253
+ .loop/
254
+ manifest.yaml # contract metadata
255
+ state.json # live FSM cursor
256
+ terminal_state.json # final exit record; written once — emit refuses overwrite without force=True
257
+ artifacts/ # evidence bundles and intermediate outputs
258
+ approvals/ # approval requests and resolutions
259
+ checkpoints/ # recoverable snapshots
260
+ memory/ # run summaries and durable lessons
261
+ ```
262
+
263
+ The contract split is deliberate:
264
+
265
+ - `SPEC.md` defines success.
266
+ - `WORKFLOW.md` defines how the loop is allowed to operate.
267
+ - `TASKS.json` defines the executable queue.
268
+ - `RUNLOG.md` records human-readable history.
269
+ - `.loop/state.json` is the machine source of truth while the loop runs.
270
+ - `.loop/terminal_state.json` records the final outcome (the resolver also
271
+ accepts it at the workspace root).
272
+
273
+ A task is not done because an agent says it is done. A task is done only when it
274
+ maps to a success criterion, its verifier passes, and evidence is recorded.
275
+
276
+ See `reference/repo-os-contract.md` for the canonical artifact schemas.
277
+
278
+ ### A versioned, conformance-checkable standard
279
+
280
+ The on-disk contract is a **documented, versioned, tool-agnostic standard** — conformance is
281
+ defined by the published `schemas/*.schema.json` (`$id` `loop-engineer/<artifact>@<major>`,
282
+ additive within a major), and a runnable **conformance checklist** (A1–E1) lets any harness claim
283
+ *"emits a Loop-Engineer-conformant contract v1."* See
284
+ [`reference/repo-os-contract.md`](reference/repo-os-contract.md) §0 / §11 / §14.
285
+
286
+ ---
287
+
288
+ ## Install
289
+
290
+ ### Portable validator / inspector
291
+
292
+ No Claude Code plugin is required to validate or inspect a loop contract:
293
+
294
+ ```bash
295
+ uvx loop-engineer inspect . # zero-install score of any repo's loop contract
296
+ pip install loop-engineer # or install the CLI: `loop doctor`, `loop inspect`, ...
297
+ ```
298
+
299
+ From a clone, `python3 -m loop <cmd>` and `pip install -e .` keep working; the
300
+ wheel is self-contained (schemas, templates, and the inspect/metrics tooling
301
+ ship inside it). The core is pure-stdlib — PyYAML/jsonschema are optional extras.
302
+
303
+ The portable core lives in `loop/` and validates schema-bearing artifacts in
304
+ `schemas/`:
305
+
306
+ - `loop-engineer/manifest@1`
307
+ - `loop-engineer/state@1`
308
+ - `loop-engineer/tasks@1`
309
+ - `loop-engineer/terminal@1`
310
+
311
+ ### Claude Code plugin
312
+
313
+ ```bash
314
+ claude plugin marketplace add SollanSystems/loop-engineer
315
+ claude plugin install loop-engineer@loop-engineer
316
+ ```
317
+
318
+ Restart Claude Code to load all 9 skills. (Local dev: clone the repo and run
319
+ `claude plugin marketplace add "$PWD"` instead.)
320
+
321
+ **Requirements:** Python 3.10+ for the portable validator/inspector; Claude Code
322
+ for the plugin — no other dependencies. Optional integrations (e.g.
323
+ `claude-code-orchestration` for `/verify-slice`) are layered on when present and
324
+ never required; every skill runs on the bundled core alone.
325
+
326
+ ---
327
+
328
+ ## Adopt in your stack
329
+
330
+ Three thin, enforcing on-ramps — each one makes a false "done" fail somewhere
331
+ that already exists in your workflow. Start where your loop lives:
332
+
333
+ **Claude Code** — the plugin ships a Stop-hook firewall: if the session's repo
334
+ holds a `.loop/` contract that claims `Succeeded` while `loop doctor` says
335
+ otherwise, the stop is blocked with the exact doctor issues. No-op without
336
+ `.loop/`, fail-open on error, zero config beyond installing the plugin.
337
+
338
+ **Any Python runtime** — `loop.emit` is a pure-stdlib writer for foreign
339
+ orchestrators (LangGraph, or anything that can call four functions):
340
+ `open_contract`, `append_iteration`, `append_receipt`, `terminate`. The writer
341
+ refuses an evidence-free `Succeeded` at write time. Recipe:
342
+ [docs/integrations/langgraph.md](docs/integrations/langgraph.md).
343
+
344
+ **CI** — one workflow step validates the contract and publishes a scorecard:
345
+
346
+ ```yaml
347
+ - uses: SollanSystems/loop-engineer@v0.7.0
348
+ with:
349
+ path: "."
350
+ ```
351
+
352
+ `doctor` failure fails the job (and the action installs the `[schemas]` extra so
353
+ `doctor` runs real JSON-Schema validation, not the structural fallback). The
354
+ inspect **score is an advisory heuristic** — useful as a trend, but a determined
355
+ author can game it, so it is warn-only unless you set `fail-under-score`;
356
+ **`loop doctor` is the hard gate.** The optional PR comment is sticky — it edits
357
+ one scorecard comment in place across re-runs. Pre-commit users: hook id
358
+ `loop-doctor` (its `additional_dependencies` pin the schema extras too). This repo
359
+ dogfoods the same action in CI against its flagship example contract
360
+ ([`examples/coverage-repair`](examples/coverage-repair)) — the gate gates its maker.
361
+
362
+ ---
363
+
364
+ ## Claude Code reference workflow
365
+
366
+ The Claude Code plugin is the reference UI over the portable loop contract.
367
+
368
+ ```text
369
+ /loop-engineer
370
+ → /loop-architect
371
+ → /loop-contract
372
+ → /loop-run
373
+ → /loop-repair when a gate fails
374
+ → /loop-flywheel after terminal state
375
+ ```
376
+
377
+ ### Design
378
+
379
+ | Skill | One line |
380
+ |---|---|
381
+ | **loop-engineer** | Router: broad intent → the right spoke map. |
382
+ | **loop-architect** | Classifies the scenario and selects the loop architecture + physical realization. |
383
+ | **loop-contract** | Scaffolds the repo-OS operating contract: `SPEC.md`, `WORKFLOW.md`, `TASKS.json`, `RUNLOG.md`, `.loop/`. |
384
+
385
+ ### Run
386
+
387
+ | Skill | One line |
388
+ |---|---|
389
+ | **loop-run** | Runs the state machine iteration by iteration, approval-gated, running the contract's verify gate (optionally `/verify-slice`). |
390
+ | **loop-repair** | Runs a bounded patch-and-repair loop with a structured repair record. |
391
+ | **loop-runtime-monitor** | Watches an in-flight run from outside; flags stall, repair-churn, and budget overrun. |
392
+
393
+ ### Improve
394
+
395
+ | Skill | One line |
396
+ |---|---|
397
+ | **loop-evals** | Designs the 7-layer eval suite and makes false-completion-rate + repair-productivity first-class. |
398
+ | **loop-flywheel** | Turns traces and failures into new eval cases; manages memory compaction. |
399
+ | **loop-inspector** | Audits an existing loop directory read-only; emits a scored gap report. |
400
+
401
+ Not sure which spoke to use? Start with `/loop-engineer`; it routes the task.
402
+
403
+ ---
404
+
405
+ ## What ships
406
+
407
+ - `loop/` — portable contract core and CLI: `doctor` (aliases: `validate`, `verify`) and `inspect`.
408
+ - `schemas/` — JSON schemas for contract artifacts.
409
+ - `skills/` — Claude Code skill suite.
410
+ - `reference/` — protocol, architecture, eval, safety, and platform reference docs.
411
+ - `scripts/` — validators, runtime monitor, anti-cheat scanner, benchmark harness, rollout ledger.
412
+ - `examples/` — sample loop contracts, including `examples/coverage-repair`.
413
+
414
+ ---
415
+
416
+ ## Verification
417
+
418
+ Release readiness is gate-backed, not asserted by README prose.
419
+
420
+ ```bash
421
+ uv run --with pyyaml python3 -B scripts/validate_frontmatter.py
422
+ uv run --with pyyaml python3 -B scripts/self_eval.py
423
+ uv run --with pyyaml --with pytest python3 -B -m pytest -q -p no:cacheprovider scripts
424
+ python3 -m py_compile loop/*.py scripts/*.py
425
+ claude plugin validate --strict .claude-plugin/plugin.json
426
+ ```
427
+
428
+ The structural self-eval checks skill presence, frontmatter, cross-links,
429
+ terminal-state coverage, repair-record fields, eval metrics, templates, secret
430
+ patterns, dispatch examples, the bring-your-own-verifier default, the MIT
431
+ license, and README differentiation.
432
+
433
+ ---
434
+
435
+ ## Status
436
+
437
+ - Version: `0.7.0`
438
+ - Release tag: `v0.7.0` (PyPI publish trigger; plugin tags through 0.6.0 used `loop-engineer--v<version>`)
439
+ - License: MIT
440
+ - Primary interface: Claude Code plugin
441
+ - Portable core: Python CLI + JSON schemas
442
+ - Current reference example: `examples/coverage-repair`
443
+
444
+ ---
445
+
446
+ ## Reference docs
447
+
448
+ Deep content lives in `reference/` and is loaded on demand by the skills:
449
+
450
+ - `reference/architecture-matrix.md` — architecture comparison + scenario→realization table.
451
+ - `reference/loop-patterns.md` — PreFlect, milestone, patch-and-repair, flywheel, manager-orchestrator, plan-then-execute.
452
+ - `reference/repo-os-contract.md` — repo-OS layout, artifact schemas, state machine.
453
+ - `reference/prompt-templates.md` — bootstrap, goal-launch, repair-loop, and short prompt templates.
454
+ - `reference/eval-suite.md` — 7-layer eval suite, first-class metrics, flywheel schedule.
455
+ - `reference/safety-and-approvals.md` — escalation ladder, approval lifecycle, anti-cheat.
456
+ - `reference/platform-map.md` — portable-core mapping across Claude, Codex, Hermes, and Google.
457
+
458
+ ---
459
+
460
+ ## Get started
461
+
462
+ Run the zero-install `inspect` command at the top of this README, then scaffold a
463
+ contract for your own loop with `/loop-contract` — or read
464
+ `reference/repo-os-contract.md` for the artifact schemas.
465
+
466
+ ---
467
+
468
+ ## License
469
+
470
+ MIT — Sollan Systems
@@ -0,0 +1,37 @@
1
+ loop/__init__.py,sha256=JVm2Qso8xFZWBMV8BJpE63y2231AUinpLniJyiUpdgw,469
2
+ loop/__main__.py,sha256=8Zc7YQ_ruMuEVB535vUbZnCyFBwhqMMUuxCRtipUol8,6006
3
+ loop/_resources.py,sha256=pWmLSiPKXaTOZU-7naHPaNqOxujINJ94XnMsRJzzVoM,1186
4
+ loop/contract.py,sha256=gX_NKcQ2Wqwy_heu0dcijLkekEPDguy_DvS4VCRDvt8,23476
5
+ loop/emit.py,sha256=DqGx5AZkpjMRlO1fqfWHbeecgMlXgt4J0Nh6r2Lkd6A,8824
6
+ loop/paths.py,sha256=L6H_XIU9ESuhFW_47KInx5yen-jEubIvKGrEdJsIxOk,2883
7
+ loop/scaffold.py,sha256=uHjzNfLnSkKlcYwCjrcnhSWDeVsJaXPywmqehYvCO7Q,4237
8
+ loop/_bundle/schemas/manifest.schema.json,sha256=U6CslLK8PSpoC886J0Ad5eIF8Ii_RU-wBqxjCSg2QYI,1553
9
+ loop/_bundle/schemas/receipt.schema.json,sha256=QGdNyPoDvrLgGDIixeYX-lWdilxPHkB2A-sQ24VfSKA,1221
10
+ loop/_bundle/schemas/repair-record.schema.json,sha256=leAQnVKMTFGPXCXuEJSqO3ehM6MvSNBucPJb7iUm7y8,1914
11
+ loop/_bundle/schemas/rollout-record.schema.json,sha256=8ssCacTQLQm_bA6lDOXEuBDHyqEjxgaOOiyaWC57zzA,1264
12
+ loop/_bundle/schemas/state.schema.json,sha256=21FeZ1uB5go4lu_9ht8RgdfWR-i1dxxYR_25JlU0Hhk,1496
13
+ loop/_bundle/schemas/tasks.schema.json,sha256=4sbAa4huHMTrvhMdx0hDLnQUeI3GDjLji1_seMuOyCo,1433
14
+ loop/_bundle/schemas/terminal.schema.json,sha256=bdFGUB1DfAjPlqTOZHCT7NJw7sgIFuwoA6T92dqoZDc,1344
15
+ loop/_bundle/templates/AGENTS.md.tmpl,sha256=Qw1fOZ6PAZD2OWFYJaKR4qBLUEvWJia2fvCcc48hZgY,2321
16
+ loop/_bundle/templates/EVALS-rubric.md.tmpl,sha256=bqCqCdX0rBGuxNWFSvB0O95CJEiTUxPkDkvyvFu1TxA,3604
17
+ loop/_bundle/templates/RUNLOG.md.tmpl,sha256=5ULZo1yFN8bYAgzADS90cagaUJ0MC1LGxuKwk4JoCRo,1070
18
+ loop/_bundle/templates/SPEC.md.tmpl,sha256=WC0wov1XUG4S73jmBCrhTT5laWJ7JLzEvFBKz1rJFbw,1545
19
+ loop/_bundle/templates/TASKS.json.tmpl,sha256=gsXnvz-6X1zYSBybPGChYoD0nSs3-RBAnoIOku4Ztrs,501
20
+ loop/_bundle/templates/WORKFLOW.md.tmpl,sha256=WoNk6z3sxAN0ti9UPdaAV-tKLQtbWZkqxIT8dtYEi3o,3768
21
+ loop/_bundle/templates/extract-trace-metrics.sh,sha256=9JBLJr0_QYeMUd2nSxTrfwvG0MKBtipOZ6PFeF-K38o,1230
22
+ loop/_bundle/templates/judge-rubric.sh,sha256=7vy5n_UBnZyxC2bLtVnlImITAdFosF283Kh0JLabE9k,1247
23
+ loop/_bundle/templates/manifest.yaml.tmpl,sha256=r--OY321floA5mW3__SUKcCCydquGB7SIKKYmJ26uhA,1692
24
+ loop/_bundle/templates/state.json.tmpl,sha256=Npduwa2KH-8QyPXI3Pp-8GDCY-gipR-x9pO8hMleFhA,1254
25
+ loop/_bundle/templates/terminal_state.json.tmpl,sha256=5znnltXwLb1ne1oy9o4pBy90ggaLVkiquGaSlyPLar0,437
26
+ loop/_bundle/templates/verify-fast.sh,sha256=rIjDAVuAhHR-0gJkWuaATLZxnbTRgjJY2rbJSydgXWw,818
27
+ loop/_bundle/templates/verify-full.sh,sha256=iM7m64zI-ReGj9qRi_ARB9WiYxAedsU6TCzjLjmAUCU,1175
28
+ loop/_bundle/templates/verify-safety.sh,sha256=67_zX5jGa6ZNFdYR8koU9u1f76KbEM3qJh3f7U1c7a8,1515
29
+ loop/_bundle/tools/anticheat_scan.py,sha256=wWJZ_aTHta8ZRmwotoF4eX0YXtCiX48IKsGgfYOUvxY,19214
30
+ loop/_bundle/tools/holdout_gate.py,sha256=inalbaLXWfNLK_KqLrvs0uYZcLqmRxeqbhc8Wc6i3hQ,4364
31
+ loop/_bundle/tools/inspect_loop.py,sha256=fkOTmlT79jsuo6-B9Q9WTvXItBRtETtw9eVDKThIbVM,28306
32
+ loop/_bundle/tools/metrics.py,sha256=n-mgKKsScaRND9akIzu8TvefsUENPzxGC3mJBpXKC4I,31041
33
+ loop_engineer-0.7.0.dist-info/METADATA,sha256=T3wBF8fjXy9hBTbumSwRA_j4yZ6AhU6y8H7AOVffINk,21432
34
+ loop_engineer-0.7.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
35
+ loop_engineer-0.7.0.dist-info/entry_points.txt,sha256=896lYZ1rIdkMgPDr3Fwte8d_rhsCBNqXka1SKuAzh-g,79
36
+ loop_engineer-0.7.0.dist-info/licenses/LICENSE,sha256=OkOjWIwkswgzOHAEVyX9cri74ph3tZN8hNHi4OeZnIA,1071
37
+ loop_engineer-0.7.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.31.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ loop = loop.__main__:main
3
+ loop-engineer = loop.__main__:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sollan Systems
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.