🔁 simplicio-loop — The Universal Looping AI Orchestrator

TL;DR · 7 Skills · Source Adapters · 15 Runtimes · The Loop · Token Economy · Bench #17 · Capture Engine · Install

🌍 Languages:
🇬🇧 English | 🇧🇷 Português | 🇪🇸 Español | 🇫🇷 Français | 🇩🇪 Deutsch | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇨🇳 简体中文 | 🇷🇺 Русский | 🇵🇱 Polski | 🇹🇷 Türkçe | 🇳🇱 Nederlands | 🇮🇳 हिन्दी | 🇸🇦 العربية

---

🚀 The new generation — an operating system for verified agent work

simplicio-loop has evolved far beyond a repeat-until-done prompt. It now compiles intent into a frozen task contract, maps the repository, schedules dependency-aware work, fans execution out into isolated worktrees, collects structured receipts, verifies independently, rolls back safely, remembers every attempt, and keeps the source of record synchronized through delivery.

• Contract first — acceptance criteria, dependencies, risks, source state, and the completion oracle are explicit before execution.
• Parallel without corruption — ready tasks run in isolated lanes/worktrees and converge through an operational ledger.
• Automatic fan-out by default — batch provisions one owned worktree per independent, authorized task; overlap, missing evidence, or unavailable isolation falls back to a visible serial lane. See docs/AUTO_FAN_OUT.md.
• Proof before completion — tests, impact/flow checks, watcher challenges, delivery receipts, and HBP evidence reject false done states.
• Memory that changes behavior — the journal, stall detector, checkpoints, and cross-agent wiki prevent oscillation and make handoffs durable.

Dependency-aware fan-out: isolated workers execute concurrently, return evidence, and converge into one verified delivery.

Every stage is explicit, bounded, observable, and reversible.

Evidence and memory are part of the execution path—not a report written after the fact.

That architecture lets one goal become a governed delivery system: from a single hard task to an entire backlog, across sessions and runtimes, with local-first operators and receipts strong enough for humans, CI, or another agent to audit.

🤖 Shipped: a concrete agent behind every stage

Implementation status:#422–#436 — the whole EPIC — is closed and shipped as of v3.37.0, including the full mandatory stage-reporting gate (#433) and the multi-tracker interface (#436). v3.38.0 adds the multi-agent coordination layer on top (scripts/coordinator.py, scripts/pr_dod_review.py) — see § What's new.

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.

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

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

Loading

The provider-neutral contract, capability probes, idempotent markers, durable outboxes, recovery rules, sandbox E2E matrix, and acceptance criteria are specified in #436. An optional provider is never treated as connected merely because a CLI exists, and no remote acknowledgment is ever invented.

🆕 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 portable contract validator for the shared graph/receipt schema, human-readable agent identities, and optional native binds for simplicio-runtime, simplicio-mapper, and simplicio-dev-cli. Runtime rows are capability inventory; a runtime is counted as executed only by the separate installed lane when its binary and executable adapter are actually available.
• Test-suite inventory is measured, not hard-coded. The checkout and the latest local gate receipt are the source of truth for file and result counts. scripts/test_categories.py reports the unit/integration/system/regression convention where it applies, including any uncategorized files; 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 for the full list and the v3.38.0 release 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 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:

discover → understand → decide → act → verify → correct → record → repeat

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 evidence checks.

/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
→ merge · close with evidence · rollback if main breaks
→ keep looping every ~2 min until the queue is dry (evidence-gated, never a false "done")

Three things make it different: it is a super-plugin of focused skills, it runs the same 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.

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.

👁️ Progresso visual, honesto e portátil

Cada execução pode ser acompanhada por texto, Markdown, JSON ou uma animação ANSI. Todas as superfícies consomem o mesmo evento simplicio.progress/v1, incluindo ícones de etapa, gates de evidence/watcher/oracle, lanes de worktrees e eventos de worker_claimed até delivery_reconciled.

