simplicio-loop 3.24.0__tar.gz → 3.25.1__tar.gz

{simplicio_loop-3.24.0/simplicio_loop.egg-info → simplicio_loop-3.25.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplicio-loop
-Version: 3.24.0
+Version: 3.25.1
 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
@@ -19,7 +19,6 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: simplicio-mapper>=0.19.0
 Requires-Dist: simplicio-cli>=0.11.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
@@ -35,7 +34,7 @@ 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.jpg)
+![simplicio-loop](https://raw.githubusercontent.com/wesleysimplicio/simplicio-loop/main/assets/simplicio-loop-hero-2026.png)
 
 ## Install
 

{simplicio_loop-3.24.0 → simplicio_loop-3.25.1}/PYPI.md

@@ -5,7 +5,7 @@ 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.jpg)
+![simplicio-loop](https://raw.githubusercontent.com/wesleysimplicio/simplicio-loop/main/assets/simplicio-loop-hero-2026.png)
 
 ## Install
 

{simplicio_loop-3.24.0 → simplicio_loop-3.25.1}/README.md

@@ -1,7 +1,7 @@
 # 🔁 simplicio-loop — The Universal Looping AI Orchestrator
 
 <p align="center">
-  <img src="assets/simplicio-loop-hero.jpg" alt="simplicio-loop" width="920" />
+  <img src="assets/simplicio-loop-hero-2026.png" alt="simplicio-loop autonomous parallel evidence-gated orchestration" width="920" />
 </p>
 
 <p align="center">
@@ -48,6 +48,41 @@
 
 ---
 
+<!-- visual-story:start -->
+## 🚀 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.
+- **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.
+
+<p align="center">
+  <img src="assets/simplicio-loop-parallel-worktrees.png" alt="simplicio-loop parallel isolated worktree execution" width="920" />
+</p>
+
+<p align="center"><em>Dependency-aware fan-out: isolated workers execute concurrently, return evidence, and converge into one verified delivery.</em></p>
+
+<p align="center">
+  <img src="assets/simplicio-loop-lifecycle-2026.svg" alt="simplicio-loop lifecycle from intake to durable memory" width="920" />
+</p>
+
+<p align="center"><em>Every stage is explicit, bounded, observable, and reversible.</em></p>
+
+<p align="center">
+  <img src="assets/simplicio-loop-evidence-memory.png" alt="simplicio-loop evidence memory verification rollback and completion" width="920" />
+</p>
+
+<p align="center"><em>Evidence and memory are part of the execution path—not a report written after the fact.</em></p>
+
+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.
+
+<p align="center">
+  <img src="assets/simplicio-loop-architecture-2026.svg" alt="simplicio-loop control execution evidence and delivery planes" width="920" />
+</p>
+<!-- visual-story:end -->
+
 ## ⚡ TL;DR
 
 **simplicio-loop** is a runtime-agnostic **super-plugin** — one autonomous looping
@@ -210,79 +245,28 @@ Every layer the orchestrator acts on, in order — from reading the demand (issu
 to delivering merged, evidenced work, then looping 24/7 for more.
 
 ```mermaid
-flowchart TD
-  subgraph SRC["1 · Demand sources (any adapter)"]
-    direction LR
-    S1["GitHub Issues / PRs / CI"]
-    S2["Jira · Azure DevOps · Linear · ClickUp · Notion · agentsview · Understand Anything (orient)"]
-    S3["Assigns · TODO/FIXME · CVE · local files · LMCache (inference accelerator)"]
-  end
-  SRC --> PF
-  subgraph PF["2 · Pre-flight gates"]
-    direction LR
-    P1["source auth + scopes"]
-    P2["runtime/tools ready"]
-    P3["arm 24/7 watcher + STOP path"]
-  end
-  PF --> DISC
-  subgraph DISC["3 · Discover + normalize"]
-    direction LR
-    D1["source_adapter: list metadata only"]
-    D2["normalize to canonical schema"]
-    D3["dedup id+title+fingerprint+branch/PR"]
-    D4["dependency DAG"]
-  end
-  DISC --> INTK
-  subgraph INTK["4 · Deep intake (per item)"]
-    direction LR
-    I1["body + ALL comments"]
-    I2["extract acceptance criteria"]
-    I3["orient code · signatures-only reads or Understand Anything knowledge graph"]
-    I4["plan + AC checklist + complexity"]
-  end
-  INTK --> RT{"5 · Route"}
-  RT -->|"small and every item complexity at most 3"| FAST["Fast-path: solo, one targeted test"]
-  RT -->|"large queue or any medium+"| POOL
-  subgraph POOL["6 · Continuous worker pool (autoscaled, conflict-aware)"]
-    direction LR
-    W1["claim · branch · worktree if overlap"]
-    W2["deterministic_edit"]
-    W3["quality loop: edit-lint-test-fix"]
-  end
-  FAST --> QG
-  POOL --> QG
-  subgraph QG["7 · Quality gates"]
-    direction LR
-    Q1["AC gate + impact_audit = real DoD"]
-    Q2["WORKS not just compiles · web_verify · video_evidence · flow_audit"]
-    Q3["adversarial review · thermos rubrics"]
-  end
-  QG --> SG
-  subgraph SG["8 · Safety gates (non-negotiable)"]
-    direction LR
-    G1["secret-scan"]
-    G2["irreversible-op human gate"]
-    G3["4-state verdict · attestation"]
-  end
-  SG --> DEL
-  subgraph DEL["9 · Deliver"]
-    direction LR
-    L1["commit · push · Draft PR"]
-    L2["close in-source + evidence"]
-    L3["verify reality, not self-report"]
-  end
-  DEL --> FB
-  subgraph FB["10 · Feedback loop to merge-ready"]
-    direction LR
-    F1["CI fail -> fix root cause"]
-    F2["review comments -> adjust"]
-    F3["branch behind main -> additive rebase"]
-  end
-  FB -->|"merged and closed"| DONE(["done + evidence + measured savings (only if a receipt exists)"])
-  WATCH["11 · 24/7 watcher · simplicio-loop evidence-gated promise · max-iterations cap · STOP path · LMCache KV cache warm"]
-  FB -. "poll new work / comments / checks" .-> WATCH
-  DONE -. "idle until new work" .-> WATCH
-  WATCH -. "re-feed the goal" .-> DISC
+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?"}
+  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"]
+  A --> VERIFY
+  B --> VERIFY
+  C --> VERIFY
+  VERIFY --> RECEIPT["Watcher challenge + evidence receipt"]
+  RECEIPT --> ORACLE{"6 · 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"]
+  WATCH -->|"new work"| IN
 ```
 
 ---
@@ -530,8 +514,9 @@ pwsh scripts/install.ps1 <runtime> [-Global]                    # Windows
 ```
 
 **The repo installer is full-stack by default — it installs everything.** One command sets up the whole stack:
-the two loop operators (`simplicio-mapper` + `simplicio-cli`, auto-handling PEP 668 / externally-managed
-Python and symlinking the binaries onto `PATH`), the **full Python stack** (the package itself),
+the 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 + Hermes **routed and measured** in the background. The **dashboard opens once** on a
 fresh install, then it's on-demand (`simplicio-loop dashboard` / `simplicio-economy.sh monitor`); the
@@ -556,7 +541,7 @@ python3 scripts/doctor.py --repair   # install/wire what's fixable; make everyth
 # also: bash scripts/simplicio-economy.sh doctor [--repair]
 ```
 
-`doctor` separates **REQUIRED** (python3, the two loop operators, the 7 skills, the loop hooks, the
+`doctor` separates **REQUIRED** (python3, the loop operator package plus its runtime bins, the 7 skills, the loop hooks, the
 capture proxy — `--repair` installs/wires them) from **OPTIONAL** accelerators (the tray dep).
 **Missing an optional piece is never a failure and
 never blocks** — the Python engine + the deterministic path cover everything; the exit code is 0 as

{simplicio_loop-3.24.0 → simplicio_loop-3.25.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simplicio-loop"
-version = "3.24.0"
+version = "3.25.1"
 description = "The Universal Looping AI Orchestrator — a runtime-agnostic super-plugin (7 skills) that drains any queue of work end-to-end on any LLM/runtime."
 readme = "PYPI.md"
 requires-python = ">=3.8"
@@ -21,11 +21,9 @@ classifiers = [
   "Topic :: Utilities",
   "Operating System :: OS Independent",
 ]
-# The simplicio-loop drive REQUIRES two operators (see .claude/skills/simplicio-loop/SKILL.md):
-#   simplicio-mapper -> the repo-survey step (binds `orient`)
-#   simplicio-cli    -> the operator that applies+verifies changes (binds `execute`/`deterministic_edit`)
+# The simplicio-loop drive requires the operator package (`simplicio-cli`), which exposes
+# `simplicio-dev-cli` and also brings the survey binary `simplicio-mapper` transitively.
 dependencies = [
-  "simplicio-mapper>=0.19.0",
   "simplicio-cli>=0.11.0",
 ]
 

{simplicio_loop-3.24.0 → simplicio_loop-3.25.1}/simplicio_loop/__init__.py

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

simplicio_loop-3.25.1/simplicio_loop/_bundle/hooks/loop_capture.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""simplicio-loop — capture hook (Cursor `afterAgentResponse`).
+
+Transport only: stash the latest assistant response so the shared completion oracle
+can evaluate it later in the stop hook. This hook never decides completion and never
+raises `done` on its own.
+"""
+import json
+import os
+import sys
+
+LOOP_DIR = os.path.join(".orchestrator", "loop")
+LAST_RESP = os.path.join(LOOP_DIR, "last_response.txt")
+
+
+def main():
+    try:
+        raw = sys.stdin.read()
+        data = json.loads(raw) if raw.strip() else {}
+        resp = data.get("text", "") or ""
+        if resp:
+            os.makedirs(LOOP_DIR, exist_ok=True)
+            with open(LAST_RESP, "w", encoding="utf-8") as f:
+                f.write(resp)
+    except Exception:
+        pass
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

{simplicio_loop-3.24.0 → simplicio_loop-3.25.1}/simplicio_loop/_bundle/hooks/loop_stop.py

@@ -26,6 +26,14 @@ import subprocess
 import sys
 import time
 import uuid
+from pathlib import Path
+
+try:  # Windows consoles default to cp1252; hook protocols and evidence are UTF-8.
+    sys.stdin.reconfigure(encoding="utf-8", errors="replace")
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
 
 LOOP_DIR = os.path.join(".orchestrator", "loop")
 SCRATCHPAD = os.path.join(LOOP_DIR, "scratchpad.md")
@@ -222,6 +230,7 @@ def write_handoff(reason, meta=None, body=None):
         anchor = read_anchor() or {}
         criteria = anchor.get("criteria") or []
         attempts = tail_journal()
+        completion = latest_completion_receipt() or {}
         lines = [
             "# simplicio-loop handoff",
             "",
@@ -262,6 +271,16 @@ def write_handoff(reason, meta=None, body=None):
                         attempt_suffix(a),
                     )
                 )
+        if completion:
+            lines += [
+                "",
+                "## Completion oracle",
+                "",
+                "- verdict: %s" % completion.get("verdict", "DELIVERY_PENDING"),
+                "- reason_code: %s" % completion.get("reason_code", "oracle_incomplete"),
+                "- tag: %s" % completion.get("tag", "UNVERIFIED"),
+                "- receipt: %s" % completion.get("_path", "(unknown)"),
+            ]
         lines += [
             "",
             "## Resume",
@@ -679,6 +698,70 @@ def watcher_verify():
         return False, "UNVERIFIED"
 
 
+def latest_run_dir():
+    try:
+        runs = Path(".orchestrator") / "runs"
+        if not runs.exists():
+            return ""
+        candidates = sorted([p for p in runs.iterdir() if p.is_dir()], key=lambda p: p.name)
+        return str(candidates[-1]) if candidates else ""
+    except Exception:
+        return ""
+
+
+def latest_completion_receipt():
+    try:
+        run_dir = latest_run_dir()
+        if not run_dir:
+            return None
+        path = Path(run_dir) / "completion-receipt.json"
+        if not path.exists():
+            return None
+        with open(path, encoding="utf-8") as f:
+            payload = json.load(f)
+        payload["_path"] = str(path)
+        return payload
+    except Exception:
+        return None
+
+
+def completion_oracle_payload(response_text="", flow_gap=""):
+    try:
+        repo_root = os.getcwd()
+        script = os.path.join(repo_root, "scripts", "completion_oracle.py")
+        if not os.path.exists(script):
+            source_repo = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+            script = os.path.join(source_repo, "scripts", "completion_oracle.py")
+        if not os.path.exists(script):
+            return {"ready": False, "reason_code": "oracle_script_missing", "tag": "UNVERIFIED"}
+        run_dir = latest_run_dir()
+        cmd = [sys.executable, script, "--loop-dir", LOOP_DIR]
+        if run_dir:
+            cmd += ["--run-dir", run_dir]
+        if response_text:
+            cmd += ["--response-text", response_text]
+        if flow_gap:
+            cmd += ["--flow-gap", flow_gap]
+        if run_dir:
+            cmd += ["--write-receipt"]
+        r = subprocess.run(
+            cmd,
+            capture_output=True,
+            stdin=subprocess.DEVNULL,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=15,
+            cwd=repo_root,
+        )
+        payload = json.loads(r.stdout) if (r.stdout or "").strip() else {}
+        if isinstance(payload, dict):
+            return payload
+        return {"ready": False, "reason_code": "oracle_invalid_payload", "tag": "UNVERIFIED"}
+    except Exception:
+        return {"ready": False, "reason_code": "oracle_error", "tag": "UNVERIFIED"}
+
+
 def spindle_latched():
     """True when a spindle handoff exists with an unreleased latch.
 
@@ -861,24 +944,31 @@ def main():
         # Pre-promise: front→back flow-audit gate (#80) — mechanical, not prose-only.
         flow_gap = flow_audit_gap()
 
-        # Completion detection (capture folded in for single-hook runtimes like Claude).
+        # Completion detection is centralized in the shared oracle (#138). The stop hook can still
+        # surface watcher/flow state in the re-feed header below, but it no longer decides COMPLETE
+        # on its own.
         if promise and resp:
-            m = PROMISE_RE.search(resp)
-            if m and m.group(1).strip() == promise.strip():
-                # The promise is honored only with evidence AND watcher verification AND no
-                # acceptance criterion still open in the task anchor AND no open flow-audit gap.
-                # The watcher-gate ensures the agent's result was independently re-executed and
-                # matched before the promise is accepted — corrective gate per Asolaria.
-                if (((not evidence_required) or has_evidence) and watcher_pass
-                        and not anchor_pending() and not flow_gap):
+            oracle = completion_oracle_payload(resp, flow_gap or "")
+            if oracle.get("ready") and os.path.exists(str(oracle.get("receipt_path") or "")):
+                _call_simplicio_hbp_append(iteration, promise, watcher_tag)
+                refresh_cross_agent_wiki(include_handoff=False)
+                cleanup_and_stop()  # (3) promise fulfilled → stop, no handoff needed
+            # Legacy converge fixtures and lightweight installs predate persisted run artifacts.
+            # Preserve their evidence-gated contract only when the oracle explicitly reports that
+            # no run directory exists; every persisted run remains exclusively oracle-authorized.
+            if oracle.get("reason_code") == "run_dir_missing":
+                match = PROMISE_RE.search(resp)
+                if (match and match.group(1).strip() == promise.strip()
+                        and ((not evidence_required) or has_evidence)
+                        and watcher_pass and not anchor_pending() and not flow_gap):
                     _call_simplicio_hbp_append(iteration, promise, watcher_tag)
                     refresh_cross_agent_wiki(include_handoff=False)
-                    cleanup_and_stop()  # (3) promise fulfilled → stop, no handoff needed
-                # promise without evidence, or watcher disagrees, or anchor still has open ACs,
-                # or a flow-audit gap remains → ignore, keep looping
+                    cleanup_and_stop()
         # (3') Cursor capture may have raised the flag.
         if os.path.exists(DONE_FLAG) or os.path.exists(LEGACY_DONE_FLAG):
-            cleanup_and_stop()
+            oracle = completion_oracle_payload(flow_gap=flow_gap or "")
+            if oracle.get("ready") and os.path.exists(str(oracle.get("receipt_path") or "")):
+                cleanup_and_stop()
         # (4) Iteration cap — incomplete stop, hand off.
         if max_iter > 0 and iteration >= max_iter:
             _call_simplicio_hbp_append_topic("loop-run-blocked", {

{simplicio_loop-3.24.0 → simplicio_loop-3.25.1}/simplicio_loop/_bundle/hooks/pre-commit.py

@@ -58,7 +58,10 @@ def _monitored_paths():
     for prefix in WATCHED_SOURCE_DIRS:
         full = os.path.join(REPO, prefix)
         if os.path.exists(full):
-            watched.add(full)
+            # Normalize separators before commonpath on Windows.  A manifest entry
+            # may use POSIX-style `/` while git emits `\\`; mixed forms caused the
+            # hook to silently miss staged skill changes on Windows.
+            watched.add(os.path.abspath(os.path.normpath(full)))
     return watched
 
 
@@ -77,7 +80,7 @@ def _staged_changes_touch_monitored():
 
     for rel_path in r.stdout.splitlines():
         for watched in _monitored_paths():
-            abs_path = os.path.join(REPO, rel_path)
+            abs_path = os.path.abspath(os.path.normpath(os.path.join(REPO, rel_path)))
             if os.path.commonpath([abs_path, watched]) == watched:
                 return True
     return False

{simplicio_loop-3.24.0 → simplicio_loop-3.25.1}/simplicio_loop/_bundle/hooks/simplicio_watch.py

@@ -15,6 +15,13 @@ import subprocess
 import sys
 from pathlib import Path
 
+
+try:  # Status icons and protocol output must survive Windows cp1252 consoles.
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
+
 HOME = os.path.expanduser("~")
 LOGS = os.path.join(HOME, ".simplicio", "logs")
 REPO_ROOT = Path(__file__).resolve().parents[1]
@@ -36,6 +43,11 @@ PROXY_SERVICE = "ai.simplicio.proxy"
 
 
 def log(msg):
+    encoding = getattr(sys.stdout, "encoding", None) or "utf-8"
+    try:
+        msg = str(msg).encode(encoding).decode(encoding)
+    except UnicodeEncodeError:
+        msg = str(msg).encode(encoding, errors="replace").decode(encoding)
     print(msg)
 
 

{simplicio_loop-3.24.0 → simplicio_loop-3.25.1}/simplicio_loop/_bundle/scripts/hierarchical_planner.py

@@ -38,6 +38,12 @@ import sys
 import tempfile
 import time
 
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
+
 HERE = os.path.dirname(os.path.abspath(__file__))
 REPO = os.path.dirname(HERE)
 LOOP_DIR = os.path.join(REPO, ".orchestrator", "loop")

{simplicio_loop-3.24.0 → simplicio_loop-3.25.1}/simplicio_loop/_bundle/skills/simplicio-loop/SKILL.md

@@ -46,13 +46,17 @@ The rest of this file is the mechanism that enforces this contract.
 - "/simplicio-loop finish all the open issues", "clear the CI queue", "drain the Jira board".
 - "run a ralph loop on X", "iterate until the tests pass", "keep going until done".
 - As the unified public entrypoint for unattended queue-drain or converge-until-done runs.
+- For body-of-work / Phase-0 drains, freeze the backlog once (`task_backlog.py init`) and use
+  `task_backlog.py checklist` / `pr_evidence.py build --backlog ...` so the PR shows the whole
+  backlog table above the per-item anchor checklist, not just the current item.
 - NOT for a one-shot edit — use the host's normal flow.
 
 ## Bound operators (REQUIRED): survey + operate
 
 This loop does NOT survey the repo with the LLM, and it does NOT hand-edit files with the LLM.
-Two installed CLIs are the operators; the model only DECIDES, the operators DO. Both ship as
-hard dependencies of the `simplicio-loop` package (`pip install simplicio-loop` pulls them).
+Two installed CLIs are the operators; the model only DECIDES, the operators DO. The supported
+install surface is the operator package `simplicio-cli`, which exposes `simplicio-dev-cli` and
+also brings `simplicio-mapper` transitively for the survey step.
 Full mechanics (two-tier survey, evidence gate, context-pack, structured queries, docs-drift
 gates, the operator dispatch table): **`references/bound-operators.md`**.
 
@@ -61,19 +65,19 @@ gates, the operator dispatch table): **`references/bound-operators.md`**.
 | **simplicio-mapper** | `simplicio-mapper` | `orient` / `recall` | **Survey** — maps the repo(s) into `.simplicio/*.json` (project-map, precedent-index, symbol-index, call-graph, docs). This survey, not an ad-hoc LLM read, is what feeds the goal each turn. |
 | **simplicio-dev-cli** | `simplicio-dev-cli` | `execute` / `deterministic_edit` / `validate` / `diagnostics` | **Operate** — applies a DECIDED change through its 6-layer contract (mapper context → precedent → prompt → diff → test → verify, ≤3 retries). The CLI edits and verifies; the AI does not hand-write the diff. |
 
-**Preflight (MANDATORY, BLOCKING).** Before iteration 1, auto-update both operators to their
-latest release, then confirm both are on PATH:
+**Preflight (MANDATORY, BLOCKING).** Before iteration 1, auto-update the operator package to its
+latest release, then confirm both runtime binaries are on PATH:
 ```bash
-python3 -m pip install -qU simplicio-mapper simplicio-cli 2>/dev/null \
-  || python3 -m pip install -qU --user --break-system-packages simplicio-mapper simplicio-cli 2>/dev/null || true
-simplicio-mapper --version   # survey operator (now latest)
+python3 -m pip install -qU simplicio-cli 2>/dev/null \
+  || python3 -m pip install -qU --user --break-system-packages simplicio-cli 2>/dev/null || true
+simplicio-mapper --version   # survey operator (expected transitively from simplicio-cli)
 simplicio-dev-cli --help     # action operator (pkg simplicio-cli; exposes `simplicio-dev-cli`)
 ```
 Best-effort and offline-safe — a network/pip failure leaves the working version in place. The
 action binary is `simplicio-dev-cli` (from `pip install simplicio-cli`) — NOT the bare `simplicio`
-(that's the separate `simplicio-runtime`). If either operator is missing, do NOT fall back to LLM
-survey/editing — STOP and emit `simplicio-loop: BLOCKED — missing operator <name>; run: pip
-install simplicio-loop`.
+(that's the separate `simplicio-runtime`). If either runtime binary is missing, do NOT fall back to
+LLM survey/editing — STOP and emit `simplicio-loop: BLOCKED — missing operator <name>; run: pip
+install simplicio-cli`.
 
 **Survey step (each loop start).** `simplicio-mapper scan . --json` (instant macro skeleton +
 background deep index) → gate with `inspect . --json` (artifacts exist on disk) → feed the goal
@@ -211,22 +215,20 @@ halt the whole drain). `simplicio-tasks` Step 3 routes fast-path/heavy-path on t
 When the goal is vague and no external source (board/issues) supplies items, the LLM brainstorms
 the decomposition — subtasks with ≥1 acceptance criterion each, `depends_on`, risks — and MUST
 freeze it BEFORE any edit: `python3 scripts/task_backlog.py init --goal "<goal verbatim>"
---items-file plan.json` (the worker refuses an empty plan, a zero-AC item, or an unknown/cyclic
+--item-file plan.json` (the worker refuses an empty plan, a zero-AC item, or an unknown/cyclic
 dependency — the AI decides, the worker freezes, orders and gates). State:
 `.orchestrator/backlog/backlog.jsonl`.
 
-**Genesis.** First run `python3 scripts/task_backlog.py genesis --exit-code` — exit 10 means a
-repo with NO code yet. There `init` demands `--genesis` plus exactly one item tagged `scaffold`
-(structure + toolchain + one minimal green test as its ACs); the worker reorders it to T1 and
-makes every other item depend on it. After the scaffold item's gate passes, re-run
-`simplicio-mapper scan . --json` before claiming the next item — the survey only feeds the goal
-once there is something to map.
-
-**Per-item cycle**: `python3 scripts/task_backlog.py next` claims one item (re-prints the one in
-flight) and prints the ready `task_anchor.py set` arming command → work it under the normal
-converge contract → `python3 scripts/task_backlog.py done --id T1` (exit 12 unless the ARMED
-anchor is this item with every AC verified) → `next` again; exactly `empty` = drained.
+**Scaffolding a new repo.** Put exactly one explicit `scaffold` item first in `plan.json`
+(structure + toolchain + one minimal green test as its ACs) and make every later item depend on
+it. After that item passes, re-run `simplicio-mapper scan . --json` before claiming the next
+item — the survey only becomes useful once there is code to map.
 
+**Per-item cycle**: `python3 scripts/task_backlog.py next` claims one ready item and prints its id,
+goal, lease owner, and fencing token → freeze that item's goal/ACs with `task_anchor.py set` → work
+it under the normal converge contract → `python3 scripts/task_backlog.py done --item T1` (exit 12
+unless the current anchor is this item with every AC verified) → `next` again. `status`/`poll`
+provide the deterministic drain signal and active-lease view.
 ## HRM-style hierarchical planner (two-level reasoning loop)
 
 Inspired by the **Hierarchical Reasoning Model** (arXiv:2506.21734, JesseBrown1980/HRM), the loop

{simplicio_loop-3.24.0 → simplicio_loop-3.25.1}/simplicio_loop/_bundle/skills/simplicio-loop/references/bound-operators.md

@@ -4,32 +4,34 @@ Moved out of `SKILL.md` § Bound operators as part of the #119 shrink (SKILL.md
 operator table, the preflight one-liner, and the BLOCK rule; this file has the full mechanics).
 
 This loop does NOT survey the repo with the LLM, and it does NOT hand-edit files with the LLM.
-Two installed CLIs are the operators; the model only DECIDES, the operators do. Both ship as
-hard dependencies of the `simplicio-loop` package (`pip install simplicio-loop` pulls them):
+Two installed CLIs are the operators; the model only DECIDES, the operators do. The supported
+install surface is the single operator package `simplicio-cli`, which exposes `simplicio-dev-cli`
+and also brings `simplicio-mapper` transitively:
 
 | Operator | CLI (binary) | Binds | Role in the loop |
 |---|---|---|---|
 | **simplicio-mapper** | `simplicio-mapper` | `orient` / `recall` | **Survey** — maps the repo(s) into `.simplicio/*.json` (project-map, precedent-index, symbol-index, call-graph, docs). Two-tier (v0.9+): `macro` is an instant shallow skeleton (no content reads), `scan` returns that skeleton now and runs the deep index in the background, `status` reports the deep-pass phase. v0.13+ adds `inspect` (machine-readable evidence that the artifacts actually exist — the survey's own evidence gate) and `handoff` (a compact context-pack — files, symbols, deps, `pack_hash` — that feeds the goal instead of re-reading the tree). v0.14+ adds the flow-docs engine: `ask` (low-token structured queries over the artifacts), `sync --check`/`drift --check` (docs-staleness + spec-drift gates), `flows`/`survey`/`business`/`history`/`diff` (flow inventory, onboarding report, business rules, architecture history). This survey, not an ad-hoc LLM read, is what feeds the goal each turn. |
 | **simplicio-dev-cli** | `simplicio-dev-cli` | `execute` / `deterministic_edit` / `validate` / `diagnostics` | **Operate** — applies a DECIDED change through its 6-layer contract (mapper context → precedent → prompt → diff → test → verify, ≤3 retries). The CLI edits and verifies; the AI does not hand-write the diff. |
 
-**Preflight (MANDATORY, BLOCKING).** Before iteration 1, auto-update both operators to their latest
-release (so every run uses the newest `simplicio-mapper`/`simplicio-cli`), then confirm both are on
+**Preflight (MANDATORY, BLOCKING).** Before iteration 1, auto-update the operator package to its
+latest release (so every run uses the newest `simplicio-cli`-shipped `simplicio-mapper`/`simplicio-dev-cli`),
+then confirm both runtime binaries are on
 PATH:
 ```bash
 # Always run the loop on the latest operators. FAIL-OPEN: offline / no-pip / a pin keeps the
 # currently-installed build; this never blocks. Runs ONCE per loop preflight, not per turn.
-python3 -m pip install -qU simplicio-mapper simplicio-cli 2>/dev/null \
-  || python3 -m pip install -qU --user --break-system-packages simplicio-mapper simplicio-cli 2>/dev/null || true
-simplicio-mapper --version   # survey operator (now latest)
+python3 -m pip install -qU simplicio-cli 2>/dev/null \
+  || python3 -m pip install -qU --user --break-system-packages simplicio-cli 2>/dev/null || true
+simplicio-mapper --version   # survey operator (expected transitively from simplicio-cli)
 simplicio-dev-cli --help     # action operator (pkg simplicio-cli; exposes `simplicio-dev-cli`)
 ```
 The auto-update is best-effort and offline-safe — a network/pip failure leaves the working version
 in place and the loop proceeds. The action binary is `simplicio-dev-cli` (from `pip install simplicio-cli`) — NOT the bare
 `simplicio`, which is reserved for the separate `simplicio-runtime` and is not what this loop
 binds. `simplicio-dev-cli` has no `--version` subcommand; `--help` exiting 0 is the readiness
-proof. If either operator is missing, do NOT fall back to LLM survey/editing — STOP and emit
-`simplicio-loop: BLOCKED — missing operator <name>; run: pip install simplicio-loop` (the install
-re-pulls `simplicio-mapper` + `simplicio-cli`). This requirement is scoped to the loop drive.
+proof. If either runtime binary is missing, do NOT fall back to LLM survey/editing — STOP and emit
+`simplicio-loop: BLOCKED — missing operator <name>; run: pip install simplicio-cli`. This requirement
+is scoped to the loop drive.
 
 **Survey step (each loop start + on any structural change).** Prefer the two-tier flow (v0.9+):
 `simplicio-mapper scan . --json` returns an instant `macro` skeleton AND kicks the deep index off in
@@ -95,7 +97,7 @@ merge/close gates); the operators do survey + apply:
 
 | Phase | Operator | Command |
 |---|---|---|
-| Preflight (before iteration 1) | both | `python3 -m pip install -qU simplicio-mapper simplicio-cli` (auto-update to latest, fail-open) → `simplicio-mapper --version` · `simplicio-dev-cli --help` → BLOCK if missing |
+| Preflight (before iteration 1) | both | `python3 -m pip install -qU simplicio-cli` (auto-update to latest, fail-open) → `simplicio-mapper --version` · `simplicio-dev-cli --help` → BLOCK if either runtime bin is missing |
 | Survey (loop start; multi-repo: per root) | mapper | `simplicio-mapper scan . --json` (instant macro + deep index in background; `--sync`/`--await` to block) → `.simplicio/*.json`. `index . --json` for a forced synchronous build. Gate: `inspect . --json` (artifacts exist on disk) → feed goal: `handoff . --for-llm toon` (context-pack, TOON-rendered; `--json` fallback + logged reason if the installed mapper predates `--for-llm`) |
 | Loop contract step 2 — Triage (every turn) | mapper | `simplicio-mapper handoff . --for-llm toon` → work from the `context_pack` (symbols/deps/recent_changes); `ask . impact\|tests-for\|callers <arg> --json` for targeted questions; `macro . --json` for an instant skeleton, or `scan`/`status` + `inspect` to refresh/re-gate if the tree changed |
 | Verify / DoD pass | mapper | `simplicio-mapper sync . --check --json` (stale generated docs) + `drift . --check --json` (spec↔code drift) — findings go in the turn report; BLOCK only when the AC itself is documentation |