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

{simplicio_loop-3.23.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.23.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,8 +19,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: simplicio-mapper>=0.17.0
-Requires-Dist: simplicio-cli>=0.9.6
+Requires-Dist: simplicio-cli>=0.11.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Provides-Extra: ml
@@ -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.23.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.23.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.23.0 → simplicio_loop-3.25.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simplicio-loop"
-version = "3.23.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,12 +21,10 @@ 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.17.0",
-  "simplicio-cli>=0.9.6",
+  "simplicio-cli>=0.11.0",
 ]
 
 # Optional: the real embedding backend for `simplicio-cli semantic --ml` / `simplicio-cli rag --ml`.

{simplicio_loop-3.23.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.23.0 → simplicio_loop-3.25.1}/simplicio_loop/_bundle/hooks/action_gate.py

@@ -235,8 +235,46 @@ def gate_command(cmd, staged=False):
 
 
 # ---------------------------------------------------------------------------------------------
-def _emit_and_exit(verdict, pretooluse=False):
+def _hbp_append_gate_blocked(reason, cmd=""):
+    """Record a gate BLOCK into the runtime's HBP tamper-evident hash chain (#128) — fail-open,
+    `simplicio`-only, mirrors `hooks/loop_stop.py`'s `_call_simplicio_hbp_append*` family. A
+    blocked mutation is exactly the kind of decision that should be provable later (a later
+    `simplicio hbp verify` can show this exact command/reason was recorded in order), not just
+    printed to stderr and forgotten. Absent binary or any failure: silent no-op, never blocks
+    the gate's own allow/block decision (that decision already happened before this is called).
+    """
+    binary = shutil.which("simplicio")
+    if not binary:
+        return
+    try:
+        import hashlib
+        # minimal payload contract shared by the #128 topics: fingerprint + attempt id.
+        fp = hashlib.sha1((reason or "").encode("utf-8", "replace")).hexdigest()[:12]
+        attempt = None
+        try:  # attempt id = live loop iteration from the scratchpad frontmatter, when armed
+            with open(os.path.join(".orchestrator", "loop", "scratchpad.md"),
+                      encoding="utf-8") as f:
+                m = re.search(r"^iteration:\s*(\d+)", f.read(), re.M)
+            attempt = int(m.group(1)) if m else None
+        except Exception:
+            attempt = None
+        payload = json.dumps({"fingerprint": fp, "attempt": attempt,
+                              "reason": (reason or "")[:200], "command": (cmd or "")[:200]})
+        subprocess.run(
+            [binary, "hbp", "append",
+             "--topic", "loop-gate-blocked",
+             "--payload", payload,
+             "--provenance", "simplicio-loop",
+             "--json"],
+            capture_output=True, timeout=15,
+        )
+    except Exception:
+        pass
+
+
+def _emit_and_exit(verdict, pretooluse=False, cmd=""):
     if verdict["action"] == "block":
+        _hbp_append_gate_blocked(verdict.get("reason", ""), cmd)
         if pretooluse:
             # Claude PreToolUse: exit 2 blocks the call; reason on stderr is fed back to the model.
             sys.stderr.write("action_gate BLOCK — " + verdict["reason"] + "\n")
@@ -251,7 +289,7 @@ def _emit_and_exit(verdict, pretooluse=False):
 
 def cmd_check(opts):
     cmd = opts.get("command", "")
-    _emit_and_exit(gate_command(cmd, staged=bool(opts.get("staged"))))
+    _emit_and_exit(gate_command(cmd, staged=bool(opts.get("staged"))), cmd=cmd)
 
 
 def cmd_scan_diff(opts):
@@ -271,6 +309,8 @@ def cmd_scan_diff(opts):
         for label, n in hits:
             print("  secret: %s (line %d)" % (label, n))
         print("block")
+        _hbp_append_gate_blocked("secret in diff (%s)" % ", ".join(sorted({h[0] for h in hits})),
+                                  "scan-diff %s" % (src or "-"))
         sys.exit(2)
     print("allow")
     sys.exit(0)
@@ -292,7 +332,7 @@ def from_pretooluse():
     cmd = (data.get("tool_input", {}) or {}).get("command", "")
     if not cmd:
         sys.exit(0)
