simplicio-loop 3.20.1__tar.gz → 3.22.4__tar.gz

{simplicio_loop-3.20.1/simplicio_loop.egg-info → simplicio_loop-3.22.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: simplicio-loop
-Version: 3.20.1
-Summary: The Universal Looping AI Orchestrator — a runtime-agnostic super-plugin (6 skills) that drains any queue of work end-to-end on any LLM/runtime.
+Version: 3.22.4
+Summary: The Universal Looping AI Orchestrator — a runtime-agnostic super-plugin (7 skills) that drains any queue of work end-to-end on any LLM/runtime.
 Author-email: Wesley Simplicio <wesleybob4@gmail.com>
 License: MIT
 Project-URL: Homepage, https://github.com/wesleysimplicio/simplicio-loop
@@ -19,8 +19,8 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: simplicio-mapper>=0.13.0
-Requires-Dist: simplicio-cli>=0.9.0
+Requires-Dist: simplicio-mapper>=0.16.0
+Requires-Dist: simplicio-cli>=0.9.3
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Provides-Extra: ml
@@ -30,10 +30,10 @@ Dynamic: license-file
 
 # simplicio-loop
 
-**The Universal Looping AI Orchestrator** — a runtime-agnostic **super-plugin** (6 skills) that
+**The Universal Looping AI Orchestrator** — a runtime-agnostic **super-plugin** (7 skills) that
 drains any queue of work end-to-end on **any LLM / runtime**:
-`discover → implement → verify → merge → close → watch 24/7`, behind safety gates and a hard cost
-kill-switch, at up to **96% fewer tokens**. Not a chatbot. A worker.
+`discover → implement → verify → merge → close → watch 24/7`, behind safety gates and evidence
+checks, at up to **96% fewer tokens**. Not a chatbot. A worker.
 
 ![simplicio-loop](https://raw.githubusercontent.com/wesleysimplicio/simplicio-loop/main/assets/simplicio-loop-hero.jpg)
 
@@ -53,26 +53,27 @@ simplicio-loop install --global   # into ~/.claude (all projects)
 Now invoke it from your agent runtime (Claude Code, Cursor, Codex, Gemini, …):
 
 ```
-/simplicio-tasks finish all the open issues
+/simplicio-loop finish all the open issues
 ```
 
-## What you get — 6 skills
+## What you get — 7 skills
 
 | Skill | What it does |
 |---|---|
-| `simplicio-tasks` | The orchestrator loop: discover → implement → verify → merge → close → watch 24/7. |
-| `simplicio-loop` | Hardened Ralph loop — re-feed the goal until an evidence-gated `<promise>` or a cap. |
+| `simplicio-loop` | Unified public entrypoint: orchestrator core + hardened loop behind one command. |
+| `simplicio-tasks` | Legacy alias kept only for compatibility with older installs and saved prompts. |
 | `simplicio-orient` | Terminal-first token economy — output-reduction catalog, tee-cache, signatures-read. |
 | `simplicio-review` | Adversarial review — parallel subagents on distinct rubrics, deduped into one verdict. |
 | `simplicio-compress` | Output + memory compression, byte-preserving identifiers. |
+| `simplicio-autoresearch` | Evolutionary mutate/eval/keep-revert optimizer — yool-guardrailed caps, git-isolated branch, anti-Goodhart gate-first eval. |
 | `simplicio-learn` | Retrospective — durable, deduped lessons written back to memory. |
 
 ## Highlights
 
 - **11 runtimes, one protocol** — Claude Code, Codex, VS Code/Copilot, Cursor, Antigravity, Kiro,
   OpenCode, Gemini, Aider, Hermes, OpenClaw.
-- **Evidence-gated completion** — never a false "done"; exits only on a verified `<promise>` or a
-  cap / budget / STOP.
+- **Evidence-gated completion** — never a false "done"; exits only on a verified `<promise>`,
+  cap, spindle handoff, or STOP.
 - **Token economy** — honest "answer concisely" baseline; savings credited only on verified-correct
   outcomes.
 

{simplicio_loop-3.20.1 → simplicio_loop-3.22.4}/PYPI.md

@@ -1,9 +1,9 @@
 # simplicio-loop
 
-**The Universal Looping AI Orchestrator** — a runtime-agnostic **super-plugin** (6 skills) that
+**The Universal Looping AI Orchestrator** — a runtime-agnostic **super-plugin** (7 skills) that
 drains any queue of work end-to-end on **any LLM / runtime**:
-`discover → implement → verify → merge → close → watch 24/7`, behind safety gates and a hard cost
-kill-switch, at up to **96% fewer tokens**. Not a chatbot. A worker.
+`discover → implement → verify → merge → close → watch 24/7`, behind safety gates and evidence
+checks, at up to **96% fewer tokens**. Not a chatbot. A worker.
 
 ![simplicio-loop](https://raw.githubusercontent.com/wesleysimplicio/simplicio-loop/main/assets/simplicio-loop-hero.jpg)
 
@@ -23,26 +23,27 @@ simplicio-loop install --global   # into ~/.claude (all projects)
 Now invoke it from your agent runtime (Claude Code, Cursor, Codex, Gemini, …):
 
 ```
-/simplicio-tasks finish all the open issues
+/simplicio-loop finish all the open issues
 ```
 
-## What you get — 6 skills
+## What you get — 7 skills
 
 | Skill | What it does |
 |---|---|
-| `simplicio-tasks` | The orchestrator loop: discover → implement → verify → merge → close → watch 24/7. |
-| `simplicio-loop` | Hardened Ralph loop — re-feed the goal until an evidence-gated `<promise>` or a cap. |
+| `simplicio-loop` | Unified public entrypoint: orchestrator core + hardened loop behind one command. |
+| `simplicio-tasks` | Legacy alias kept only for compatibility with older installs and saved prompts. |
 | `simplicio-orient` | Terminal-first token economy — output-reduction catalog, tee-cache, signatures-read. |
 | `simplicio-review` | Adversarial review — parallel subagents on distinct rubrics, deduped into one verdict. |
 | `simplicio-compress` | Output + memory compression, byte-preserving identifiers. |
+| `simplicio-autoresearch` | Evolutionary mutate/eval/keep-revert optimizer — yool-guardrailed caps, git-isolated branch, anti-Goodhart gate-first eval. |
 | `simplicio-learn` | Retrospective — durable, deduped lessons written back to memory. |
 
 ## Highlights
 
 - **11 runtimes, one protocol** — Claude Code, Codex, VS Code/Copilot, Cursor, Antigravity, Kiro,
   OpenCode, Gemini, Aider, Hermes, OpenClaw.
-- **Evidence-gated completion** — never a false "done"; exits only on a verified `<promise>` or a
-  cap / budget / STOP.
+- **Evidence-gated completion** — never a false "done"; exits only on a verified `<promise>`,
+  cap, spindle handoff, or STOP.
 - **Token economy** — honest "answer concisely" baseline; savings credited only on verified-correct
   outcomes.
 

{simplicio_loop-3.20.1 → simplicio_loop-3.22.4}/README.md

@@ -1,23 +1,24 @@
-# 🔁 simplicio-tasks — The Universal Looping AI Orchestrator
+# 🔁 simplicio-loop — The Universal Looping AI Orchestrator
 
 <p align="center">
   <img src="assets/simplicio-loop-hero.jpg" alt="simplicio-loop" width="920" />
 </p>
 
 <p align="center">
+  <a href="https://github.com/wesleysimplicio/simplicio-loop/actions/workflows/ci.yml"><img src="https://github.com/wesleysimplicio/simplicio-loop/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://github.com/wesleysimplicio/simplicio-loop/stargazers"><img src="https://img.shields.io/github/stars/wesleysimplicio/simplicio-loop?style=social" alt="Stars"></a>
-  <a href="#-the-11-skills--accelerators"><img src="https://img.shields.io/badge/skills-11-7C3AED" alt="11 skills"></a>
+  <a href="#-the-7-skills--5-accelerators"><img src="https://img.shields.io/badge/skills-7-7C3AED" alt="7 skills"></a>
   <a href="#-source-adapters"><img src="https://img.shields.io/badge/source%20adapters-5-00E08A" alt="5 source adapters"></a>
-  <a href="#-11-runtimes-one-protocol"><img src="https://img.shields.io/badge/runtimes-11-2563EB" alt="11 runtimes"></a>
+  <a href="#-11-runtimes-one-protocol"><img src="https://img.shields.io/badge/runtimes-11%20(3%20garantidos%2B8%20best--effort)-2563EB" alt="11 runtimes (3 guaranteed + 8 best-effort)"></a>
   <a href="#-the-48-extension-points"><img src="https://img.shields.io/badge/extension%20points-48-00E08A" alt="48 extension points"></a>
-  <a href="#-token-economy"><img src="https://img.shields.io/badge/tokens-up%20to%2096%25%20fewer-green" alt="Up to 90% fewer tokens"></a>
+  <a href="#-token-economy"><img src="https://img.shields.io/badge/savings-unverified-888888" alt="Savings — unverified"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
   <a href="https://discord.gg/wM6tr7xVb"><img src="https://img.shields.io/badge/Discord-Join%20Simplicio-5865F2?logo=discord&logoColor=white" alt="Join the Simplicio Discord"></a>
 </p>
 
 <p align="center">
   <a href="#-tldr">TL;DR</a> ·
-  <a href="#-the-11-skills--accelerators">11 Skills</a> ·
+  <a href="#-the-7-skills--5-accelerators">7 Skills</a> ·
   <a href="#-source-adapters">Source Adapters</a> ·
   <a href="#-11-runtimes-one-protocol">11 Runtimes</a> ·
   <a href="#-the-loop">The Loop</a> ·
@@ -49,8 +50,8 @@
 
 ## ⚡ TL;DR
 
-**simplicio-tasks** is a runtime-agnostic **super-plugin** — one autonomous looping
-orchestrator (invoked as **`/simplicio-tasks`**) plus **five satellite skills** — that turns any
+**simplicio-loop** is a runtime-agnostic **super-plugin** — one autonomous looping
+orchestrator (invoked as **`/simplicio-loop`**) plus **five satellite skills** — that turns any
 strong LLM (Claude, Codex, Copilot, Gemini, Cursor, local models) into a self-driving worker. You
 point it at a body of work — *"finish all the open issues"*, *"clear the CI queue"*, *"drain the Jira board"* — and it
 runs the whole lifecycle on its own:
@@ -60,11 +61,11 @@ runs the whole lifecycle on its own:
 It discovers work from any source (GitHub Issues, Jira, Azure DevOps, agentsview sessions, and
 more), dedups, auto-scales an agent fleet to your machine, implements each item through a quality
 loop that **runs the code (not just compiles it)**, opens PRs, resolves CI/review feedback, merges,
-and keeps watching **24/7** for new work — all behind safety gates and a hard cost kill-switch.
+and keeps watching **24/7** for new work — all behind safety gates and evidence checks.
 
 ```text
-/simplicio-tasks finish all open issues
-→ identity + pre-flight (kill-switch, auth, watcher)
+/simplicio-loop finish all open issues
+→ identity + pre-flight (auth, watcher, STOP path)
 → discover 50 issues · dedup · build dependency DAG
 → autoscale fleet = 14 · pipeline implement→review→merge
 → each item: read body+ACs → orient code → plan → edit → run → verify → PR
@@ -75,32 +76,36 @@ and keeps watching **24/7** for new work — all behind safety gates and a hard
 Three things make it different: it is a **super-plugin of focused skills**, it runs the **same
 protocol on 11 runtimes**, and it does all of this with **aggressive, honest token economy**.
 
+The skill installs **standalone** too: you do **not** need `simplicio-runtime` or any mandatory
+runtime-native component just to use `simplicio-loop`. Native binds, operators, capture services,
+and the wider Simplicio runtime stack are optional accelerators on top of the core skill bundle.
+
+<p align="center">
+  <img src="assets/simplicio-loop-infographic.png" alt="simplicio-loop detailed infographic: standalone install, optional native binds, 7 skills, 5 accelerators, 11 runtimes, 5 source adapters, and proof gates" width="920" />
+</p>
+
 Within the Simplicio product line, this repo is also the **current reference task flow** for
 company work. `simplicio-runtime` is the unified entrypoint going forward, but it is expected to
 reuse this loop's evidence-gated converge/drain discipline, durable attempt journal, and worker
 coordination patterns instead of creating a separate task semantics.
 
-<p align="center">
-  <img src="assets/simplicio-loop-infographic.png" alt="simplicio-loop — the whole system at a glance: 6 core skills, 5 satellites, 5 accelerators, 48 extension points, 11 runtimes, up to 90% fewer tokens" width="920" />
-</p>
-
 ---
 
 ## 🤖 LLM front door
 
-If you are an agent/runtime entering this repo cold, read `llms.txt` first for the short operational contract, then `AGENTS.md`, then `.claude/skills/simplicio-tasks/SKILL.md`.
+If you are an agent/runtime entering this repo cold, read `llms.txt` first for the short operational contract, then `AGENTS.md`, then `.claude/skills/simplicio-loop/SKILL.md`.
 
 ---
 
 ## 📘 Official capability record
 
-The complete, official roster of what `simplicio-tasks` ships — every capability below is **real,
-runnable, and tested** (`python3 scripts/check.py`: claims-audit 5/5 + local test suite). Each links to its
+The complete, official roster of what `simplicio-loop` ships — every capability below is **real,
+runnable, and tested** (`python3 scripts/check.py`: claims-audit 9/9 + 245 passed). Each links to its
 deep section and its worker.
 
 | Capability | What it does | Proof / worker | Details |
 |---|---|---|---|
-| 🎬 **Video evidence** (`video_evidence`) | Records the **real browser session** as moving proof a UI change works (Playwright, default); renders a **deterministic captioned MP4** with [hyperframes](https://github.com/heygen-com/hyperframes) for an explicit explainer request (`/simplicio-tasks make a video of screen X`) | `scripts/video_evidence.py` · BLOCKED (never fake-pass) without the toolchain | [§ Video evidence](#-video-evidence--playwright-by-default-hyperframes-on-request) |
+| 🎬 **Video evidence** (`video_evidence`) | Records the **real browser session** as moving proof a UI change works (Playwright, default); renders a **deterministic captioned MP4** with [hyperframes](https://github.com/heygen-com/hyperframes) for an explicit explainer request (`/simplicio-loop make a video of screen X`) | `scripts/video_evidence.py` · BLOCKED (never fake-pass) without the toolchain | [§ Video evidence](#-video-evidence--playwright-by-default-hyperframes-on-request) |
 | 🧠 **Attempt memory + stall detector** | A durable run-journal (`.orchestrator/loop/journal.jsonl`) + a stall detector so the loop **changes strategy instead of oscillating**; incremental triage (`since`) reads only the delta each turn, and optional stage lineage makes retries/governance explicit | `scripts/loop_journal.py` · `selftest` 13/13 | [§ Anti-oscillation](#-attempt-memory--stall-detector-anti-oscillation) |
 | 🧭 **Repo conventions** (`repo_conventions`) | **Learns the repo's own playbook** — mines git history + merged PRs + static config into `.orchestrator/conventions.json` so every new branch/commit/PR mirrors the team's established style; worktree-per-item isolation is the default | `scripts/repo_conventions.py` · `selftest` 19/19 | [§ The full flow](#️-the-full-flow--from-demand-to-delivery) |
 | 🧩 **Scope reflection** (`dependency_graph`) | Maps local dependencies, reverse dependents, and related tests from the planned touched files; blocks task plans that ignore callers, sibling files, or proof points before the edit starts | `scripts/impact_audit.py` · `selftest` | [§ Tests & local checks](#-tests--local-checks-no-paid-ci) |
@@ -112,7 +117,7 @@ deep section and its worker.
 Two loop **modes** make termination explicit: **converge** (a single hard task — ends on the
 evidence-gated `<promise>` or a stall escalation) vs **drain** (a queue — ends when the source
 re-query stays empty K rounds). Both still obey the universal exits (promise+evidence,
-`max_iterations`, budget, STOP).
+`max_iterations`, STOP).
 
 > Loop scoring across this line of work: **7.5** (strong design, unproven) → **9** (attempt memory +
 > anti-oscillation) → **9.5** (reproducible local proof) → **~10** (enforced safety + complete loop
@@ -120,30 +125,31 @@ re-query stays empty K rounds). Both still obey the universal exits (promise+evi
 
 ---
 
-## 🧠 The 11 skills & accelerators
+## 🧠 The 7 skills + 5 accelerators
 
-The orchestrator core + five satellites + five accelerators/integrations. Each satellite is
+The orchestrator core + six satellites + five accelerators/integrations. Each satellite is
 **optional** — when loaded, the orchestrator delegates to it (richer + cheaper); when absent, the
 inline protocol covers 100%. Accelerators are **auto-detected** — present = used, absent = LLM
 fallback.
 
 | # | Capability | Absorbs | What it does | Token impact |
 |---|---|---|---|---|
-| 1 | 🔁 **simplicio-tasks** | — | The orchestrator loop: 48 extension points, dual-path router, self-audit convergence | Core |
-| 2 | ♾️ **simplicio-loop** | [ralph-loop](https://github.com/cursor/plugins/tree/main/ralph-loop) | Hardened Ralph loop: evidence-gated `<promise>` exit, max_iterations cap | Loop drive |
+| 1 | 🔁 **simplicio-loop** | — | Unified public entrypoint: orchestrator core + hardened loop behind one command | Core + loop |
+| 2 | ↩️ **simplicio-tasks** | legacy alias | Compatibility shim for older installs and saved prompts | Legacy alias |
 | 3 | 🧱 **simplicio-orient** | [rtk](https://github.com/rtk-ai/rtk) + [caveman](https://github.com/JuliusBrussee/caveman) | Terminal-first execution, output-reduction catalog, tee-cache, signatures-read | L0 deterministic |
 | 4 | 🔥 **simplicio-review** | [thermos](https://github.com/cursor/plugins/tree/main/thermos) | Parallel adversarial review on distinct rubrics → deduped verdict | Quality gate |
 | 5 | 🗜️ **simplicio-compress** | [caveman](https://github.com/JuliusBrussee/caveman) | Output + memory compression, fail-closed `transform_guard` | 40-60% fewer |
 | 6 | 🎓 **simplicio-learn** | [teaching](https://github.com/cursor/plugins/tree/main/teaching) | Post-run retrospective → durable, deduped lessons in memory | Smarter each run |
-| 7 | 🧭 **Understand Anything** | [Egonex-AI](https://github.com/Egonex-AI/Understand-Anything) | Knowledge graph orient: semantic search, guided tours, dependency graph | **L0 zero tokens** |
-| 8 | 📊 **agentsview** | [kenn-io](https://github.com/kenn-io/agentsview) | Session analytics, cost tracking, stalled-session discovery | **L1** SQL only |
-| 9 | ⚡ **LMCache** | [LMCache](https://github.com/LMCache/LMCache) | KV cache between loop turns — 40-70% TTFT reduction on local models | GPU time ↓ |
-| 10 | 🗜️ **Simplicio capture engine** | `engine/simplicio_engine.py` (native, stdlib-only) | Transparent capture proxy: forwards to the real provider, measures + deterministically compresses, writes `proxy_savings.json` | **deterministic** |
-| 11 | 🎬 **video_evidence** | Playwright (default) · [hyperframes](https://github.com/heygen-com/hyperframes) (on request) | Records the **real session** as moving proof of a UI change (Playwright); renders a **deterministic captioned MP4** explainer with hyperframes when the video IS the deliverable | Evidence producer |
+| 7 | 🧪 **simplicio-autoresearch** | Karpathy [autoresearch](https://github.com/balukosuri/Andrej-Karpathy-s-Autoresearch-As-a-Universal-Skill) + ECC `autoresearch-agent` | Evolutionary mutate/eval/keep-revert loop: yool-guardrailed caps, git-isolated branch, anti-Goodhart gate-first eval, `savings-event` receipt | Auto-optimize |
+| 8 | 🧭 **Understand Anything** | [Egonex-AI](https://github.com/Egonex-AI/Understand-Anything) | Knowledge graph orient: semantic search, guided tours, dependency graph | **L0 zero tokens** |
+| 9 | 📊 **agentsview** | [kenn-io](https://github.com/kenn-io/agentsview) | Session analytics, cost tracking, stalled-session discovery | **L1** SQL only |
+| 10 | ⚡ **LMCache** | [LMCache](https://github.com/LMCache/LMCache) | KV cache between loop turns — 40-70% TTFT reduction on local models | GPU time ↓ |
+| 11 | 🗜️ **Simplicio capture engine** | `engine/simplicio_engine.py` (native, stdlib-only) | Transparent capture proxy: forwards to the real provider, measures + deterministically compresses, writes `proxy_savings.json` | **deterministic** |
+| 12 | 🎬 **video_evidence** | Playwright (default) · [hyperframes](https://github.com/heygen-com/hyperframes) (on request) | Records the **real session** as moving proof of a UI change (Playwright); renders a **deterministic captioned MP4** explainer with hyperframes when the video IS the deliverable | Evidence producer |
 
 Each skill lives under [`.claude/skills/`](.claude/skills); each accelerator has a reference doc
-under `.claude/skills/simplicio-tasks/references/` (the video producer:
-[`video-evidence.md`](.claude/skills/simplicio-tasks/references/video-evidence.md), worker
+under `.claude/skills/simplicio-loop/references/` (the video producer:
+[`video-evidence.md`](.claude/skills/simplicio-loop/references/video-evidence.md), worker
 [`scripts/video_evidence.py`](scripts/video_evidence.py)).
 
 ---
@@ -161,22 +167,29 @@ The orchestrator discovers work from any source via pluggable adapters. Each exp
 | **agentsview sessions** | `scripts/agentsview_adapter.py` | Stalled session recovery + cost observability |
 | Local files / CI queue | filesystem / CI API | Internal work tracking |
 
-See each adapter's reference doc under `.claude/skills/simplicio-tasks/references/`.
+See each adapter's reference doc under `.claude/skills/simplicio-loop/references/`.
 
 ---
 
-## 🌐 11 runtimes, one protocol
+## 🌐 11 runtimes, one protocol — 3 guaranteed + 8 best-effort
 
 One universal skill core + one set of hooks drives every runtime. An adapter is thin: it tells a
 runtime *where to load the skills*, *how to arm the loop*, and *how to bind native speed*. **The
 skill names no runtime; the runtime detects the skill.**
 
+### Tier 1 — Guaranteed (gated on every commit)
+
 | Runtime | Skill load | Loop drive | Native bind |
 |---|---|---|---|
 | **Claude Code** | `.claude/skills/` + plugin | `Stop` hook | MCP |
 | **Codex** | `AGENTS.md` | self-paced | MCP / adapter |
-| **VS Code (Copilot)** | `copilot-instructions.md` | tasks | MCP |
 | **Cursor** | `.cursor-plugin/` | `stop`+`afterAgentResponse` | MCP / rules |
+
+### Tier 2 — Best-effort (contributions welcome, no gate)
+
+| Runtime | Skill load | Loop drive | Native bind |
+|---|---|---|---|
+| **VS Code (Copilot)** | `copilot-instructions.md` | tasks | MCP |
 | **Antigravity** | rules / `AGENTS.md` | self-paced | MCP |
 | **Kiro** | `.kiro/steering/` | specs | MCP |
 | **OpenCode** | `AGENTS.md` | self-paced | MCP |
@@ -185,9 +198,9 @@ skill names no runtime; the runtime detects the skill.**
 | **Hermes** | native recall | native loop | **native** |
 | **OpenClaw** | plugin SDK | native scheduler | **native** |
 
-The promise: **same protocol, same gates, same safety on all 11 — only the speed differs.**
-`orient_clamp.py` (token economy) works on every runtime with zero wiring. See
-[`adapters/MATRIX.md`](adapters/MATRIX.md).
+The promise: **same protocol, same gates, same safety on all 11 — Tier 1 verified mechanically,
+Tier 2 best-effort.** `orient_clamp.py` (token economy) works on every runtime with zero wiring. See
+[`adapters/MATRIX.md`](adapters/MATRIX.md) for the promotion/demotion rules.
 
 ---
 
@@ -207,9 +220,9 @@ flowchart TD
   SRC --> PF
   subgraph PF["2 · Pre-flight gates"]
     direction LR
-    P1["cost kill-switch budget · agentsview cost check"]
-    P2["source auth + scopes"]
-    P3["arm 24/7 watcher"]
+    P1["source auth + scopes"]
+    P2["runtime/tools ready"]
+    P3["arm 24/7 watcher + STOP path"]
   end
   PF --> DISC
   subgraph DISC["3 · Discover + normalize"]
@@ -266,7 +279,7 @@ flowchart TD
     F3["branch behind main -> additive rebase"]
   end
   FB -->|"merged and closed"| DONE(["done + evidence + measured savings (only if a receipt exists)"])
-  WATCH["11 · 24/7 watcher · simplicio-loop evidence-gated promise · max-iterations cap · cost kill-switch · LMCache KV cache warm"]
+  WATCH["11 · 24/7 watcher · simplicio-loop evidence-gated promise · max-iterations cap · STOP path · LMCache KV cache warm"]
   FB -. "poll new work / comments / checks" .-> WATCH
   DONE -. "idle until new work" .-> WATCH
   WATCH -. "re-feed the goal" .-> DISC
@@ -282,8 +295,7 @@ agent sees its own prior work. Exit is ONLY via:
 1. **Evidence-gated `<promise>`** — the turn that emits the promise MUST also carry concrete
    proof (passing test, merged PR, closed-item re-query). A promise with no evidence = ignored.
 2. **`max_iterations` cap** — hard safety backstop
-3. **Budget kill-switch** — `daily_usd_ceiling` halts the loop when spent
-4. **STOP signal** — `.orchestrator/STOP` or channel command
+3. **STOP signal** — `.orchestrator/STOP` or channel command
 
 Between turns, LMCache (when available) caches the KV state so re-feed costs near-zero prefill.
 
@@ -316,13 +328,28 @@ loop_journal.py record --iteration N --action "…" --gate fail --gate-output te
 loop_journal.py stall --k 3 --exit-code      # PROGRESS → re-feed · STALLED → switch/escalate
 ```
 
+### 📦 Exported contract for other runtimes — `simplicio.loop-execution/v1`
+
+`simplicio-loop` is the reference implementation of this converge/drain discipline. So that
+`simplicio-runtime` (or any other consumer) reuses this semantics instead of inventing a second,
+incompatible execution contract (#115), the discipline is published as versioned, testable fixtures
+under [`contracts/loop-execution/v1/`](contracts/loop-execution/v1/SCHEMA.md): converge success,
+stall + escalation, drain with empty rounds, the STOP path, evidence-gated completion, and the
+minimal append-only journal shape. `python3 scripts/check_loop_contract.py` (wired into
+`scripts/check.py`) validates every fixture against the REAL producers (`hooks/loop_stop.py`,
+`scripts/loop_journal.py`) by actually running them in an isolated temp directory — not a
+re-description of them — so a runtime implementing its own executor can diff its behavior against
+each fixture's `expected.json` instead of re-deriving the rules from prose. See
+[`contracts/loop-execution/v1/SCHEMA.md`](contracts/loop-execution/v1/SCHEMA.md) for the full
+contract and how to consume it.
+
 ---
 
 ## 🎬 Video evidence — Playwright by default, hyperframes on request
 
 The loop produces **demo videos** as proof a change works — **two engines**, one `video_evidence`
 extension point (worker [`scripts/video_evidence.py`](scripts/video_evidence.py), contract
-[`references/video-evidence.md`](.claude/skills/simplicio-tasks/references/video-evidence.md)):
+[`references/video-evidence.md`](.claude/skills/simplicio-loop/references/video-evidence.md)):
 
 1. **Default — the normal evidence flow uses Playwright.** After a UI change, `video_evidence`
    records the **real browser session** driving the screen (Playwright native video → `.webm`, →
@@ -341,7 +368,7 @@ extension point (worker [`scripts/video_evidence.py`](scripts/video_evidence.py)
    frames, same output", CI-reproducible, no API keys, local render via headless Chrome + FFmpeg).
 
    ```text
-   /simplicio-tasks make an explainer video of the system login screen
+   /simplicio-loop make an explainer video of the system login screen
    → detect: video-creation request → web_verify captures the screens
    → video_evidence verify --engine hyperframes → deterministic MP4 → attached to the PR
    ```
@@ -363,18 +390,20 @@ is always a **file path + boolean verdict** — never video bytes in context (to
 | `simplicio-compress` | Terse prose + one-time memory compaction |
 | `orient_clamp.py` | Clamp + tee on every shell command, zero wiring |
 | Native response cache | repeated deterministic (temp=0) request → served from cache, skips the LLM call (**100% on hit**) — `simplicio-cli cache`, on by default (`SIMPLICIO_CACHE=0` to disable) |
-| Simplicio capture proxy + MCP | 60-95% fewer tokens on tool outputs via a transparent compression daemon |
+| **Simplicio capture proxy + MCP** | 60-95% fewer tokens on tool outputs via a transparent compression daemon — **unverified** (no receipt snapshot exists) |
 
 Savings only count on a verified-correct outcome. Baseline = the cheapest sensible non-orchestrated
 path to the same result. **Savings reporting is evidence-gated, not mandatory:** a savings figure is
 shown only when a turn actually ran an economy-producing command and the number traces to a
 measured receipt (clamp tee, signatures-read, cache hit, `deterministic_edit`, `savings_ledger`).
 No measured economy → no savings line; the orchestrator never fabricates a baseline or a percentage.
-See `references/token-economy.md`.
+**All quantitative savings figures in this README are currently UNVERIFIED** — no receipt snapshot
+exists in `.orchestrator/savings/snapshots.jsonl`. See `references/token-economy.md` and
+`scripts/claims_manifest.py`.
 
-### 🔎 Running `simplicio-tasks`: economy vs measurement (per runtime)
+### 🔎 Running `simplicio-loop`: economy vs measurement (per runtime)
 
-Two different things happen when you call **`simplicio-tasks`**, and they behave differently per runtime:
+Two different things happen when you call **`simplicio-loop`**, and they behave differently per runtime:
 
 - **Economy** — compression, output clamps, signatures-only reads, `deterministic_edit` — applies **every
   time the skill runs and loads `simplicio-orient` / `simplicio-compress`, on any runtime.** It is the
@@ -416,6 +445,27 @@ out with `SIMPLICIO_NO_DASHBOARD=1`), and the tray never opens by itself — not
 open. Manage the stack: `scripts/simplicio-economy.sh {status|up|monitor|tray|wire}`. After install,
 capture runs **without invoking the loop** — see `references/token-capture.md`.
 
+### 🧪 e2e savings demo — one task, four hops, a receipt at every one
+
+`scripts/e2e_demo.py` is the capstone acceptance test for this program: it drives ONE task through
+**MAP → RECALL → EDIT → VERIFY** and writes a `simplicio.savings-event/v1`-shaped receipt per hop,
+never a bare percentage.
+
+```bash
+python3 scripts/e2e_demo.py run         # live: real simplicio-mapper + task_anchor.py calls
+python3 scripts/e2e_demo.py selftest    # offline: proves the receipt/report math, no external tools
+```
+
+`run` writes `.orchestrator/savings/e2e-demo.md` (the report), `e2e-demo-events.jsonl` (one receipt
+per hop), and feeds the same `snapshots.jsonl` store `savings_harness.py score` and
+`billing_aggregator.py collect`/`meter` already read — so this demo's numbers roll up into the
+existing aggregation with no new code. MAP and VERIFY call real live tools
+(`simplicio-mapper handoff`, `task_anchor.py check --format json|toon`); RECALL and EDIT
+honestly label a local stand-in where an upstream dependency (mapper's native `--for-llm toon`,
+dev-cli's `SIMPLICIO_PROMPT_TOON`) isn't shipped yet — every hop's `note` says exactly which.
+`selftest` is fully offline (no subprocess to `simplicio-mapper`/`simplicio-cli`, no network, no
+API key) and is what `scripts/check.py` runs.
+
 ### 🛠️ The capture engine — one native module, every command
 
 [`engine/simplicio_engine.py`](engine/simplicio_engine.py) is the native Simplicio capture engine
@@ -448,12 +498,27 @@ Four mechanisms sustain the orchestration power:
 | **DAG + pipeline** | parallelism by dependency, staged per item | `references/orchestration.md` (Step 3 pool + pipeline) |
 | **Isolation by worktree** | parallel edits without corrupting the tree, merge-gated | `references/orchestration.md` |
 | **Adversarial verify** | panel of skeptics before "delivered" | `references/quality-safety-delivery.md` · skill `simplicio-review` |
-| **Loop budget cap** | anti-infinite-loop, dual exit | `references/standing-loop-247.md` · skill `simplicio-loop` |
+| **Bounded loop cap** | anti-infinite-loop, evidence-gated exit | `references/standing-loop-247.md` · skill `simplicio-loop` |
 
 ---
 
 ## 🚀 Install & use
 
+**Fast path: standalone skill install.** If you only want the `simplicio-loop` skill bundle, this
+is enough — **no native runtime dependency is required**:
+
+```bash
+pip install simplicio-loop
+simplicio-loop install            # current project
+simplicio-loop install --global   # user-wide
+```
+
+That installs the skills + hooks only. If your runtime can bind native helpers, they are an
+**optional speed-up**, not a prerequisite.
+
+**Full-stack path: repo installer.** Use this when you also want the broader Simplicio local stack
+(operators, capture proxy, dashboards, services, runtime wiring):
+
 ```bash
 git clone https://github.com/wesleysimplicio/simplicio-loop
 cd simplicio-loop
@@ -464,10 +529,10 @@ pwsh scripts/install.ps1 <runtime> [-Global]                    # Windows
 # <runtime> ∈ claude codex vscode cursor antigravity kiro opencode gemini aider hermes openclaw
 ```
 
-**Install is complete by default — it installs everything.** One command sets up the whole stack:
+**The repo installer is full-stack by default — it installs everything.** One command sets up the whole stack:
 the two loop operators (`simplicio-mapper` + `simplicio-cli`, auto-handling PEP 668 / externally-managed
 Python and symlinking the binaries onto `PATH`), the **full Python stack** (the package itself),
-the **6 skills + hooks** with the loop's Stop hook wired, and the **always-on capture proxy**
+the **7 skills + hooks** with the loop's Stop hook wired, and the **always-on capture proxy**
 with Claude + Codex + Hermes **routed and measured** in the background. The **dashboard opens once** on a
 fresh install, then it's on-demand (`simplicio-loop dashboard` / `simplicio-economy.sh monitor`); the
 **menu-bar tray never opens by itself** — nothing is forced to stay open.
@@ -491,7 +556,7 @@ python3 scripts/doctor.py --repair   # install/wire what's fixable; make everyth
 # also: bash scripts/simplicio-economy.sh doctor [--repair]
 ```
 
-`doctor` separates **REQUIRED** (python3, the two loop operators, the 6 skills, the loop hooks, the
+`doctor` separates **REQUIRED** (python3, the two loop operators, the 7 skills, the loop hooks, the
 capture proxy — `--repair` installs/wires them) from **OPTIONAL** accelerators (the tray dep).
 **Missing an optional piece is never a failure and
 never blocks** — the Python engine + the deterministic path cover everything; the exit code is 0 as
@@ -508,16 +573,15 @@ bash scripts/install.sh claude    # or: bash scripts/install.sh cursor
 Then:
 
 ```
-/simplicio-tasks finish all the open issues
+/simplicio-loop finish all the open issues
 ```
 
-The only requirement is **python3** on PATH (skills, hooks, and installer are cross-platform
-Python). For GitHub sources, `git` + an authenticated `gh`. See [`INSTALL.md`](INSTALL.md) and
+For the standalone skill install, the only requirement is **python3** on PATH. For the repo
+installer and GitHub-backed sources, you also want `git` + an authenticated `gh`. See [`INSTALL.md`](INSTALL.md) and
 [`adapters/MATRIX.md`](adapters/MATRIX.md).
 
-**Before an unattended 24/7 run:** set a cost ceiling in `.orchestrator/loop-budget.json`
-(`daily_usd_ceiling > 0`), confirm source auth is persistent, and keep the irreversible-op human
-gate + secret-scan on. With `ceiling = 0` the watcher refuses to run unattended (fail-safe).
+**Before an unattended 24/7 run:** confirm source auth is persistent, keep the irreversible-op
+human gate + secret-scan on, and ensure a reachable STOP/cancel path is configured.
 
 ---
 
@@ -533,8 +597,8 @@ gate + secret-scan on. With `ceiling = 0` the watcher refuses to run unattended
 - **Trust-before-load** — perception-shaping config (clamp profiles, suppression lists) is
   untrusted until a human reviews and hash-pins it.
 - **Prompt-injection hardening** — item/PR/comment content can never override the contract.
-- **Hard $ kill-switch** for unattended runs; **evidence-gated** completion (never a false
-  "done"); **fail-open** hooks (never trap the agent in a loop).
+- **Evidence-gated** completion (never a false "done"); **fail-open** hooks (never trap the agent
+  in a loop); explicit STOP/cancel path for unattended runs.
 
 ---
 
@@ -543,9 +607,16 @@ gate + secret-scan on. With `ceiling = 0` the watcher refuses to run unattended
 Claims are verified, not just asserted — and the gate runs **locally**, with zero CI cost:
 
 ```bash
-python3 scripts/check.py            # the whole gate (audit + tests)
+python3 scripts/check.py            # the whole gate (audit + tests + loop-contract + token-budget)
+python3 scripts/check.py --core-gate # fast/mandatory core only — skips satellite-only tests (#118)
 ```
 
+`scripts/` has grown into ~39 files; [`docs/SCRIPTS_INVENTORY.md`](docs/SCRIPTS_INVENTORY.md)
+classifies every one of them **core** (required for the loop drive or this gate) vs **satellite**
+(an opt-in/advanced capability — source adapters, `simplicio-autoresearch`, the economy/dashboard
+stack, `repo_conventions`, `schema_verify`). Lead with the core; treat the rest as advanced,
+opt-in capabilities you reach for when the task calls for them.
+
 - **Test suite** (`tests/`) — the workers' deterministic `selftest`s, plus an **e2e of the loop
   driver** (`hooks/loop_stop.py`): it proves the loop **stops on evidence**, **ignores a bare
   `<promise>`**, and **stops on the cap** as distinct exits — and that the evidence producers

{simplicio_loop-3.20.1 → simplicio_loop-3.22.4}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simplicio-loop"
-version = "3.20.1"
-description = "The Universal Looping AI Orchestrator — a runtime-agnostic super-plugin (6 skills) that drains any queue of work end-to-end on any LLM/runtime."
+version = "3.22.4"
+description = "The Universal Looping AI Orchestrator — a runtime-agnostic super-plugin (7 skills) that drains any queue of work end-to-end on any LLM/runtime."
 readme = "PYPI.md"
 requires-python = ">=3.8"
 license = { text = "MIT" }
@@ -25,8 +25,8 @@ classifiers = [
 #   simplicio-mapper -> the repo-survey step (binds `orient`)
 #   simplicio-cli    -> the operator that applies+verifies changes (binds `execute`/`deterministic_edit`)
 dependencies = [
-  "simplicio-mapper>=0.13.0",
-  "simplicio-cli>=0.9.0",
+  "simplicio-mapper>=0.16.0",
+  "simplicio-cli>=0.9.3",
 ]
 
 # Optional: the real embedding backend for `simplicio-cli semantic --ml` / `simplicio-cli rag --ml`.

{simplicio_loop-3.20.1 → simplicio_loop-3.22.4}/simplicio_loop/__init__.py

@@ -13,6 +13,6 @@ try:
     try:
         __version__ = _v("simplicio-loop")
     except PackageNotFoundError:
-        __version__ = "3.15.0"
+        __version__ = "3.22.4"
 except Exception:  # pragma: no cover
-    __version__ = "3.15.0"
+    __version__ = "3.22.3"