simplicio-loop progress <run-id>--format text --once
simplicio-loop progress <run-id>--format markdown --once # LLM/chat
simplicio-loop progress <run-id>--format json --once # dashboard/adapters
simplicio-loop progress <run-id>--format text --ascii --no-animation # log/PowerShell

100% só aparece com receipt do oracle pronto (COMPLETE/DRAINED); uma fase done sem prova fica quase concluída e mostra o blocker. Consulte o contrato completo em docs/PROGRESS_PROTOCOL.md.

---

🤖 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-loop/SKILL.md.

---

📘 Official capability record

The complete, official roster of what simplicio-loop ships — every capability below is real, runnable, and tested by the applicable local gate. Exact collected/executed/skipped/deselected counts belong to that gate receipt, not this document. Each capability 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 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
🧠 Attempt memory + stall detector	A durable run-journal (.simplicio/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
🧭 Repo conventions (repo_conventions)	Learns the repo's own playbook — mines git history + merged PRs + static config into .simplicio/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
🧩 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
🕸️ Flow coverage (endpoint_compare)	Maps mixed front/back/service workspaces: UI actions → frontend HTTP calls → backend endpoints → service calls; blocks frontend calls with no backend endpoint and stubbed endpoints, and surfaces unclassified loose ends	scripts/flow_audit.py · selftest	§ Tests & local checks
🔒 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
🔬 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
✅ 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
🤝 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
🕵️ 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
🐞 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
🔔 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

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, 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 semantics). The verification infra now catches the project's own regressions as it grows.

---

