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.
- loop/__init__.py +17 -0
- loop/__main__.py +176 -0
- loop/_bundle/schemas/manifest.schema.json +41 -0
- loop/_bundle/schemas/receipt.schema.json +21 -0
- loop/_bundle/schemas/repair-record.schema.json +42 -0
- loop/_bundle/schemas/rollout-record.schema.json +27 -0
- loop/_bundle/schemas/state.schema.json +25 -0
- loop/_bundle/schemas/tasks.schema.json +30 -0
- loop/_bundle/schemas/terminal.schema.json +19 -0
- loop/_bundle/templates/AGENTS.md.tmpl +67 -0
- loop/_bundle/templates/EVALS-rubric.md.tmpl +114 -0
- loop/_bundle/templates/RUNLOG.md.tmpl +42 -0
- loop/_bundle/templates/SPEC.md.tmpl +61 -0
- loop/_bundle/templates/TASKS.json.tmpl +23 -0
- loop/_bundle/templates/WORKFLOW.md.tmpl +84 -0
- loop/_bundle/templates/extract-trace-metrics.sh +27 -0
- loop/_bundle/templates/judge-rubric.sh +28 -0
- loop/_bundle/templates/manifest.yaml.tmpl +47 -0
- loop/_bundle/templates/state.json.tmpl +38 -0
- loop/_bundle/templates/terminal_state.json.tmpl +13 -0
- loop/_bundle/templates/verify-fast.sh +27 -0
- loop/_bundle/templates/verify-full.sh +34 -0
- loop/_bundle/templates/verify-safety.sh +35 -0
- loop/_bundle/tools/anticheat_scan.py +490 -0
- loop/_bundle/tools/holdout_gate.py +121 -0
- loop/_bundle/tools/inspect_loop.py +669 -0
- loop/_bundle/tools/metrics.py +725 -0
- loop/_resources.py +43 -0
- loop/contract.py +577 -0
- loop/emit.py +258 -0
- loop/paths.py +77 -0
- loop/scaffold.py +131 -0
- loop_engineer-0.7.0.dist-info/METADATA +470 -0
- loop_engineer-0.7.0.dist-info/RECORD +37 -0
- loop_engineer-0.7.0.dist-info/WHEEL +4 -0
- loop_engineer-0.7.0.dist-info/entry_points.txt +3 -0
- 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
|
+
[](https://github.com/SollanSystems/loop-engineer/actions/workflows/ci.yml)
|
|
43
|
+
[](https://www.python.org/downloads/)
|
|
44
|
+
[](LICENSE)
|
|
45
|
+
[](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
|
+

|
|
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,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.
|