-    _emit_and_exit(gate_command(cmd), pretooluse=True)
+    _emit_and_exit(gate_command(cmd), pretooluse=True, cmd=cmd)
 
 
 def cmd_selftest(_opts):

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.23.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",
@@ -326,9 +345,12 @@ def _changed_files():
     commit). A heuristic, not a precise "since loop start" diff — fail-open: {} on any error.
 
     Excludes `.orchestrator/` (the loop's own state files — never source, and would otherwise
-    make the receipt's own write, or a sibling state write, look like a "later" source change)
-    and build/cache noise (`__pycache__`, `.pyc`) that this very check's own module import can
-    create — that self-inflicted false-positive is exactly why both are filtered here.
+    make the receipt's own write, or a sibling state write, look like a "later" source change),
+    `.simplicio/` (the simplicio runtime/dev-cli's own state — checkpoints, events.jsonl, survey
+    artifacts — written by this very hook's fire-and-forget CLI callouts mid-turn, the same
+    self-inflicted false-positive class), and build/cache noise (`__pycache__`, `.pyc`) that this
+    very check's own module import can create — those false-positives are exactly why all three
+    are filtered here.
     """
     out = set()
     for args in (
@@ -344,7 +366,8 @@ def _changed_files():
             continue
     return {
         f for f in out
-        if not f.startswith(".orchestrator/") and "__pycache__" not in f and not f.endswith((".pyc", ".pyo"))
+        if not f.startswith((".orchestrator/", ".simplicio/"))
+        and "__pycache__" not in f and not f.endswith((".pyc", ".pyo"))
     }
 
 
@@ -518,6 +541,31 @@ def _call_simplicio_checkpoint(iteration):
         pass
 
 
+def _call_simplicio_hbp_append_topic(topic, payload_dict):
+    """Generic fail-open append into the runtime's HBP tamper-evident hash chain
+    (`simplicio hbp append`), when the native `simplicio` binary is on PATH (#128).
+
+    Same contract as the promise-verified append below: `simplicio`-only, best-effort — absent
+    binary or any failure is a silent no-op that never blocks the caller's own decision. Every
+    new HBP point in this hook family (stall detected, gate blocked, run blocked) goes through
+    here so the topics all carry the same provenance and failure discipline.
+    """
+    binary = shutil.which("simplicio")
+    if not binary:
+        return
+    try:
+        subprocess.run(
+            [binary, "hbp", "append",
+             "--topic", topic,
+             "--payload", json.dumps(payload_dict),
+             "--provenance", "simplicio-loop",
+             "--json"],
+            capture_output=True, timeout=15,
+        )
+    except Exception:
+        pass
+
+
 def _call_simplicio_hbp_append(iteration, promise, watcher_tag):
     """Record the promise-verification decision into the runtime's HBP
     tamper-evident hash chain (`simplicio hbp append`), when the native
@@ -531,29 +579,44 @@ def _call_simplicio_hbp_append(iteration, promise, watcher_tag):
     recorded in order, without trusting this process's own say-so after the
     fact. Absent binary or any failure: silent no-op, never blocks the stop.
     """
-    binary = shutil.which("simplicio")
-    if not binary:
-        return
     try:
         anchor = read_anchor() or {}
-        payload = json.dumps({
+        _call_simplicio_hbp_append_topic("loop-promise-verified", {
             "iteration": iteration,
             "promise": promise,
             "watcher_tag": watcher_tag,
             "goal_fp": anchor.get("goal_fp", ""),
         })
-        subprocess.run(
-            [binary, "hbp", "append",
-             "--topic", "loop-promise-verified",
-             "--payload", payload,
-             "--provenance", "simplicio-loop",
-             "--json"],
-            capture_output=True, timeout=15,
-        )
     except Exception:
         pass
 
 
+def _journal_stall(k=3):
+    """Trailing same-fingerprint failure streak from the journal — (fingerprint, streak).
+
+    Mirrors `scripts/loop_journal.py`'s `analyze()` trailing-streak math over the tail of the
+    journal, locally and fail-open (("", 0) on any error) — the hook must never import the
+    worker to decide whether to emit the `loop-stall-detected` HBP record (#128).
+    """
+    try:
+        rows = tail_journal(n=max(k * 3, 12))
+        if not rows:
+            return "", 0
+        last = rows[-1]
+        fp = last.get("fingerprint", "")
+        if last.get("gate") == "pass" or not fp:
+            return "", 0
+        streak = 0
+        for r in reversed(rows):
+            if r.get("gate") != "pass" and r.get("fingerprint") == fp:
+                streak += 1
+            else:
+                break
+        return fp, streak
+    except Exception:
+        return "", 0
+
+
 def read_watcher_challenge():
     """Return the current per-iteration watcher challenge dict, or None. Fail-open."""
     try:
@@ -635,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.
 
@@ -781,7 +908,11 @@ def main():
         # hand-survey/hand-edit.
         missing_ops = missing_bound_operators()
         if missing_ops:
-            write_handoff("bound operator missing: %s" % ", ".join(missing_ops), meta, body)
+            reason = "bound operator missing: %s" % ", ".join(missing_ops)
+            _call_simplicio_hbp_append_topic("loop-run-blocked", {
+                "fingerprint": _journal_stall()[0], "attempt": iteration, "reason": reason,
+            })
+            write_handoff(reason, meta, body)
             cleanup_and_stop()
 
         stdin = read_stdin_json()
@@ -792,6 +923,15 @@ def main():
         # this turn even if the agent forgot the manual `loop_journal.py record` call.
         auto_record_journal(iteration, has_evidence)
 
+        # HBP point: stall detected (#128) — when the trailing journal streak crosses the same
+        # K=3 threshold the stall detector/planner use, record it into the tamper-evident chain
+        # so a later `simplicio hbp verify` can prove WHEN the loop knew it was stuck. Fail-open.
+        stall_fp, stall_streak = _journal_stall()
+        if stall_streak >= 3:
+            _call_simplicio_hbp_append_topic("loop-stall-detected", {
+                "fingerprint": stall_fp, "attempt": iteration, "streak": stall_streak,
+            })
+
         # HRM-style hierarchical planner: re-assess phase on stall or every N iterations.
         # Runs BEFORE the promise gate so the phase context is available.
         _call_hierarchical_planner()
@@ -804,26 +944,37 @@ 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", {
+                "fingerprint": _journal_stall()[0], "attempt": iteration,
+                "reason": "max_iterations cap reached",
+            })
             write_handoff("max_iterations cap reached", meta, body)
             cleanup_and_stop()
         # (5) Spindle handoff — latched handoff overrides re-feed.