🧠 The 7 skills + 5 accelerators

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-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 + caveman	Terminal-first execution, output-reduction catalog, tee-cache, signatures-read	L0 deterministic
4	🔥 simplicio-review	thermos	Parallel adversarial review on distinct rubrics → deduped verdict	Quality gate
5	🗜️ simplicio-compress	caveman	Output + memory compression, fail-closed transform_guard	40-60% fewer
6	🎓 simplicio-learn	teaching	Post-run retrospective → durable, deduped lessons in memory	Smarter each run
7	🧪 simplicio-autoresearch	Karpathy autoresearch + 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	Knowledge graph orient: semantic search, guided tours, dependency graph	L0 zero tokens
9	📊 agentsview	kenn-io	Session analytics, cost tracking, stalled-session discovery	L1 SQL only
10	⚡ 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 (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/; each accelerator has a reference doc under .claude/skills/simplicio-loop/references/ (the video producer: video-evidence.md, worker scripts/video_evidence.py).

---

📡 Source adapters

The orchestrator discovers work from any source via pluggable adapters. Each exposes six verbs: list_ready, get_details, claim, update_status, attach_evidence, close.

Source	Adapter	Purpose
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

See each adapter's reference doc under .claude/skills/simplicio-loop/references/.

---

🌐 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. The native simplicio-runtime MCP bind is optional: when it is missing or unreachable, the adapter reports explicit degraded mode rather than blocking the standalone loop — see docs/MCP_SETUP.md for per-host configuration.

Tier 1 — Guaranteed (gated on every commit)

Runtime	Skill load	Loop drive	Native bind (MCP)
Claude Code	.claude/skills/ + plugin	Stop hook	optional — ~/.claude.json
Codex	AGENTS.md	self-paced	optional — ~/.codex/config.toml
Cursor	.cursor-plugin/	stop+afterAgentResponse	optional — .cursor/mcp.json

Tier 2 — Best-effort (contributions welcome, no gate)

Runtime	Skill load	Loop drive	Native bind (MCP)
VS Code (Copilot)	copilot-instructions.md	tasks	optional — .vscode/mcp.json
Antigravity	rules / AGENTS.md	self-paced	optional — best-effort path
Kiro	.kiro/steering/	specs	optional — .kiro/settings/mcp.json
OpenCode	AGENTS.md	self-paced	optional — opencode.json
Gemini (CLI/Code Assist)	GEMINI.md	self-paced	optional — .gemini/settings.json (CLI)
Kimi	inlined conventions	self-paced	optional — best-effort, no verified client
Qwen (Code/CLI)	AGENTS.md-equivalent	self-paced	optional — .qwen/settings.json (best-effort)
DeepSeek	inlined conventions	self-paced	optional — no first-party client, best-effort
Aider	CONVENTIONS.md	self-paced	optional — no MCP client (LLM fallback for exec)
Simplicio Agent(formerly Hermes)	native recall	native loop	optional — native
OpenClaw	plugin SDK	native scheduler	optional — native
Orca	via inner agent + skills registry	inner hook / scheduled automations	optional — registry/inner-agent config

The promise: same protocol, same gates, same safety on all 15 — Tier 1 verified mechanically, Tier 2 best-effort.orient_clamp.py (token economy) works on every runtime with zero wiring. See adapters/MATRIX.md for the promotion/demotion rules.

---

🗺️ The full flow — from demand to delivery

Every layer the orchestrator acts on, in order — from reading the demand (issues, tasks, assigns) 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 --> 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["6 · Test + impact/flow evidence"]
A --> VERIFY
B --> VERIFY
C --> VERIFY
VERIFY --> RECEIPT["Watcher challenge + evidence receipt"]
RECEIPT --> ORACLE{"7 · Completion oracle"}
ORACLE -->|"pending / blocked"| RECOVER["Journal · checkpoint · rollback · backlog-only maintenance"]
RECOVER --> PLAN
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

Loading

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.

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 (and, on a GitHub source, the source-snapshot hash) into a single-use mutation_authority token, and execute_operator()/execute_operator_batch() refuse to run without a matching one. Both halves of the gate (SIMPLICIO_REQUIRE_MUTATION_AUTHORITY, SIMPLICIO_LOOP_AUTO_PLANNING_RECEIPT) are mandatory by default — see .claude/skills/simplicio-loop/references/planning-gate.md and docs/adr/0004-planning-gate-rollout.md.

---

🔁 The loop

The Evidence-Gated Loop is the core mechanism. It re-feeds the same goal each turn so the 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. STOP signal — .simplicio/orchestrator/STOP or channel command

Between turns, LMCache (when available) caches the KV state so re-feed costs near-zero prefill.

🧠 Attempt memory + stall detector (anti-oscillation)

A re-feed loop that remembers nothing oscillates — try X, fail, try X again — until the cap burns. simplicio-loop keeps a durable run-journal (.simplicio/orchestrator/loop/journal.jsonl, append-only: iteration · action · hypothesis · gate · error-fingerprint, plus optional lineage like execution_state · stage_id · validator · decision · retry_count) and a stall detector (scripts/loop_journal.py, deterministic + model-free):

• Error fingerprint — the failing gate output is reduced to a stable hash with line numbers, paths, hex/uuids, timestamps and durations normalized away, so the same bug is recognized across turns even when the incidental text differs.
• Stall = K identical-fingerprint failures in a row (default K=3). A changing fingerprint means the loop is moving (PROGRESS); the same one K times means it is spinning (STALLED).
• On STALLED the loop does not re-feed the same goal — it names the dead-end actions to avoid, then switches strategy or escalates to the human gate with the fingerprint.
• loop_journal.py resume is read at the top of every turn, so a fresh process continues without re-deriving prior attempts (real resume) and never retries a known dead-end.
• When the loop is doing extraction, validation, or governed retries, record can also stamp --execution-state, --stage-id, --source-artifact, --chunk-id, --validator, --decision, --retry-count, --blocked-reason, and --next-action, so the next turn knows not just what failed, but where in the flow it failed.

loop_journal.py resume # what was tried + dead-ends to avoid
loop_journal.py record --iteration N --action "…" --gate fail --gate-output test.log \
--execution-state planned --stage-id validate --validator pytest --decision retry
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/: 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 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, contract 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, → .mp4 with FFmpeg) — the strongest "works, not just compiles" receipt (Step 4b) and a valid evidence-gated <promise>.

   python3 scripts/video_evidence.py verify --url http://localhost:3000/login \
   --name login-demo --expect "Sign in" --issue 42 [--upload --pr 42]

