loop-engineer 0.7.0__tar.gz → 0.8.0__tar.gz

{loop_engineer-0.7.0 → loop_engineer-0.8.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "loop-engineer",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Design, launch, verify, repair, and improve agent loops. A Claude-Code-native architect+operator for long-running, verifiable, self-improving agentic-coding systems.",
   "author": { "name": "Sollan Systems", "url": "https://github.com/SollanSystems" },
   "homepage": "https://github.com/SollanSystems/loop-engineer",

{loop_engineer-0.7.0 → loop_engineer-0.8.0}/.github/workflows/ci.yml

@@ -59,7 +59,23 @@ jobs:
       - name: Install recipe dependencies
         run: python -m pip install --upgrade pip pyyaml pytest jsonschema langgraph
       - name: LangGraph recipe end-to-end
-        run: python -B -m pytest -q -p no:cacheprovider scripts/test_langgraph_recipe.py
+        run: python -B -m pytest -q -p no:cacheprovider scripts/test_langgraph_recipe.py scripts/test_langgraph_recipe_st3.py
+
+  recipe-temporal:
+    name: recipe (temporal)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install recipe dependencies
+        run: python -m pip install --upgrade pip pyyaml pytest jsonschema temporalio
+      - name: Temporal recipe end-to-end
+        # start_local() downloads the Temporal dev-server binary (~20MB) to
+        # $TMPDIR/temporal-sdk-python-<version> — ephemeral and quick, so (like
+        # recipe-langgraph) this job carries no cache step.
+        run: python -B -m pytest -q -p no:cacheprovider scripts/test_temporal_recipe.py
 
   action-dogfood:
     name: action (dogfood on flagship example)

{loop_engineer-0.7.0 → loop_engineer-0.8.0}/.gitignore

@@ -33,3 +33,6 @@ Thumbs.db
 # Secrets — never commit
 .env
 *.local
+
+# Local cold-start context — deliberately untracked (see its own do-not-commit note)
+/CLAUDE.md

{loop_engineer-0.7.0 → loop_engineer-0.8.0}/CHANGELOG.md

@@ -14,6 +14,37 @@ All notable changes to `loop-engineer` are documented here.
   `WORKFLOW.md` and `README.md` are reworded to describe the mechanism; the 0.3.4
   history is left intact.
 
+## 0.8.0 — 2026-07-09
+
+**ST3 — integration adapters.** `loop/integrations.py`: an engine-neutral,
+pure-stdlib projection (`EngineOutcome` + `to_terminal_state`) from any
+engine's "the run ended" signal onto the 7 typed terminal states, with the
+fixed precedence safety → human → blocked → budget → spec-gap → gate verdict.
+`Succeeded` is reachable only through a green `holdout_gate.decide` verdict,
+a clean anticheat sweep, a met criterion, and evidence; `false_completion` is
+copied from the gate, never synthesized; missing gate/anticheat input fails
+closed to `FailedUnverifiable`. The LangGraph recipe is upgraded in place to
+this bar (its run now scores clean under `loop metrics` — closing the
+recorded FCR-1.0 follow-up) and a Temporal recipe lands
+(`examples/temporal-certify/`, certify-activity pattern, cancellation →
+`AbortedByHuman`, retry exhaustion → `FailedBlocked`, timeout →
+`FailedBudget`). Both recipes pin the false-completion invariant
+(visible-green/holdout-red → `FailedUnverifiable` with
+`false_completion: true`, never `Succeeded`) and pass the doctor round-trip.
+
+**ST4 — contributor funnel.** `loop inspect` now recognizes a foreign
+Superpowers-style run dir read-only (`loop/foreign.py` — a layout mapper onto
+the existing `LoopPaths` seam; the M2/M3-hardened scorer is untouched and a
+foreign harness with no gate and no terminal record scores honestly low).
+The reading is checked in as `docs/gap-reports/superpowers.md` — the §14
+conformance checklist evaluated against a vendored, sanitized fixture
+(`examples/superpowers-run/`). A second runnable example lands:
+`examples/flaky-test-triage/` — doctor-clean, gate-backed, and the showcase
+for repair records (`loop metrics` derives a non-null repair-productivity of
+1.0 from its anchored red→green repair). Seven gate-backed starter issues are
+drafted under `docs/contributing/issues/` and filed at release;
+CONTRIBUTING gains the start-here funnel.
+
 ## 0.7.0 — 2026-07-08
 
 **ST2 — the portable standard.** The on-disk contract is now a documented,

{loop_engineer-0.7.0 → loop_engineer-0.8.0}/CONTRIBUTING.md

@@ -20,6 +20,25 @@ python3 -m loop inspect  examples/coverage-repair
 
 If you don't have the deps, prefix with `uv run --with pyyaml --with pytest`.
 
+## Start here — the contributor funnel
+
+Every open starter issue names **the gate that proves the fix** — a
+deterministic command that is red before your change and green after. That is
+the whole review bar (see the ground rule above).
+
+- [`good first issue`](https://github.com/SollanSystems/loop-engineer/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+  — small, bounded, gate-verifiable fixes.
+- [`help wanted`](https://github.com/SollanSystems/loop-engineer/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
+  — integration recipes (OpenHands, ruflo — designs already written in
+  `docs/superpowers/specs/2026-06-30-st3-integration-adapters.md`) and
+  foreign-harness gap reports (`docs/gap-reports/`).
+
+The contribution target for anything that emits or consumes contract
+artifacts is the standard: `reference/repo-os-contract.md` — a harness that
+satisfies the §14 conformance checklist (A1–E1) may claim it emits a
+Loop-Engineer-conformant contract v1. Drafts for the seeded issues live in
+`docs/contributing/issues/` and are filed on GitHub at release time.
+
 ## Repository layout
 
 | Path | What lives here |

{loop_engineer-0.7.0 → loop_engineer-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-engineer
-Version: 0.7.0
+Version: 0.8.0
 Summary: Portable Loop Contract Core: validate and inspect repo-native operating contracts for agent loops.
 Project-URL: Homepage, https://github.com/SollanSystems/loop-engineer
 Project-URL: Repository, https://github.com/SollanSystems/loop-engineer
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 [![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)
 [![Python 3.10–3.12](https://img.shields.io/badge/python-3.10%E2%80%933.12-blue)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![Release](https://img.shields.io/badge/release-0.7.0-blue)](https://github.com/SollanSystems/loop-engineer/tags)
+[![Release](https://img.shields.io/badge/release-0.8.0-blue)](https://github.com/SollanSystems/loop-engineer/tags)
 
 Long-running agents commit **false completion**. After context compaction they
 forget what "done" meant, optimize to the visible test, patch in circles, and
@@ -344,7 +344,7 @@ refuses an evidence-free `Succeeded` at write time. Recipe:
 **CI** — one workflow step validates the contract and publishes a scorecard:
 
 ```yaml
-- uses: SollanSystems/loop-engineer@v0.7.0
+- uses: SollanSystems/loop-engineer@v0.8.0
   with:
     path: "."
 ```
@@ -434,12 +434,12 @@ license, and README differentiation.
 
 ## Status
 
-- Version: `0.7.0`
-- Release tag: `v0.7.0` (PyPI publish trigger; plugin tags through 0.6.0 used `loop-engineer--v<version>`)
+- Version: `0.8.0`
+- Release tag: `v0.8.0` (PyPI publish trigger; plugin tags through 0.6.0 used `loop-engineer--v<version>`)
 - License: MIT
 - Primary interface: Claude Code plugin
 - Portable core: Python CLI + JSON schemas
-- Current reference example: `examples/coverage-repair`
+- Current reference examples: `examples/coverage-repair`, `examples/flaky-test-triage`
 
 ---
 

{loop_engineer-0.7.0 → loop_engineer-0.8.0}/README.md

@@ -5,7 +5,7 @@
 [![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)
 [![Python 3.10–3.12](https://img.shields.io/badge/python-3.10%E2%80%933.12-blue)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![Release](https://img.shields.io/badge/release-0.7.0-blue)](https://github.com/SollanSystems/loop-engineer/tags)
+[![Release](https://img.shields.io/badge/release-0.8.0-blue)](https://github.com/SollanSystems/loop-engineer/tags)
 
 Long-running agents commit **false completion**. After context compaction they
 forget what "done" meant, optimize to the visible test, patch in circles, and
@@ -307,7 +307,7 @@ refuses an evidence-free `Succeeded` at write time. Recipe:
 **CI** — one workflow step validates the contract and publishes a scorecard:
 
 ```yaml
-- uses: SollanSystems/loop-engineer@v0.7.0
+- uses: SollanSystems/loop-engineer@v0.8.0
   with:
     path: "."
 ```
@@ -397,12 +397,12 @@ license, and README differentiation.
 
 ## Status
 
-- Version: `0.7.0`
-- Release tag: `v0.7.0` (PyPI publish trigger; plugin tags through 0.6.0 used `loop-engineer--v<version>`)
+- Version: `0.8.0`
+- Release tag: `v0.8.0` (PyPI publish trigger; plugin tags through 0.6.0 used `loop-engineer--v<version>`)
 - License: MIT
 - Primary interface: Claude Code plugin
 - Portable core: Python CLI + JSON schemas
-- Current reference example: `examples/coverage-repair`
+- Current reference examples: `examples/coverage-repair`, `examples/flaky-test-triage`
 
 ---
 

loop_engineer-0.8.0/docs/contributing/issues/01-good-first-qw9-trigger-phrases.md

@@ -0,0 +1,45 @@
+<!-- title: Trigger-phrase disambiguation batch (3 LOW fixes) -->
+<!-- labels: good first issue -->
+
+# Trigger-phrase disambiguation batch (3 LOW fixes)
+
+Three small `SKILL.md` frontmatter edits that sharpen router resolution. Each is
+independently checkable and none changes behavior — only the trigger prose.
+
+## Problem
+
+Three trigger-phrase weaknesses, all present at this commit:
+
+- **Shared bare "grade" verb.** `skills/loop-evals/SKILL.md` anchors *"or grade a
+  long-running agentic run"* and `skills/loop-inspector/SKILL.md` anchors *"grade a
+  superpowers / ruflo / .loop harness"* — both hang the same verb on different
+  objects, so a bare "grade this" query has no clean winner.
+- **`loop-evals` verbosity outlier.** Its `description` scalar runs well past the
+  sibling band (~736 chars vs a ~400–510-char peer range), because capability prose
+  (the 7-layer suite, deterministic-then-rubric, the regression harness) lives in the
+  frontmatter instead of the body.
+- **`loop-run` weak first example.** `skills/loop-run/SKILL.md` opens its example
+  list with bare `'run the loop'` — the only one of its examples lacking a
+  qualifier.
+
+## Proposal
+
+- Make the noun part of each "grade" phrase: evals → *"grade a run's outcome against
+  its SPEC"*; inspector → *"grade this harness/contract's readiness"*.
+- Trim `loop-evals`' `description` into the ~400–510-char sibling band by moving the
+  capability-summary prose into the skill body, leaving trigger phrases + a one-line
+  hook in frontmatter.
+- Qualify `loop-run`'s opening example: *"run the agent loop"* (or *"run this loop's
+  state machine"*).
+
+Keep every `description` a *quoted* YAML scalar (the suite quotes all of them).
+
+## The gate that proves the fix
+
+```bash
+python3 scripts/validate_frontmatter.py   # green
+python3 scripts/self_eval.py              # green
+```
+
+`loop-evals`' frontmatter length should land back in the sibling band; the two
+gates above are the whole review bar.

loop_engineer-0.8.0/docs/contributing/issues/02-good-first-qw10-self-eval-labels.md

@@ -0,0 +1,39 @@
+<!-- title: Label self_eval terminal/repair/eval checks honestly as doc-completeness -->
+<!-- labels: good first issue -->
+
+# Label self_eval terminal/repair/eval checks honestly as doc-completeness
+
+A naming/comment clarification (no behavioral change required) that keeps the gate
+honest about its own scope.
+
+## Problem
+
+Three `scripts/self_eval.py` checks are substring-presence scans over a single
+`SKILL.md` each, not behavioral enforcement:
+
+- `check_terminal_states` (`scripts/self_eval.py:185`) — `missing = [s for s in
+  facts["terminal_states"] if s not in text]` over `skills/loop-run/SKILL.md`.
+- `check_repair_fields` (`scripts/self_eval.py:193`) — same shape over
+  `skills/loop-repair/SKILL.md`.
+- `check_eval_layers_and_metrics` (`scripts/self_eval.py:206`) — normalized
+  substring presence over `skills/loop-evals/SKILL.md`.
+
+Each passes as long as the canonical words *appear in the prose*. Presenting them as
+"the hard pass/fail gate" risks a reader mistaking documentation-completeness for
+runtime-correctness enforcement — gaming requires only listing the canonical words.
+
+## Proposal
+
+Rename and/or comment the three checks as **documentation-completeness** checks (not
+behavioral enforcement), and say so where `self_eval` is described as a gate — in
+`CONTRIBUTING.md` (the "Ground rule" / self_eval mention) and in the README's
+structural-check list. No behavioral change is required if the checks are
+intentional; this is a scope-honesty clarification consistent with the suite's own
+posture.
+
+## The gate that proves the fix
+
+```bash
+python3 scripts/self_eval.py   # green (13 structural invariants)
+python3 -m pytest -q scripts/test_docs_claims.py   # README accuracy assertions green
+```

loop_engineer-0.8.0/docs/contributing/issues/03-good-first-emit-metrics-vocabulary.md

@@ -0,0 +1,44 @@
+<!-- title: Reconcile emit's iteration-outcome vocabulary with metrics' recognized tokens -->
+<!-- labels: good first issue -->
+
+# Reconcile emit's iteration-outcome vocabulary with metrics' recognized tokens
+
+The writer and the metrics reader disagree on the outcome vocabulary, so a RUNLOG
+written entirely through the sanctioned writer can still look "dirty" to `loop
+metrics`.
+
+## Problem
+
+`loop/emit.py` `_ITERATION_OUTCOMES` (`loop/emit.py:26`) accepts `approval_requested`
+and `replanned`, but `scripts/metrics.py` `_KNOWN_OUTCOME_TOKENS`
+(`scripts/metrics.py:101`, built from `_SUCCESS_OUTCOME_TOKENS` +
+`_HONEST_RED_OUTCOME_TOKENS`) recognizes neither. So an iteration appended via
+`emit.append_iteration(..., outcome="approval_requested")` — a fully valid write —
+surfaces under `provenance.unrecognized_outcomes`.
+
+Checkable at this commit:
+
+```python
+import sys; sys.path.insert(0, "scripts"); import metrics
+from loop.emit import _ITERATION_OUTCOMES
+print([o for o in _ITERATION_OUTCOMES if o not in metrics._KNOWN_OUTCOME_TOKENS])
+# -> ['approval_requested', 'replanned']
+```
+
+## Proposal
+
+Decide the canonical vocabulary and align the two ends:
+
+- either add `approval_requested` and `replanned` to metrics' honest-red set
+  (`scripts/metrics.py` `_HONEST_RED_OUTCOME_TOKENS`) — they are known, non-success
+  outcomes, so they belong there and should not read as "unrecognized synonyms";
+- or narrow `emit`'s accepted set to the tokens metrics already knows.
+
+Add a round-trip regression test: `emit.append_iteration` writing every allowed
+outcome, then `compute_metrics(...)` reports `provenance.unrecognized_outcomes == []`.
+
+## The gate that proves the fix
+
+```bash
+python3 -m pytest scripts/test_metrics.py scripts/test_emit.py   # green
+```

loop_engineer-0.8.0/docs/contributing/issues/04-help-wanted-openhands-recipe.md

@@ -0,0 +1,42 @@
+<!-- title: Integration recipe: OpenHands run → FCR gate -->
+<!-- labels: help wanted -->
+
+# Integration recipe: OpenHands run → FCR gate
+
+An integration recipe that layers the loop-contract's false-completion gate over an
+OpenHands run. **Composes, doesn't compete:** OpenHands is the EXECUTE tier — it
+writes, runs, and tests code in a sandbox; "done" is still the agent stopping. Loop
+Engineer wraps that exit in a typed terminal + held-out gate. This adds a layer, it
+does not replace the runtime.
+
+## Problem / opportunity
+
+The design is already written — `docs/superpowers/specs/2026-06-30-st3-integration-adapters.md`
+§5.3 — but no runnable recipe ships yet. The shipped LangGraph and Temporal recipes
+are the template to follow:
+
+- the adapter seam: `loop/integrations.py` (`EngineOutcome` → `to_terminal_state`);
+- an env-guarded end-to-end example under `examples/` (skips cleanly when the engine
+  isn't installed, like `examples/langgraph-emit/` and `examples/temporal-certify/`);
+- a CI job that exercises it.
+
+The specialization from §5.3: OpenHands' `AgentStuckError` / max-iteration stop maps
+to `FailedBudget`; a sandbox that touched a holdout/answer-key path (HIGH anti-cheat
+finding) maps to `FailedUnverifiable` — the exact "the runtime ran tests but the
+agent peeked" case OpenHands can't itself catch.
+
+## Proposal
+
+Follow the `docs/integrations/langgraph.md` recipe end-to-end for OpenHands: read the
+run's trajectory as the anti-cheat trajectory input, run the holdout split, and
+project the engine outcome through `to_terminal_state` into a typed terminal.
+
+## The gate that proves the fix
+
+```bash
+python3 -m loop doctor <recipe-out>   # doctor round-trip is clean
+```
+
+Plus a pinned false-completion invariant test: visible-green / holdout-red must
+project to `FailedUnverifiable` with `false_completion: true`, and **never**
+`Succeeded`.

loop_engineer-0.8.0/docs/contributing/issues/05-help-wanted-ruflo-recipe.md

@@ -0,0 +1,39 @@
+<!-- title: Integration recipe: ruflo swarm → acceptance gate -->
+<!-- labels: help wanted -->
+
+# Integration recipe: ruflo swarm → acceptance gate
+
+An integration recipe that layers a single acceptance gate over a ruflo swarm.
+**Composes, doesn't compete:** ruflo is the ORCHESTRATE tier — a multi-agent swarm
+whose terminal is "the coordinator decided the objective is met," a self-report
+across N agents. Loop Engineer adds one acceptance gate the swarm must pass *as a
+whole*. This adds a layer, it does not replace the swarm.
+
+## Problem / opportunity
+
+The design is written — `docs/superpowers/specs/2026-06-30-st3-integration-adapters.md`
+§5.4 — but no runnable recipe ships yet. Same shape as the OpenHands recipe (issue
+04): follow the shipped LangGraph/Temporal recipes as the template (`loop/integrations.py`
+adapter, an env-guarded end-to-end example, a CI job).
+
+The seam is the swarm's terminal hook: **no individual agent may declare the swarm
+done** — the acceptance gate does. Register the gate as the swarm's terminal hook
+(ruflo exposes hooks / an MCP coordination server), read the merged diff and agent
+trails as the anti-cheat inputs, run the holdout split, and project through
+`to_terminal_state`.
+
+## Proposal
+
+Follow the `docs/integrations/langgraph.md` recipe end-to-end for a ruflo swarm,
+wiring the gate as the terminal hook so the swarm's collective "done" is decided by
+the held-out gate, not by any agent's self-report.
+
+## The gate that proves the fix
+
+```bash
+python3 -m loop doctor <recipe-out>   # doctor round-trip is clean
+```
+
+Plus a pinned false-completion invariant test: visible-green / holdout-red must
+project to `FailedUnverifiable` with `false_completion: true`, and **never**
+`Succeeded`.

loop_engineer-0.8.0/docs/contributing/issues/06-help-wanted-gap-reports.md

@@ -0,0 +1,42 @@
+<!-- title: Foreign-harness gap reports — the inspect scoreboard pipeline -->
+<!-- labels: help wanted -->
+
+# Foreign-harness gap reports — the inspect scoreboard pipeline
+
+Contribute a read-only `loop inspect` gap report for another public harness layout —
+the second entry in an "inspect N public harnesses" scoreboard.
+
+## Problem / opportunity
+
+`docs/gap-reports/superpowers.md` is the template and the first entry. **Composes,
+doesn't compete:** a gap report reads a foreign layout read-only and names the gaps a
+loop-contract would *close* at the finish line — it is not a criticism of the foreign
+harness or of the (fictional) work in the fixture. `inspect` labels a foreign layout
+`advisory: true`; a foreign layout is read for gaps, never graded as a failing
+contract.
+
+The template's provenance rules are load-bearing:
+
+- every claim is checkable against **one vendored, sanitized fixture** checked into
+  `examples/` — no version-general claims about the foreign harness itself;
+- the report carries the §14 A1–E1 conformance table (condensed from
+  `reference/repo-os-contract.md` §14), read against that fixture;
+- complement framing throughout ("composes, doesn't compete").
+
+## Proposal
+
+For another public harness layout: vendor a fictional, sanitized fixture under
+`examples/<harness>-run/`, then author `docs/gap-reports/<harness>.md` following
+`docs/gap-reports/superpowers.md` — the provenance blockquote, the §14 A1–E1 table,
+the `inspect` reading, and "what emitting the contract would add," with every factual
+claim restricted to the fixture.
+
+## The gate that proves the fix
+
+```bash
+python3 -m loop inspect examples/<harness>-run   # produces a scored report
+```
+
+The exit criteria follow the `scripts/test_foreign_inspect.py` patterns (scored,
+`foreign_layout` labeled, `advisory: true`), and the report follows the template's
+provenance rules.

loop_engineer-0.8.0/docs/contributing/issues/07-help-wanted-emit-scaffold-runlog-seed.md

@@ -0,0 +1,61 @@
+<!-- title: emit.open_contract seeds a metrics-dirty RUNLOG placeholder -->
+<!-- labels: help wanted -->
+
+# emit.open_contract seeds a metrics-dirty RUNLOG placeholder
+
+A fresh scaffold is born "metrics-dirty," which forces every integration recipe to
+work around it. Fix the root so the workaround can be retired.
+
+## Problem
+
+`loop.emit.open_contract` scaffolds a `RUNLOG.md` from `templates/RUNLOG.md.tmpl`,
+whose outcome block (`templates/RUNLOG.md.tmpl:27`) is
+`` `{{ITERATION_OUTCOME}}` — one of: `task_passed`, … ``. `loop/scaffold.py`
+`_substitutions` has no `ITERATION_OUTCOME` key, so `_fill` renders the unknown token
+as the literal `REPLACE` (`loop/scaffold.py:95`). `scripts/metrics.py` then parses
+`REPLACE` as an unrecognized outcome token, so a just-scaffolded loop is
+metrics-dirty until real iterations land.
+
+Checkable at this commit:
+
+```python
+import sys, tempfile, os
+from loop import emit
+sys.path.insert(0, "scripts"); import metrics
+ws = os.path.join(tempfile.mkdtemp(), "scaffold_check")
+emit.open_contract(ws)
+print(metrics.compute_metrics(ws)["provenance"]["unrecognized_outcomes"])
+# -> ['replace']
+```
+
+Because of this, both engine recipes reset `<ws>/RUNLOG.md` to emit's fresh header
+right after `open_contract`: `examples/langgraph-emit/graph_example.py:105` and
+`examples/temporal-certify/workflow_example.py:159`. That inline reset is a
+documented carve-out in the plan's Global Constraints
+(`docs/superpowers/plans/2026-07-08-v0.8.0-composes-the-field.md`, "Adjudicated
+carve-out").
+
+## Proposal
+
+Make the scaffold not seed a metrics-flagged placeholder. Options, pick one:
+
+- a first-class affordance — `emit.open_contract(seed_runlog=False)` or
+  `emit.reset_runlog(ws)` — so a caller that scores from iteration 0 opts out of the
+  placeholder; or
+- render the placeholder outcome as a value `metrics` recognizes (or omit the seeded
+  iteration block entirely) so a fresh scaffold is metrics-clean by construction.
+
+The reset only ever strips a placeholder — it never fabricates state — so the
+affordance must preserve that (no synthetic completed iteration).
+
+## The gate that proves the fix / acceptance
+
+- A freshly-scaffolded loop reports `provenance.unrecognized_outcomes == []` (the
+  snippet above returns `[]`).
+- Both recipes drop their inline `RUNLOG.md` resets and still pass their gates.
+- The plan's Global-Constraints carve-out text can be retired.
+
+```bash
+python3 -m pytest scripts/test_metrics.py scripts/test_emit.py   # green
+python3 -m loop doctor <recipe-workspace>   # recipe still clean after the inline reset is removed
+```

loop_engineer-0.8.0/docs/gap-reports/superpowers.md

@@ -0,0 +1,107 @@
+# Gap report — Superpowers (foreign-harness inspect)
+
+> **Provenance.** Evaluated **only** against the vendored fixture
+> [`examples/superpowers-run/`](../../examples/superpowers-run/) — fictional,
+> sanitized content, checked in. No version-general claims about Superpowers
+> itself are made or implied: every statement below is checkable against that
+> one directory.
+> **Date:** 2026-07-08.
+> **Reproduce:** `python3 -m loop inspect examples/superpowers-run`
+
+## Composes, doesn't compete
+
+Superpowers is a skills library — it drives *how* an agent works. The fixture
+vendors exactly the layout such a run leaves behind: a design spec under
+`docs/superpowers/specs/`, a plan of `- [x]` checkboxes under
+`docs/superpowers/plans/`, and a prose `progress.md` journal. Loop Engineer is
+the contract layer — it proves *how the work ended*. The two **compose**: a
+Superpowers-driven run can emit a Loop-Engineer contract at the finish line.
+This report is not a criticism of Superpowers or of the (fictional) work in the
+fixture; the low score below measures only what a spec/plan/journal layout
+*structurally cannot prove*.
+
+## §14 conformance — read against the fixture
+
+The "What the standard requires" column is condensed from
+[`reference/repo-os-contract.md`](../../reference/repo-os-contract.md) §14.
+
+| Item | What the standard requires | Fixture status |
+|---|---|---|
+| A1 | `.loop/manifest.yaml` valid against `manifest@1` incl. the canonical 7 `terminal_states` | **unmet** — no `.loop/` exists |
+| A2 | `.loop/state.json` valid against `state@1` | **unmet** |
+| A3 | `TASKS.json` valid against `tasks@1` (no dup ids; no evidence-free `done`) | **unmet** — plan checkboxes carry no evidence field at all |
+| A4 | `RUNLOG.md` present | **unmet** — the journal (`progress.md`) narrates but is not an iteration log |
+| B1 | exactly-one-of: no terminal vs valid terminal pair | **structurally unprovable** — the layout has no terminal record; "marking the work complete" lives in prose |
+| B2 | `terminal@1` with `criteria_met`/`evidence`/`false_completion`; honest `Succeeded` rules | **structurally unprovable** |
+| C1–C3 | receipts / repair / rollout validate when present | **absent** (nothing to check — and nothing to mine for FCR/RP) |
+| D1–D2 | versioned `schema` keys; additive tolerance | **unmet** — no artifact carries a schema id |
+| E1 | `doctor` lifecycle report consistent with B1 | **unmet** — `doctor` (correctly) refuses: no contract |
+
+Each row is checkable against the fixture: `examples/superpowers-run/` contains
+only `README.md`, `docs/superpowers/specs/2026-07-08-csv-dedupe-design.md`,
+`docs/superpowers/plans/2026-07-08-csv-dedupe.md`, and
+`.superpowers/sdd/progress.md`. There is no `.loop/`, no `schema:` key in any
+file, and `progress.md`'s closing line is the prose "Marking the work
+complete." — the exact false-completion surface B1/B2 exist to make typed.
+Running `python3 -m loop doctor examples/superpowers-run` returns `ok: false`
+with `lifecycle: unknown` and `missing_file` issues for every contract
+artifact (E1).
+
+## `inspect` reading
+
+```json
+{
+  "target": "examples/superpowers-run",
+  "score": 12,
+  "terminal_states_covered": 0,
+  "present": [
+    "defines verifiable success criteria"
+  ],
+  "gaps": [
+    "no independent verification (verify-* script / TASKS verify command) — success is self-asserted",
+    "no approval gates declared for side-effects (destructive / secret / production / money)",
+    "no false-completion defense: no recorded holdout/anti-cheat invocation (a self-asserted false_completion flag or prose mention earns no credit)",
+    "no plan-then-execute discipline for untrusted/web reads (prompt-injection surface)",
+    "0/7 terminal states present — missing Succeeded, FailedUnverifiable, FailedBlocked, FailedBudget, FailedSafety, FailedSpecGap, AbortedByHuman (loop can end in a silent 'completed')"
+  ],
+  "verdict": "weak",
+  "foreign_layout": "superpowers",
+  "advisory": true
+}
+```
+
+The fixture scores **weak** (`score: 12`, `terminal_states_covered: 0`),
+labeled `foreign_layout: superpowers` and `advisory: true`. Read this plainly:
+the low score measures what the layout *cannot prove*, not the quality of the
+work, nor of Superpowers. `advisory: true` is the whole point — a foreign
+layout is read for gaps, never graded as a failing contract.
+
+## What emitting the contract would add
+
+- **A typed terminal instead of prose "complete."** The `Succeeded`/`Failed*`
+  record replaces `progress.md`'s free-text "Marking the work complete." with
+  one of the canonical 7 states plus a `false_completion` boolean.
+- **A held-out gate that makes false completion *measurable*.** An
+  anti-cheat/holdout invocation is what turns "tests pass locally" into a
+  third-party-checkable verdict — the missing `false-completion defense` gap.
+- **An evidence trail.** `criteria_met` maps each success criterion to a check;
+  verify bundles under `.loop/artifacts/` back the terminal instead of a
+  self-assertion.
+- **FCR / RP derivable by `loop metrics`.** With receipts and repair records on
+  disk, false-completion-rate and repair-productivity are *computed*, not
+  claimed (the C1–C3 "nothing to mine for FCR/RP" gap).
+
+The *how* is small: four `loop.emit` calls — `open_contract`,
+`append_iteration`, `append_receipt`, `terminate` — at the run's finish line.
+That path is worked end-to-end for a real engine in
+[`docs/integrations/langgraph.md`](../integrations/langgraph.md).
+
+## This is a seed
+
+This is the first entry in an "inspect N public harnesses" scoreboard: read a
+foreign layout read-only, name the gaps a contract would close, keep every
+claim checkable against a vendored fixture. Contributions of further gap
+reports are welcome — this file is the template. See the drafted contributor
+issue
+[`docs/contributing/issues/06-help-wanted-gap-reports.md`](../contributing/issues/06-help-wanted-gap-reports.md)
+(`help wanted: gap reports`, filed on GitHub at release).