simplicio-loop 3.36.1__tar.gz → 3.38.0__tar.gz

{simplicio_loop-3.36.1 → simplicio_loop-3.38.0}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Wesley Simplicio
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Wesley Simplicio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{simplicio_loop-3.36.1 → simplicio_loop-3.38.0}/MANIFEST.in

@@ -1,3 +1,4 @@
 include PYPI.md
 include LICENSE
 recursive-include simplicio_loop/_bundle *
+recursive-include contracts/stage-agents/v1 *.json

{simplicio_loop-3.36.1/simplicio_loop.egg-info → simplicio_loop-3.38.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplicio-loop
-Version: 3.36.1
+Version: 3.38.0
 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

{simplicio_loop-3.36.1 → simplicio_loop-3.38.0}/PYPI.md

@@ -1,53 +1,53 @@
-# simplicio-loop
-
-**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 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-2026.png)
-
-## Install
-
-```bash
-pip install simplicio-loop
-```
-
-Then drop the skills + hooks into your project (or globally):
-
-```bash
-simplicio-loop install            # into ./.claude of the current project
-simplicio-loop install --global   # into ~/.claude (all projects)
-```
-
-Now invoke it from your agent runtime (Claude Code, Cursor, Codex, Gemini, …):
-
-```
-/simplicio-loop finish all the open issues
-```
-
-## What you get — 7 skills
-
-| Skill | What it does |
-|---|---|
-| `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
-
-- **12 runtimes, one protocol** — Claude Code, Codex, VS Code/Copilot, Cursor, Antigravity, Kiro,
-  OpenCode, Gemini, Aider, Simplicio Agent (formerly Hermes), OpenClaw, Orca.
-- **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.
-
-Requires Python 3.8+. The skills, hooks, and installer are pure cross-platform Python.
-
-MIT — part of the [Simplicio](https://github.com/wesleysimplicio) ecosystem.
-Full docs: <https://github.com/wesleysimplicio/simplicio-loop>
+# simplicio-loop
+
+**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 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-2026.png)
+
+## Install
+
+```bash
+pip install simplicio-loop
+```
+
+Then drop the skills + hooks into your project (or globally):
+
+```bash
+simplicio-loop install            # into ./.claude of the current project
+simplicio-loop install --global   # into ~/.claude (all projects)
+```
+
+Now invoke it from your agent runtime (Claude Code, Cursor, Codex, Gemini, …):
+
+```
+/simplicio-loop finish all the open issues
+```
+
+## What you get — 7 skills
+
+| Skill | What it does |
+|---|---|
+| `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
+
+- **12 runtimes, one protocol** — Claude Code, Codex, VS Code/Copilot, Cursor, Antigravity, Kiro,
+  OpenCode, Gemini, Aider, Simplicio Agent (formerly Hermes), OpenClaw, Orca.
+- **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.
+
+Requires Python 3.8+. The skills, hooks, and installer are pure cross-platform Python.
+
+MIT — part of the [Simplicio](https://github.com/wesleysimplicio) ecosystem.
+Full docs: <https://github.com/wesleysimplicio/simplicio-loop>

{simplicio_loop-3.36.1 → simplicio_loop-3.38.0}/README.md

@@ -1,7 +1,7 @@
 # 🔁 simplicio-loop — The Universal Looping AI Orchestrator
 
 <p align="center">
-  <img src="assets/simplicio-loop-hero-2026.png" alt="simplicio-loop autonomous parallel evidence-gated orchestration" width="920" />
+  <img src="assets/simplicio-loop-hero-stage-agents-2026.webp" alt="simplicio-loop portable stage agents, evidence gates, durable memory, and connected work-item reporting" width="920" />
 </p>
 
 <p align="center">
@@ -9,7 +9,7 @@
   <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-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="#-12-runtimes-one-protocol"><img src="https://img.shields.io/badge/runtimes-12%20(3%20garantidos%2B9%20best--effort)-2563EB" alt="12 runtimes (3 guaranteed + 9 best-effort)"></a>
+  <a href="#-15-runtimes-one-protocol"><img src="https://img.shields.io/badge/runtimes-15%20(3%20garantidos%2B12%20best--effort)-2563EB" alt="15 runtimes (3 guaranteed + 12 best-effort)"></a>
   <a href="#-the-49-extension-points"><img src="https://img.shields.io/badge/extension%20points-49-00E08A" alt="49 extension points"></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>
@@ -20,7 +20,7 @@
   <a href="#-tldr">TL;DR</a> ·
   <a href="#-the-7-skills--5-accelerators">7 Skills</a> ·
   <a href="#-source-adapters">Source Adapters</a> ·
-  <a href="#-12-runtimes-one-protocol">12 Runtimes</a> ·
+  <a href="#-15-runtimes-one-protocol">15 Runtimes</a> ·
   <a href="#-the-loop">The Loop</a> ·
   <a href="#-token-economy">Token Economy</a> ·
   <a href="#-token-economy">Capture Engine</a> ·
@@ -86,24 +86,141 @@ That architecture lets one goal become a governed delivery system: from a single
 </p>
 <!-- visual-story:end -->
 
-## 🆕 What's new in v3.35.0
+<!-- stage-agents-roadmap:start -->
+## 🤖 Shipped: a concrete agent behind every stage
 
-- **Real multi-device execution** — atomic claim/discovery over a live remote queue, worker heartbeat + cancellation, receipt verification on *both* the client and the server, and an installable worker/supervisor/queue-server console-script surface, plus a `doctor.py` `LOCAL_ONLY` / `REMOTE_READY` / `REMOTE_MEASURED` tri-state so "remote" is never claimed without a passing cross-process proof.
-- **Real multi-LLM routing** — a deterministic model registry/router with fallback and circuit-breaker, task-contract-driven routing fields, and a genuine, verified `codex exec` run producing an auditable `runtime-execution-receipt` (Claude-side execution is implemented too, gated only by org policy in this environment — never faked).
-- **Evidence-gated delivery, wired for real** — fail-closed receipt verification (content/hash/schema/freshness), heartbeat-guarded dispatch, a merge executor that reconciles *after* merging (not just after opening the PR), chaos-tested crash recovery, and a cross-receipt commit-binding gate that closes a real "two green receipts, two different commits" gap.
-- **Security hardening** — an enumerated environment allow-list, short-lived HMAC credentials with `jti` revocation and per-operation scoping, DNS/TLS-pinned transport proven against live redirect/rebinding/proxy-injection attempts, structured audit logging, and CODEOWNERS coverage of every security-critical module.
-- **Delivery truth** — no more presumed proof: paginated live GraphQL queries, byte-level release-artifact verification (real SHA-256 + `gh attestation verify`), branch-reachability/issue-state/freshness checks, and a real concurrency + crash + fault-injection test matrix (including crashes *during* the external call itself).
-- **Quality gate, for real** — an independent watcher that re-derives every quality-matrix lane (including coverage drift) instead of trusting a self-reported receipt, all 192 test files sorted into a real unit/integration/system/regression convention, and measured coverage raised from 16.6% / 9.4% to 28.45% / 24.02% (global / critical) on the widened scope.
-- **A local, CI-less determinism story** — since GitHub Actions isn't available on this repo, a fail-closed local pre-push gate now stands in as the mandatory, impossible-to-bypass check, and the release pipeline (version bump → build → checksum → SBOM → local provenance → install-smoke) runs end-to-end against the real checkout with `scripts/release_rehearsal.py`.
-- **A transactional installer** — backup-before-mutate, real rollback, N-1→N upgrade tests, explicit consent gating before installing a service/proxy, and a machine-readable mutation manifest.
-- **Repository governance** — LFS-scoped media, a budget gate blocking accidental build-artifact commits, a canonical version/skill/claims manifest, and a dry-run-only history-migration plan (the actual rewrite stays a separate, explicit maintainer action, by design).
+> **Implementation status:** [#422](https://github.com/wesleysimplicio/simplicio-loop/issues/422)–[#436](https://github.com/wesleysimplicio/simplicio-loop/issues/436) — the whole EPIC — is **closed and shipped** as of v3.37.0, including the full mandatory stage-reporting gate ([#433](https://github.com/wesleysimplicio/simplicio-loop/issues/433)) and the multi-tracker interface ([#436](https://github.com/wesleysimplicio/simplicio-loop/issues/436)). v3.38.0 adds the multi-agent coordination layer on top (`scripts/coordinator.py`, `scripts/pr_dod_review.py`) — see [§ What's new](#-whats-new-in-v3380--the-multi-agent-coordination-release).
 
-See [`CHANGELOG.md`](CHANGELOG.md) for the full list and the [v3.35.0 release](https://github.com/wesleysimplicio/simplicio-loop/releases/tag/v3.35.0) for signed artifacts (wheel, sdist, SBOM, provenance).
+The portable driver assigns one accountable agent to intake/planning, implementation, safety,
+delivery, feedback/recovery, and final completion audit. Review fans out to four independent agents
+— security/correctness, code quality, runtime reproduction, and blast radius — before it can
+reconverge. Every transition emits an event and receipt; the completion auditor accepts evidence,
+never self-reported confidence.
+
+<p align="center">
+  <img src="assets/simplicio-loop-stage-agents-reporting-2026.webp" alt="simplicio-loop stage agents with four-way review, evidence ledger, recovery, completion audit, and work-item comments" width="920" />
+</p>
+
+### Work-item comment policy
+
+| Work tracker | Reporting policy | Completion meaning |
+|---|---|---|
+| **GitHub Issues / PRs** | **Required** for GitHub-bound runs | `COMPLETE` waits for a remotely observed comment receipt |
+| **Azure DevOps** | Only when its connector is detected, authenticated, authorized, and target-resolved | Connected providers report; `NOT_CONNECTED` is an explicit, non-blocking skip |
+| **Jira** | Only when connected | Same canonical timeline, provider-specific confirmation |
+| **Asana** | Only when connected | Same canonical timeline, provider-specific confirmation |
+| **Trello** | Only when connected | Same canonical timeline, provider-specific confirmation |
+
+```mermaid
+flowchart LR
+  SOURCE["Issue · task · queue"] --> COORD["Portable coordinator"]
+  COORD --> PLAN["Intake + Planner agent"]
+  PLAN --> BUILD["Implementation agent"]
+  BUILD --> SAFE["Safety agent"]
+  SAFE --> R1["Review agent · security"]
+  SAFE --> R2["Review agent · quality"]
+  SAFE --> R3["Review agent · runtime/E2E"]
+  SAFE --> R4["Review agent · blast radius"]
+  R1 --> DELIVER["Delivery agent"]
+  R2 --> DELIVER
+  R3 --> DELIVER
+  R4 --> DELIVER
+  DELIVER --> RECOVER["Feedback + Recovery agent"]
+  RECOVER --> BUILD
+  DELIVER --> AUDIT["Completion auditor"]
+  AUDIT --> VERDICT{"COMPLETE · PARTIAL · BLOCKED · REGRESSED"}
+  PLAN -. "events + receipts" .-> LEDGER["Append-only stage ledger"]
+  BUILD -.-> LEDGER
+  SAFE -.-> LEDGER
+  DELIVER -.-> LEDGER
+  AUDIT -.-> LEDGER
+  LEDGER --> GH["GitHub comments · REQUIRED"]
+  LEDGER -. "only if connected" .-> AZ["Azure DevOps comments"]
+  LEDGER -. "only if connected" .-> JIRA["Jira comments"]
+  LEDGER -. "only if connected" .-> ASANA["Asana comments"]
+  LEDGER -. "only if connected" .-> TRELLO["Trello comments"]
+  GH --> AUDIT
+```
+
+The provider-neutral contract, capability probes, idempotent markers, durable outboxes, recovery
+rules, sandbox E2E matrix, and acceptance criteria are specified in
+[#436](https://github.com/wesleysimplicio/simplicio-loop/issues/436). An optional provider is never
+treated as connected merely because a CLI exists, and no remote acknowledgment is ever invented.
+<!-- stage-agents-roadmap:end -->
+
+## 🆕 What's new in v3.38.0 — the multi-agent coordination release
+
+This release is about one hard problem that only shows up once **several agent sessions work the
+same repo at once**: how does a session know what's already claimed, what's already merged-but-
+incomplete, and what to do with its own idle time instead of duplicating a sibling's work? Every
+item below was built, tested, and shipped against the **live, multi-session state of this very
+repo** — not a synthetic scenario.
+
+- **`scripts/coordinator.py` — the decision core.** Given today's GitHub state (open-issue claim
+  comments + merged PRs), it returns one deterministic action per issue: `OWN` (nothing claimed
+  yet), `CONTINUE_OWN` (you're already the latest claimant), `DEFER_ACTIVE_CLAIM` (a sibling
+  session claimed it recently — don't duplicate), `RECLAIM_STALE` (that claim went cold, safe to
+  pick up), or `VERIFY_PARTIAL` (a PR already merged for this issue, but it's still open — check
+  what's actually done before assuming either "nothing happened" or "it's finished"). It also
+  raises a `duplicate_risk` flag the instant two sessions claim the same issue close together.
+  Caught, live, on day one: two sessions independently building a findings collector for the same
+  issue under two different filenames.
+- **`scripts/pr_dod_review.py` — the reviewer for idle time.** When every open issue is already
+  claimed, a session's highest-leverage move isn't to wait — it's to check the open PRs against
+  this repo's own bar: the 7-dimension Definition of Done (implementation, unit/integration/
+  system/regression tests, a performance benchmark, ≥85% coverage) and the underlying issue's
+  frozen acceptance-criteria checklist. `check --post` posts a mechanical, line-by-line verdict as
+  a PR comment instead of a vibe-based approval. Proven against a real, already-merged "MVP slice"
+  PR: it correctly flagged **17 of 17** acceptance criteria on the parent epic as still unresolved.
+- **`scripts/finding_collector.py` — durable, deduplicated defect memory (issue #466, phase 1).**
+  A `simplicio.finding/v1` record per distinct defect, fingerprinted so the *same* underlying bug —
+  seen by any agent, any run, any timestamp — collapses into one record with an occurrence count
+  instead of spawning duplicate noise. No GitHub calls yet; that's the next phase.
+  `scripts/evolution.py` (taxonomy + priority + dedup) and `scripts/workflow_topology.py` (DAG
+  diff + validator) shipped as the first MVP slices of the companion Continuous Evolution (#467)
+  and Adaptive Architecture (#468) epics; `scripts/agent_replication.py` did the same for Elastic
+  Replication (#469) — admission control and winner-selection for speculative duplicate execution.
+- **`references/multi-agent-coordination.md` + `references/background-verification.md`** — two new
+  documented conventions wired straight into `SKILL.md`'s triage step: check coordinator ownership
+  before touching an issue, review PRs instead of idling once everything's claimed, and launch
+  slow verification commands (tests/`claims_audit.py`) in the background so a turn keeps making
+  progress instead of watching a progress bar.
+- **Mandatory post-merge cleanup (`scripts/worktree_cleanup.py`, #484)** — a merged branch's local
+  worktree and branch ref are now removed automatically instead of accumulating across sessions.
+- **CLI contract additions (WI-471)** — a `preflight` subcommand and a `--json` flag on `status`,
+  so an external supervisor can machine-check readiness before arming a run.
+- **Continuous Findings wiring (WI-466)** — the completion gate now genuinely consults the finding
+  store, and a store/repo consistency bug was found and fixed in the same pass.
+- **Two real regressions caught and fixed on `main` itself, live, this release cycle** — a PR that
+  silently deleted a function definition (breaking `loop_progress.py`'s own selftest) merged once,
+  and a squash-merge race then reintroduced the exact same broken code onto `main` a second time.
+  Both were found by actually running the affected script, not by trusting a green PR description —
+  the whole reason `coordinator.py` and `pr_dod_review.py` exist now.
+- **Carried forward from v3.37.0's Portable Stage Agents epic (#422–#436)** — a concrete,
+  independently verifiable agent behind every stage (intake/planner, implementation, four-way
+  review panel, safety gate, delivery, feedback/recovery, completion auditor), a conformance suite
+  proving contract/receipt parity across all 15 runtimes, human-readable agent identities, and
+  `simplicio-runtime` promoted to a required bound operator exactly like `simplicio-mapper`/
+  `simplicio-dev-cli`.
+- **Test suite grew to 231 files** (from 192), all still sorted into the unit/integration/system/
+  regression convention `docs/SCRIPTS_INVENTORY.md` tracks; `scripts/claims_audit.py` stayed at
+  14/14 through every merge this cycle.
+
+**What this means for you, concretely:** if you run `simplicio-loop` across more than one session
+or machine against the same repo, it now actively protects you from the two failure modes that
+actually happen in practice — two agents quietly redoing the same work, and a "done" PR that
+merged but left the real issue only partially solved. Neither used to be visible; both now are,
+mechanically, every triage pass.
+
+See [`CHANGELOG.md`](CHANGELOG.md) for the full list and the
+[v3.38.0 release](https://github.com/wesleysimplicio/simplicio-loop/releases/tag/v3.38.0) for
+signed artifacts (wheel, sdist, SBOM, provenance).
 
 ## ⚡ TL;DR
 
 **simplicio-loop** is a runtime-agnostic **super-plugin** — one autonomous looping
-orchestrator (invoked as **`/simplicio-loop`**) plus **five satellite skills** — that turns any
+orchestrator (invoked as **`/simplicio-loop`**) plus **six satellite skills and five
+accelerators** — 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:
@@ -126,14 +243,14 @@ and keeps watching **24/7** for new work — all behind safety gates and evidenc
 ```
 
 Three things make it different: it is a **super-plugin of focused skills**, it runs the **same
-protocol on 12 runtimes**, and it does all of this with **aggressive, honest token economy**.
+protocol on 15 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, 12 runtimes, 5 source adapters, and proof gates" width="920" />
+  <img src="assets/simplicio-loop-infographic.png" alt="simplicio-loop detailed infographic: standalone install, required native binds, 7 skills, 5 accelerators, 15 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
@@ -169,8 +286,8 @@ If you are an agent/runtime entering this repo cold, read `llms.txt` first for t
 ## 📘 Official capability record
 
 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.
+runnable, and tested** (`python3 scripts/check.py`: claims-audit 14/14 + 2,544 tests collected
+across 231 files). Each links to its deep section and its worker.
 
 | Capability | What it does | Proof / worker | Details |
 |---|---|---|---|
@@ -182,6 +299,10 @@ deep section and its worker.
 | 🔒 **Fail-closed safety gate** (`action_gate`) | A `PreToolUse`/git-pre-push hook that **mechanically blocks** force-push, history rewrite, mass-delete, destructive DDL, infra teardown, and secret-laden commits/pushes — Step 5 made executable, not prose | `hooks/action_gate.py` · `selftest` 15/15 | [§ Safety](#-safety-non-negotiable) |
 | 🔬 **Local verification** | A test suite (worker selftests + an **e2e of the loop driver** proving evidence-gated exit) + a **claims-audit** (referenced scripts exist · counts consistent · `_bundle ≡ source`) — all local, **no paid CI** | `scripts/check.py` · `scripts/claims_audit.py` · `tests/` | [§ Tests & local checks](#-tests--local-checks-no-paid-ci) |
 | ✅ **Honest savings** | The savings line is now **evidence-gated, not mandatory** — a number is shown only with a measured receipt (clamp/signatures/cache/`deterministic_edit`/ledger); never fabricated | token-economy contract | [§ Token economy](#-token-economy) |
+| 🤝 **Multi-agent coordinator** (`coordinator.py`) | Decides `OWN` / `CONTINUE_OWN` / `DEFER_ACTIVE_CLAIM` / `RECLAIM_STALE` / `VERIFY_PARTIAL` per issue from live claim comments + merged PRs, so two sessions never duplicate the same work | `scripts/coordinator.py` · `selftest` 10/10 | [§ The full flow](#️-the-full-flow--from-demand-to-delivery) |
+| 🕵️ **PR DoD/AC reviewer** (`pr_dod_review`) | When every issue is claimed, reviews open PRs against the 7-dimension Definition of Done + the issue's own acceptance-criteria checklist — a mechanical verdict, not a vibe-based approval | `scripts/pr_dod_review.py` · `selftest` 13/13 | [§ The full flow](#️-the-full-flow--from-demand-to-delivery) |
+| 🐞 **Finding collector** (`finding_collector`) | Fingerprinted, deduplicated defect memory — the same underlying bug collapses into one record with an occurrence count, no matter how many agents/runs observe it | `scripts/finding_collector.py` · `selftest` 9/9 | [§ Official capability record](#-official-capability-record) |
+| 🔔 **Release check** (`release_check`) | Compares the local canonical version against the latest GitHub release and tells the driving LLM to update instead of quietly working on a stale checkout — fail-open when offline | `scripts/release_check.py` · `selftest` 8/8 | [§ Install & use](#-install--use) |
 
 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
@@ -230,9 +351,12 @@ The orchestrator discovers work from any source via pluggable adapters. Each exp
 
 | Source | Adapter | Purpose |
 |---|---|---|
-| GitHub Issues/PRs | `gh` CLI (native) | Primary work-item source |
-| Jira / Asana / ClickUp / Linear / Notion | host connector | Board/project management |
-| Trello / Azure DevOps | `az boards` adapter | Azure work tracking |
+| GitHub Issues/PRs | `gh` CLI (native) | Primary work-item source; canonical lifecycle comments ship today |
+| Azure DevOps | `az boards` / host connector | Azure Boards discovery; stage comments only after a real connected-capability probe |
+| Jira | host connector | Jira discovery; stage comments only when connected |
+| Asana | host connector | Asana discovery; stage comments only when connected |
+| Trello | host connector | Trello discovery; stage comments only when connected |
+| ClickUp / Linear / Notion | host connector | Board/project discovery; no stage-comment claim without a certified adapter |
 | **agentsview sessions** | `scripts/agentsview_adapter.py` | Stalled session recovery + cost observability |
 | Local files / CI queue | filesystem / CI API | Internal work tracking |
 
@@ -240,33 +364,38 @@ See each adapter's reference doc under `.claude/skills/simplicio-loop/references
 
 ---
 
-## 🌐 12 runtimes, one protocol — 3 guaranteed + 9 best-effort
+## 🌐 15 runtimes, one protocol — 3 guaranteed + 12 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.**
+skill names no runtime; the runtime detects the skill.** The native `simplicio-runtime` MCP bind
+is **REQUIRED** on every runtime (loop BLOCKS if it's missing/unreachable) — see
+[`docs/MCP_SETUP.md`](docs/MCP_SETUP.md) for the per-host config table.
 
 ### Tier 1 — Guaranteed (gated on every commit)
 
-| Runtime | Skill load | Loop drive | Native bind |
+| Runtime | Skill load | Loop drive | Native bind (MCP) |
 |---|---|---|---|
-| **Claude Code** | `.claude/skills/` + plugin | `Stop` hook | MCP |
-| **Codex** | `AGENTS.md` | self-paced | MCP / adapter |
-| **Cursor** | `.cursor-plugin/` | `stop`+`afterAgentResponse` | MCP / rules |
+| **Claude Code** | `.claude/skills/` + plugin | `Stop` hook | REQUIRED — `~/.claude.json` |
+| **Codex** | `AGENTS.md` | self-paced | REQUIRED — `~/.codex/config.toml` |
+| **Cursor** | `.cursor-plugin/` | `stop`+`afterAgentResponse` | REQUIRED — `.cursor/mcp.json` |
 
 ### Tier 2 — Best-effort (contributions welcome, no gate)
 
-| Runtime | Skill load | Loop drive | Native bind |
+| Runtime | Skill load | Loop drive | Native bind (MCP) |
 |---|---|---|---|
-| **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 |
-| **Gemini** | `GEMINI.md` | self-paced | MCP / adapter |
-| **Aider** | `CONVENTIONS.md` | self-paced | — (LLM fallback) |
-| **Simplicio Agent** *(formerly Hermes)* | native recall | native loop | **native** |
-| **OpenClaw** | plugin SDK | native scheduler | **native** |
-| **Orca** | via inner agent + skills registry | inner hook / scheduled automations | MCP |
+| **VS Code (Copilot)** | `copilot-instructions.md` | tasks | REQUIRED — `.vscode/mcp.json` |
+| **Antigravity** | rules / `AGENTS.md` | self-paced | REQUIRED — best-effort path |
+| **Kiro** | `.kiro/steering/` | specs | REQUIRED — `.kiro/settings/mcp.json` |
+| **OpenCode** | `AGENTS.md` | self-paced | REQUIRED — `opencode.json` |
+| **Gemini** (CLI/Code Assist) | `GEMINI.md` | self-paced | REQUIRED — `.gemini/settings.json` (CLI) |
+| **Kimi** | inlined conventions | self-paced | REQUIRED — best-effort, no verified client |
+| **Qwen** (Code/CLI) | `AGENTS.md`-equivalent | self-paced | REQUIRED — `.qwen/settings.json` (best-effort) |
+| **DeepSeek** | inlined conventions | self-paced | REQUIRED — no first-party client, best-effort |
+| **Aider** | `CONVENTIONS.md` | self-paced | REQUIRED — no MCP client (LLM fallback for exec) |
+| **Simplicio Agent** *(formerly Hermes)* | native recall | native loop | REQUIRED — **native** |
+| **OpenClaw** | plugin SDK | native scheduler | REQUIRED — **native** |
+| **Orca** | via inner agent + skills registry | inner hook / scheduled automations | REQUIRED — registry/inner-agent config |
 
 The promise: **same protocol, same gates, same safety on all 12 — Tier 1 verified mechanically,
 Tier 2 best-effort.** `orient_clamp.py` (token economy) works on every runtime with zero wiring. See
@@ -283,27 +412,39 @@ to delivering merged, evidenced work, then looping 24/7 for more.
 flowchart LR
   IN["Intent: issue · task · queue"] --> CONTRACT["1 · Freeze task contract"]
   CONTRACT --> MAP["2 · Map source + normalize"]
-  MAP --> PLAN["3 · Dependency DAG + acceptance criteria"]
-  PLAN --> ROUTE{"4 · Ready task?"}
+  MAP --> COORD{"3 · Coordinator decide (multi-session)"}
+  COORD -->|"OWN / CONTINUE_OWN / RECLAIM_STALE"| PLAN["4 · Dependency DAG + acceptance criteria"]
+  COORD -->|"DEFER_ACTIVE_CLAIM (all issues)"| REVIEW["PR DoD/AC review — never idle"]
+  COORD -->|"VERIFY_PARTIAL"| RECHECK["Verify what's actually merged before continuing"]
+  RECHECK --> PLAN
+  REVIEW --> IN
+  PLAN --> ROUTE{"5 · Ready task?"}
   ROUTE -->|"solo / small"| SOLO["Targeted lane"]
   ROUTE -->|"parallel / medium+"| FAN["Bounded fan-out"]
   FAN --> A["Isolated worktree A"]
   FAN --> B["Isolated worktree B"]
   FAN --> C["Isolated worktree C"]
-  SOLO --> VERIFY["5 · Test + impact/flow evidence"]
+  SOLO --> VERIFY["6 · Test + impact/flow evidence"]
   A --> VERIFY
   B --> VERIFY
   C --> VERIFY
   VERIFY --> RECEIPT["Watcher challenge + evidence receipt"]
-  RECEIPT --> ORACLE{"6 · Completion oracle"}
+  RECEIPT --> ORACLE{"7 · Completion oracle"}
   ORACLE -->|"pending / blocked"| RECOVER["Journal · checkpoint · rollback · backlog-only maintenance"]
   RECOVER --> PLAN
-  ORACLE -->|"verified / measured"| DELIVER["7 · Source sync · PR · merge"]
-  DELIVER --> MEMORY["8 · Ledger · wiki · durable attempt memory"]
-  MEMORY --> WATCH["9 · Re-feed · watcher · STOP path"]
+  ORACLE -->|"verified / measured"| DELIVER["8 · Source sync · PR · merge"]
+  DELIVER --> CLEANUP["Post-merge worktree/branch cleanup"]
+  CLEANUP --> MEMORY["9 · Ledger · wiki · durable attempt memory"]
+  MEMORY --> WATCH["10 · Re-feed · watcher · STOP path"]
   WATCH -->|"new work"| IN
 ```
 
+**Multi-agent coordination (new in v3.38.0).** Step 3 is the mechanical answer to "is a sibling
+session already on this?" — `scripts/coordinator.py` decides from live GitHub state, never a guess.
+When every candidate issue comes back deferred, the loop doesn't idle: it reviews open PRs against
+the DoD + acceptance criteria (`scripts/pr_dod_review.py`) instead. Full detail:
+[`references/multi-agent-coordination.md`](.claude/skills/simplicio-loop/references/multi-agent-coordination.md).
+
 **Planning gate (issue #284).** Steps 1–3 above are not just guidance — `simplicio_loop/planning_gate.py`
 makes them a fail-closed mechanical barrier between "claimed" and "mutating": every real
 `arm_run()` self-builds a `planning-receipt.json` binding run/attempt/contract/plan/lease/fence
@@ -572,9 +713,18 @@ Pass **`--minimal`** only for headless/CI to skip the heavy deps + the machine s
 ### Update
 
 ```bash
-bash scripts/update.sh [<runtime>]    # git pull → reinstall skills/hooks/operators → restart services
+python3 scripts/release_check.py check   # is a newer release published? — never auto-updates
+bash scripts/update.sh [<runtime>]       # git pull → reinstall skills/hooks/operators → restart services
 ```
 
+`release_check.py` compares the local canonical version (`pyproject.toml`) against the latest
+GitHub release tag and prints an explicit `MEASURED|release-check: a newer release is available …`
+line (exit 10) when you're behind — the agent/LLM driving `simplicio-loop` is meant to read that
+line and run the update itself, not silently keep working on a stale checkout. It never applies the
+update — a detected-but-declined update is never auto-installed — and it fails open (`UNVERIFIED|`,
+exit 0) when `gh`/network is unavailable, so an offline dev environment never looks broken. `doctor`
+(below) runs the same check as one OPTIONAL line in its report.
+
 `update.sh` stashes local edits, fast-forwards `main`, reinstalls from the fresh source, restarts the
 launchd/systemd services so they run the new code, and prints the live stack + savings.
 
@@ -675,12 +825,18 @@ opt-in capabilities you reach for when the task calls for them.
 
 ---
 
+## ⭐ Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=wesleysimplicio/simplicio-loop&type=Date)](https://star-history.com/#wesleysimplicio/simplicio-loop&Date)
+
+---
+
 ## 📄 License
 
 MIT
 
 <!-- simplicio-loop:github-comment-coordination:v1 -->
-## 🌐 GitHub comment coordination across runtimes
+## 🌐 Work-item comment coordination across runtimes
 
 `simplicio-loop` can run at the same time in Claude Code, Codex, Cursor, Gemini, and Hermes. When a run is bound to a GitHub issue, it publishes idempotent lifecycle updates to that issue's canonical comment: claim, plan, progress, evidence, PR, and close. Agents on different machines can coordinate through the same GitHub thread without a shared local filesystem.
 
@@ -692,7 +848,7 @@ pwsh scripts/install.ps1 gemini -Global
 pwsh scripts/install.ps1 hermes -Global   # legacy alias for simplicio_agent
 ```
 
-Local queues, leases, worktrees, heartbeats, and evidence remain active on every machine; GitHub comments are the shared coordination projection. This flow is GitHub-only: Jira, Azure DevOps, and other trackers do not receive these comments. If GitHub is unavailable or unauthenticated, the loop remains usable locally and records the sync failure without inventing a remote acknowledgment. Give every runtime GitHub access and bind runs to the same `source_issue`.
+Local queues, leases, worktrees, heartbeats, and evidence remain active on every machine; GitHub comments are the shipped shared coordination projection. Today, an unavailable or unauthenticated GitHub records a sync failure without inventing a remote acknowledgment. The stage-agent roadmap tightens this for GitHub-bound runs: [#433](https://github.com/wesleysimplicio/simplicio-loop/issues/433) makes the comment confirmation mandatory before `COMPLETE`. [#436](https://github.com/wesleysimplicio/simplicio-loop/issues/436) adds the same projection to Azure DevOps, Jira, Asana, and Trello only when each connector is proven connected; disconnected optional trackers are explicitly skipped.
 
 The repository workflow `.github/workflows/simplicio-status-sync.yml` turns the canonical lifecycle
 state into a managed `simplicio:status:<state>` label and, when configured, moves the issue in a

simplicio_loop-3.38.0/contracts/stage-agents/v1/action-intent.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "simplicio.action-intent/v1",
+  "title": "Stage Agent Action Intent",
+  "description": "Typed intent emitted before any mutation-boundary action. Classifies the action surface so the safety gate can apply the right policy. Fail-closed: unknown action classes are rejected by the reducer.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "intent_id", "action_class", "command", "actor", "scope"],
+  "properties": {
+    "schema": { "const": "simplicio.action-intent/v1" },
+    "intent_id": { "type": "string", "minLength": 1 },
+    "action_class": {
+      "type": "string",
+      "enum": [
+        "write_edit",
+        "compound_shell",
+        "dependency_install",
+        "commit",
+        "push",
+        "pull_request",
+        "issue_board_op",
+        "migration_data",
+        "deploy_release",
+        "cancel_cleanup",
+        "secret_network_access",
+        "artifact_fetch_execute"
+      ]
+    },
+    "command": { "type": "string", "minLength": 1 },
+    "actor": { "type": "string", "minLength": 1 },
+    "scope": { "type": "string", "minLength": 1 },
+    "idempotency_key": { "type": "string" },
+    "policy_hash": { "type": "string" },
+    "segments": { "type": "array", "items": { "type": "string" } },
+    "created_at": { "type": "string", "format": "date-time" }
+  }
+}