2. On request — a personalized explainer uses hyperframes. When the deliverable IS a video ("make an explainer video of screen X"), the orchestrator renders a deterministic, captioned slideshow of the web_verify screenshots with hyperframes (by HeyGen — "same input, same frames, same output", CI-reproducible, no API keys, local render via headless Chrome + FFmpeg).

   /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
   

Either engine: a video that never recorded/rendered yields BLOCKED, never a fake pass. Evidence is always a file path + boolean verdict — never video bytes in context (token economy).

---

📊 Token economy

Technique	Savings
deterministic_edit (L0)	100% of edit tokens (file written mechanically, never by LLM)
Terminal-first execution	Facts from shell, not LLM hallucination
Output-reduction catalog	Caps per command type (CAP_ERRORS=20, CAP_WARNINGS=10, CAP_LIST=20) — orient_clamp.py
Tee+CCR cache on failure	Never re-run a failed command — read the cached output
Signatures-only reads	simplicio-cli signatures <file> — 870-line file → 65 lines (93% saved), bodies stripped
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 — 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. Most quantitative savings figures in this README remain UNVERIFIED (no receipt snapshot in .simplicio/orchestrator/savings/snapshots.jsonl) — except the measured comparative bench below. See references/token-economy.md and scripts/claims_manifest.py.

Measured benchmark (issue #17)

Task:simplicio-agent#17 — Asolaria HRM + N-Nest-Prime, P0 slice completed in both arms: Brown-Hilbert port.port.port addressing + Agent/Watcher corrective gate (agent/asolaria_nest_contract.py + unit tests, both arms green).

Arms (same machine, Windows):

Arm	How work was done
Without loop	Ad-hoc gh + rg + full-file reads of candidate modules (LLM-style survey)
With loop	STRICT env → preflight --strict → simplicio-mapper scan/inspect/handoff → simplicio-fast doctor → arm_drain_prism → signatures-only reads

Stack measured:simplicio-loop 3.38.9 · mapper 0.26.0 · cli 0.18.0 · fast 2.0.17.

Metric	Without loop	With loop	Ratio (with/without)
Wall time	2.72 s	13.20 s	4.86× slower (operator startup)
Est. tokens(context_bytes ÷ 4)	~156 576	~15 246	0.097×
Token savings	—	~90.3% fewer est. tokens	—
Context bytes	626 303	60 982	0.097×
Shell/tool commands	16	12	—
Operator calls	0	6	preflight + mapper×3 + fast + arm
Tests success	true	true	same deliverable

Phase times (seconds):

Phase	Without	With
preflight	—	2.78
survey	1.50	7.31
plan / arm	~0	1.99
implement	~0	~0
test	1.21	1.13

How to read this: the loop cuts intake context/tokens hard (good for multi-turn LLM cost). Wall-clock can be higher on a cold operator run (preflight + mapper). Over a long session the token reduction usually dominates billed cost; wall-clock amortizes when the map/snapshot is warm.

Caveats (honest):

• “Tokens” here are estimated as context_bytes / 4, not provider-billed usage.
• Implementation code was the same P0 contract in both arms so the comparison isolates survey/orchestration, not two different implementations of the full epic.
• Not a substitute for the Token Monitor (proxy-routed measurement).

Artifacts: PDF report docs/evidence/issue17_loop_vs_baseline.pdf · raw metrics in the bench scratch (re-run with the harness under docs/evidence/ notes).

Loop-stack economy report (5 issues × 5 lanes + interpretation)

Full interpretation of why multi-lane benches look the way they do — including Fast as part of STRICT loop, why loop_no_fast can “save more tokens” while doing less work, why MCP is a bus not a compressor, and why savings % depends on baseline size.

PDF (pizza + bars + barramento + narrative)	docs/evidence/loop_stack_economy_benchmark_report.pdf
Raw metrics JSON	docs/evidence/multi_issue_lanes_metrics.json
Harness charts	docs/evidence/multi_issue_lanes_bench.pdf (agent harness)

Mean token savings vs host baseline (issues #9, #96, #171, #322, #711):

Lane	Mean	Median	Min → Max	Mean wall	Fast acting
loop (STRICT = mapper+fast)	~39%	~34%	−31% → ~83%	~50 s	yes (5)
loop + Agent MCP	~38%	~34%	−32% → ~83%	~53 s	yes (5)
loop_no_fast (diagnostic)	~64%	~61%	~22% → ~90%	~18 s	no
mcp_only	~99%*	~99%	~98% → ~100%	~11 s	n/a

*mcp_only high % = almost no repo survey (tool metadata only), not better delivery.

Contract reminder: under STRICT, Fast is already inside the loop when operational — not a second stack on top of loop. Runtime/MCP remain optional for the loop core.

Regenerate the interpretation PDF:

python scripts/render_loop_stack_economy_report_pdf.py

🔎 Running simplicio-loop: economy vs measurement (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 skill's behavior plus the hooks (strongest where hooks exist: orient_clamp.py auto-clamps on Claude and Cursor; elsewhere it is instruction-driven).
• Measurement — the Token Monitor's live numbers — only counts traffic that flows through the capture proxy.

Runtime	Economy (skill)	Measurement (monitor)
Simplicio Agent	✓	✓ automatic — already routed through the proxy (base_url → :8788)
Claude	✓ (skill + hooks)	✗ by default — Claude talks to api.anthropic.com directly; measured only once routed (simplicio-cli wrap claude, or ANTHROPIC_BASE_URL → http://127.0.0.1:8788)
Codex	✓ (skill)	✗ by default — simplicio-cli init codex adds the MCP tools but does not route LLM traffic; measured with simplicio-cli wrap codex or an OpenAI base-url pointing at the proxy

So: the savings happen on every runtime; the monitor tallies them automatically on Simplicio Agent, and on Claude/Codex after a one-time routing step (simplicio-cli wrap … / base-url → :8788). Without routing, the economy still applies — the monitor just won't count those tokens. scripts/simplicio-economy.sh wire does this routing for OpenAI-compatible clients at install time.

📈 Simplicio Token Monitor

A view of the savings you open when you want — only the capture is always-on:

• Capture proxy — always-on (the one auto-started service; the wired clients need it reachable). It silently captures + measures Claude + Codex + Simplicio Agent in the background.
• Web dashboard — http://127.0.0.1:9090 — real-time token chart, savings gauge, the LLMs/runtimes and 141/144 providers (98%) we intercept, a live proxy log. Opens once on the first install so you see it works, then it's on-demand — re-open it any of these ways:
  • simplicio-loop dashboard — works from anywhere after the pip install (no repo path needed); simplicio-loop dashboard --stop to close, --no-browser to just start the server.
  • bash scripts/simplicio-economy.sh monitor (repo checkout) · … monitor stop to close.
  • just ask the agent — "open the token dashboard".
• Menu-bar / tray widget — live tokens saved in the system tray (macOS rumps · Windows/Linux pystray). On-demand:bash scripts/simplicio-economy.sh tray · … tray stop.

Install auto-starts only the capture proxy (macOS launchd · Linux systemd · Windows Startup). The dashboard opens once on a fresh install (marker-guarded — a re-install/update never reopens it; opt out with SIMPLICIO_NO_DASHBOARD=1), and the tray never opens by itself — nothing is forced to stay 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.

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 .simplicio/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 is the native Simplicio capture engine (stdlib-only, fail-open) — a native, transparent capture proxy + deterministic compression engine with no external dependency. Run any command via the scripts/simplicio-engine wrapper (e.g. simplicio-engine doctor):

Command	What it does
proxy	the transparent capture proxy — routes each model to its real provider, compresses + measures + caches (no model swap)
doctor	proxy reachability + lifetime savings
cache	native response cache (stats/clear) — a repeated deterministic request is served from cache, skipping the LLM call
signatures	signatures-only view of a source file (bodies stripped, ~93% fewer tokens to read code)
semantic	reversible extractive (semantic-lite) compression
detect	content-type detection + smart per-block routing
rag	TF-IDF (or --ml embedding) retrieval over the CCR memory store
memory	CCR compress-cache-retrieve store (remember/recall/forget/list/stats)
mcp	native stdio MCP server (compress / retrieve / stats tools)
init / wrap	register Simplicio into a client (Claude / Codex / Copilot / OpenClaw) · run a client with capture routing
report / audit / capture / evals	savings report · audit a tree for compression opportunity · dry-run a request · compression regression gate

---

🏛️ Design pillars (in detail)

Four mechanisms sustain the orchestration power:

Pillar	Focus	Lives in
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
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:

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):

git clone https://github.com/wesleysimplicio/simplicio-loop
cd simplicio-loop
# install for your runtime (omit <runtime> to auto-detect)
bash scripts/install.sh <runtime> [--global] [--minimal] # macOS / Linux
pwsh scripts/install.ps1 <runtime> [-Global] # Windows# <runtime> ∈ claude codex vscode cursor antigravity kiro opencode gemini aider simplicio_agent openclaw# (hermes still accepted as a legacy alias for simplicio_agent)

The repo installer is full-stack by default — it installs everything. One command sets up the whole stack: the loop operator package (simplicio-cli, which exposes simplicio-dev-cli and also brings simplicio-mapper transitively, auto-handling PEP 668 / externally-managed Python and symlinking the binaries onto PATH), the full Python stack (the package itself), the 7 skills + hooks with the loop's Stop hook wired, and the always-on capture proxy with Claude + Codex + Simplicio Agent 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. Pass --minimal only for headless/CI to skip the heavy deps + the machine services. Verify any time: bash scripts/simplicio-economy.sh status.

Update

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.

Doctor — verify + repair

python3 scripts/doctor.py # report the whole stack (REQUIRED vs OPTIONAL)
python3 scripts/doctor.py --repair # install/wire what's fixable; make everything operational
python3 scripts/preflight.py --json # fail-closed mapper + dev-cli; optional Runtime is reported separately# also: bash scripts/simplicio-economy.sh doctor [--repair]

doctor separates REQUIRED (python3, the loop operator package and its mapper/dev-cli bins, the 7 skills, the loop hooks, the capture proxy — --repair installs/wires them) from OPTIONAL accelerators (the native Simplicio Runtime bind and the tray dependency). 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 long as every REQUIRED item is healthy.

Or, on Claude Code / Cursor, install it straight from the latest GitHub release (no marketplace):

gh release download --repo wesleysimplicio/simplicio-loop --archive tar.gz
tar xzf simplicio-loop-*.tar.gz &&cd simplicio-loop-*/
bash scripts/install.sh claude # or: bash scripts/install.sh cursor

Then:

/simplicio-loop finish all the open issues

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 and adapters/MATRIX.md.

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.

---

🔒 Safety (non-negotiable)

• Secret-scan every diff; block on hit.
• Irreversible-op human gate — force-push, history rewrite, prod deploy, data/schema delete, mass-file delete → stop and ask. Headless + no approver → remove the destructive capability.
• Enforced, not just promised — hooks/action_gate.py is a fail-closedPreToolUse / git-pre-push hook that mechanically blocks the above (and secret-laden commits) before they run. The safety contract holds even if the model forgets it. selftest proves the ruleset (15/15).
• 4-state pre-execution verdict — optimization may never raise a command's risk tier.
• 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.
• Evidence-gated completion (never a false "done"); fail-open hooks (never trap the agent in a loop); explicit STOP/cancel path for unattended runs.

---

✅ Tests & local checks (no paid CI)

Claims are verified, not just asserted — and the gate runs locally, with zero CI cost:

python3 scripts/check.py # complete local gate (core + satellite tests)
python3 scripts/check.py --core-gate # mandatory offline/bounded core; external lanes excluded

Both commands require an importable pytest; its absence is pytest_unavailable, never a direct-execution fallback. The core gate runs claims audit, mirror parity, core pytest tests, loop contract, clean-environment contract, token/repository budgets, and portable stage-contract validation. It uses a sanitized subprocess environment, disables third-party pytest autoload, and applies the loopback/AF_UNIX socket restriction to pytest and Python descendants that inherit the gate environment; it does not sandbox arbitrary external CLIs. It has a 600-second global deadline plus shorter per-phase deadlines, and fails if no mandatory test actually ran. Installed runtimes, live APIs, sibling repositories, release builds, and other real external integrations stay in explicitly marked lanes and are reported as unavailable/excluded — never silently promoted to PASS.

docs/SCRIPTS_INVENTORY.md documents the gate-relevant core (required for the loop drive or this gate) and satellite (opt-in/advanced) boundaries; it is not a census of every utility under scripts/. The current checkout and its local gate receipt are authoritative for inventory and execution counts. Lead with the core; treat the rest as advanced, opt-in capabilities you reach for when the task calls for them.

• Test suite (tests/, requires pytest) — the workers' deterministic selftests, 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 BLOCK (never fake-pass) when their toolchain is absent. Individual legacy test modules may retain a developer self-runner, but scripts/check.py never treats that partial mechanism as a substitute for pytest collection.
• Claims audit (scripts/claims_audit.py, fail-closed) — every scripts/*.py the docs reference exists · the extension-point count agrees across all files · each cited worker command actually runs · the shipped simplicio_loop/_bundle/ skills are byte-identical to source.
• Impact audit (scripts/impact_audit.py) — for any code task, proves the declared task surface covers the local blast radius: dependencies, reverse dependents, and related tests.

  python3 scripts/impact_audit.py audit . --file path/to/seed.py --cover path/to/seed.py --fail-on high

• Flow audit (scripts/flow_audit.py) — for mixed front/back/service repos, produces the endpoint_compare evidence map and fails on objective integration gaps:

  python3 scripts/flow_audit.py audit . --fail-on high

• Wire it as a git pre-push hook to keep main honest for free:

  printf'#!/bin/sh\npython3 scripts/check.py\n'> .git/hooks/pre-push && chmod +x .git/hooks/pre-push

Install the development extra (pip install "simplicio-loop[dev]") before running scripts/check.py: pytest is a required gate dependency.

---

⭐ Star History

---

📄 License

MIT

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

pwsh scripts/install.ps1 claude -Global
pwsh scripts/install.ps1 codex -Global
pwsh scripts/install.ps1 cursor -Global
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 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 makes the comment confirmation mandatory before COMPLETE. #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.

GitHub Actions is not required or accepted as validation evidence for this repository; the local gate is authoritative. Lifecycle state is projected by the local runtime integration when configured; it can manage the simplicio:status:<state> label and a GitHub Projects v2 Status field. The projection is runtime-neutral: it accepts Claude, Codex, Cursor, Gemini, Kiro, Antigravity, Hermes/Simplicio Agent, OpenClaw, and future providers. Set these repository variables to enable Project v2 movement:

SIMPLICIO_PROJECT_NUMBER # project number, for example 7
SIMPLICIO_PROJECT_OWNER # optional; defaults to the repository owner
SIMPLICIO_PROJECT_OWNER_TYPE # organization (default) or user
SIMPLICIO_PROJECT_STATUS_FIELD # optional; defaults to Status

Labels still update when no Project is configured. Human comments do not move cards; only the marked Simplicio lifecycle comment, issue open/close/reopen events, or an explicit workflow dispatch can change the status. The workflow uses issues: write and repository-projects: write and never posts a second coordination comment.