simplicio-loop 3.16.0__tar.gz → 3.20.0__tar.gz

{simplicio_loop-3.16.0/simplicio_loop.egg-info → simplicio_loop-3.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplicio-loop
-Version: 3.16.0
+Version: 3.20.0
 Summary: The Universal Looping AI Orchestrator — a runtime-agnostic super-plugin (6 skills) that drains any queue of work end-to-end on any LLM/runtime.
 Author-email: Wesley Simplicio <wesleybob4@gmail.com>
 License: MIT

{simplicio_loop-3.16.0 → simplicio_loop-3.20.0}/README.md

@@ -75,12 +75,23 @@ and keeps watching **24/7** for new work — all behind safety gates and a hard
 Three things make it different: it is a **super-plugin of focused skills**, it runs the **same
 protocol on 11 runtimes**, and it does all of this with **aggressive, honest token economy**.
 
+Within the Simplicio product line, this repo is also the **current reference task flow** for
+company work. `simplicio-runtime` is the unified entrypoint going forward, but it is expected to
+reuse this loop's evidence-gated converge/drain discipline, durable attempt journal, and worker
+coordination patterns instead of creating a separate task semantics.
+
 <p align="center">
   <img src="assets/simplicio-loop-infographic.png" alt="simplicio-loop — the whole system at a glance: 6 core skills, 5 satellites, 5 accelerators, 48 extension points, 11 runtimes, up to 90% fewer tokens" width="920" />
 </p>
 
 ---
 
+## 🤖 LLM front door
+
+If you are an agent/runtime entering this repo cold, read `llms.txt` first for the short operational contract, then `AGENTS.md`, then `.claude/skills/simplicio-tasks/SKILL.md`.
+
+---
+
 ## 📘 Official capability record
 
 The complete, official roster of what `simplicio-tasks` ships — every capability below is **real,
@@ -90,7 +101,7 @@ deep section and its worker.
 | Capability | What it does | Proof / worker | Details |
 |---|---|---|---|
 | 🎬 **Video evidence** (`video_evidence`) | Records the **real browser session** as moving proof a UI change works (Playwright, default); renders a **deterministic captioned MP4** with [hyperframes](https://github.com/heygen-com/hyperframes) for an explicit explainer request (`/simplicio-tasks make a video of screen X`) | `scripts/video_evidence.py` · BLOCKED (never fake-pass) without the toolchain | [§ Video evidence](#-video-evidence--playwright-by-default-hyperframes-on-request) |
-| 🧠 **Attempt memory + stall detector** | A durable run-journal (`.orchestrator/loop/journal.jsonl`) + a stall detector so the loop **changes strategy instead of oscillating**; incremental triage (`since`) reads only the delta each turn | `scripts/loop_journal.py` · `selftest` 9/9 | [§ Anti-oscillation](#-attempt-memory--stall-detector-anti-oscillation) |
+| 🧠 **Attempt memory + stall detector** | A durable run-journal (`.orchestrator/loop/journal.jsonl`) + a stall detector so the loop **changes strategy instead of oscillating**; incremental triage (`since`) reads only the delta each turn, and optional stage lineage makes retries/governance explicit | `scripts/loop_journal.py` · `selftest` 13/13 | [§ Anti-oscillation](#-attempt-memory--stall-detector-anti-oscillation) |
 | 🧭 **Repo conventions** (`repo_conventions`) | **Learns the repo's own playbook** — mines git history + merged PRs + static config into `.orchestrator/conventions.json` so every new branch/commit/PR mirrors the team's established style; worktree-per-item isolation is the default | `scripts/repo_conventions.py` · `selftest` 19/19 | [§ The full flow](#️-the-full-flow--from-demand-to-delivery) |
 | 🧩 **Scope reflection** (`dependency_graph`) | Maps local dependencies, reverse dependents, and related tests from the planned touched files; blocks task plans that ignore callers, sibling files, or proof points before the edit starts | `scripts/impact_audit.py` · `selftest` | [§ Tests & local checks](#-tests--local-checks-no-paid-ci) |
 | 🕸️ **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](#-tests--local-checks-no-paid-ci) |
@@ -280,7 +291,8 @@ Between turns, LMCache (when available) caches the KV state so re-feed costs nea
 
 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** (`.orchestrator/loop/journal.jsonl`, append-only:
-`iteration · action · hypothesis · gate · error-fingerprint`) and a **stall detector**
+`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`](scripts/loop_journal.py), deterministic + model-free):
 
 - **Error fingerprint** — the failing gate output is reduced to a stable hash with line numbers,
@@ -292,10 +304,15 @@ simplicio-loop keeps a **durable run-journal** (`.orchestrator/loop/journal.json
   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.
 
 ```bash
 loop_journal.py resume                       # what was tried + dead-ends to avoid
-loop_journal.py record --iteration N --action "…" --gate fail --gate-output test.log
+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
 ```
 

{simplicio_loop-3.16.0 → simplicio_loop-3.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simplicio-loop"
-version = "3.16.0"
+version = "3.20.0"
 description = "The Universal Looping AI Orchestrator — a runtime-agnostic super-plugin (6 skills) that drains any queue of work end-to-end on any LLM/runtime."
 readme = "PYPI.md"
 requires-python = ">=3.8"

{simplicio_loop-3.16.0 → simplicio_loop-3.20.0}/simplicio_loop/_bundle/hooks/loop_stop.py

@@ -21,12 +21,14 @@ the dead-end attempts. A successful (promise-fulfilled) stop needs no handoff.
 import json
 import os
 import re
+import subprocess
 import sys
 import time
 
 LOOP_DIR = os.path.join(".orchestrator", "loop")
 SCRATCHPAD = os.path.join(LOOP_DIR, "scratchpad.md")
-DONE_FLAG = os.path.join(LOOP_DIR, "done")
+DONE_FLAG = os.path.join(LOOP_DIR, "done.flag")
+LEGACY_DONE_FLAG = os.path.join(LOOP_DIR, "done")
 LAST_RESP = os.path.join(LOOP_DIR, "last_response.txt")
 ANCHOR = os.path.join(LOOP_DIR, "anchor.json")
 JOURNAL = os.path.join(LOOP_DIR, "journal.jsonl")
@@ -35,6 +37,9 @@ STOP_SIGNAL = os.path.join(".orchestrator", "STOP")
 BUDGET = os.path.join(".orchestrator", "loop-budget.json")
 GATE_LOCK = os.path.join(LOOP_DIR, "gate.lock")
 GATE_TTL_SEC = 1800  # 30 min — a stale lock must NEVER permanently trap the loop (fail-open)
+WATCHER_STATE = os.path.join(LOOP_DIR, "watcher_state.json")
+SPINDLE_STATE = os.path.join(LOOP_DIR, "spindle_state.json")
+PHASE_FILE = os.path.join(LOOP_DIR, "phase.json")
 
 EVIDENCE_RE = re.compile(
     r"(https?://\S+/pull/\d+)"          # a PR URL
@@ -52,7 +57,7 @@ def allow_stop():
 
 
 def cleanup_and_stop():
-    for p in (SCRATCHPAD, DONE_FLAG, LAST_RESP):
+    for p in (SCRATCHPAD, DONE_FLAG, LEGACY_DONE_FLAG, LAST_RESP, WATCHER_STATE):
         try:
             if os.path.exists(p):
                 os.remove(p)
@@ -176,6 +181,29 @@ def tail_journal(n=8):
         return []
 
 
+def attempt_suffix(a):
+    bits = []
+    if a.get("execution_state"):
+        bits.append("state=%s" % a["execution_state"])
+    if a.get("stage_id"):
+        bits.append("stage=%s" % a["stage_id"])
+    if a.get("decision"):
+        bits.append("decision=%s" % a["decision"])
+    if a.get("validator"):
+        bits.append("validator=%s" % a["validator"])
+    if a.get("retry_count") is not None:
+        bits.append("retry=%s" % a["retry_count"])
+    if a.get("chunk_id"):
+        bits.append("chunk=%s" % a["chunk_id"])
+    if a.get("source_artifact"):
+        bits.append("source=%s" % a["source_artifact"])
+    if a.get("next_action"):
+        bits.append("next=%s" % a["next_action"])
+    if a.get("blocked_reason"):
+        bits.append("blocked=%s" % a["blocked_reason"])
+    return (" — " + " | ".join(bits)) if bits else ""
+
+
 def write_handoff(reason, meta=None, body=None):
     """Write the cross-agent continuation artifact before an INCOMPLETE stop.
 
@@ -218,13 +246,14 @@ def write_handoff(reason, meta=None, body=None):
             lines += ["", "## Last attempts (`scripts/loop_journal.py resume` for the full read)"]
             for a in attempts:
                 lines.append(
-                    "- iter %s: %s -> %s (fp %s)%s"
+                    "- iter %s: %s -> %s (fp %s)%s%s"
                     % (
                         a.get("iteration", "?"),
                         a.get("action", "?"),
                         a.get("gate", "?"),
                         (a.get("fingerprint") or "")[:12],
                         (" — %s" % a["note"]) if a.get("note") else "",
+                        attempt_suffix(a),
                     )
                 )
         lines += [
@@ -241,6 +270,7 @@ def write_handoff(reason, meta=None, body=None):
         with open(tmp, "w", encoding="utf-8") as f:
             f.write("\n".join(lines))
         os.replace(tmp, HANDOFF)
+        refresh_cross_agent_wiki(include_handoff=True)
     except Exception:
         pass  # fail-open: a broken handoff write must never block the stop
 
@@ -260,6 +290,173 @@ def budget_halted():
         return False  # fail-open: budget unreadable ≠ trap
 
 
+def _discover_simplicio_cli():
+    """Probe for simplicio CLI in priority order. Returns (binary, sub) or (None, None).
+    Silent-fail: any probe error returns (None, None) — never blocks.
+    """
+    candidates = [
+        ("simplicio", "claims"),
+        ("simplicio-py", "claims"),
+        ("python3", ["-m", "simplicio.cli", "claims"]),
+    ]
+    for binary, sub in candidates:
+        try:
+            args = [binary] + (sub if isinstance(sub, list) else [sub, "--help"])
+            subprocess.run(args, capture_output=True, timeout=5)
+            return binary, sub
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            continue
+    return None, None
+
+
+def _call_simplicio_claims():
+    """Run ``simplicio claims check`` silently. Fail-open."""
+    binary, _ = _discover_simplicio_cli()
+    if not binary:
+        return
+    try:
+        subprocess.run(
+            [binary, "claims", "check"],
+            capture_output=True, timeout=15,
+        )
+    except Exception:
+        pass
+
+
+def _call_simplicio_nest():
+    """Run ``simplicio nest verify`` silently. Fail-open."""
+    candidates = [
+        ("simplicio", "nest"),
+        ("simplicio-py", "nest"),
+        ("python3", ["-m", "simplicio.cli", "nest"]),
+    ]
+    for binary, sub in candidates:
+        try:
+            args = [binary] + (sub if isinstance(sub, list) else [sub, "--help"])
+            subprocess.run(args, capture_output=True, timeout=5)
+            nest_binary = binary
+            try:
+                subprocess.run(
+                    [nest_binary, "nest", "verify"],
+                    capture_output=True, timeout=15,
+                )
+            except Exception:
+                pass
+            return
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            continue
+
+
+def watcher_verify():
+    """Run pre-promise watcher verification per Asolaria N-Nest Corrective Gate pattern.
+
+    Reads `.orchestrator/loop/watcher_state.json` written by the watcher process (a separate
+    agent/PID that independently re-executes the work and compares results against the agent's
+    reported output). Gate: `reported == watcher.recomputed_truth`.
+
+    Returns (passed: bool, tag: str) where tag is "MEASURED" (verified) or "UNVERIFIED" (not
+    verified or mismatch). If no watcher state exists → UNVERIFIED (gate fails). Fail-open:
+    a corrupt or missing watcher state NEVER traps the loop — it simply gates the promise.
+    """
+    try:
+        if not os.path.exists(WATCHER_STATE):
+            return False, "UNVERIFIED"
+        with open(WATCHER_STATE, encoding="utf-8") as f:
+            state = json.load(f)
+        match = bool(state.get("match", False))
+        status = str(state.get("status", "UNVERIFIED"))
+        if match and status == "MEASURED":
+            return True, "MEASURED"
+        return False, "UNVERIFIED"
+    except Exception:
+        return False, "UNVERIFIED"
+
+
+def spindle_latched():
+    """True when a spindle handoff exists with an unreleased latch.
+
+    A latched handoff means agent A handed off to agent B and is waiting for B to
+    confirm receipt. When latched, the loop must NOT re-feed the goal — the handoff
+    target will pick up. Fail-open: unreadable/missing file → False (never trap).
+    """
+    try:
+        if not os.path.exists(SPINDLE_STATE):
+            return False
+        with open(SPINDLE_STATE, encoding="utf-8") as f:
+            s = json.load(f)
+        return bool(s.get("latch", False))
+    except Exception:
+        return False
+
+
+def spindle_active():
+    """True when a spindle handoff exists and IS confirmed (current agent is processing).
+
+    An active (confirmed) handoff means the receiving agent confirmed receipt and is
+    working. The loop can continue normally for this agent. Fail-open: unreadable/missing
+    file → False (never trap).
+    """
+    try:
+        if not os.path.exists(SPINDLE_STATE):
+            return False
+        with open(SPINDLE_STATE, encoding="utf-8") as f:
+            s = json.load(f)
+        return bool(s.get("current_agent")) and not bool(s.get("latch", False))
+    except Exception:
+        return False
+
+
+def read_phase():
+    """Read the current hierarchical phase, if any. Fail-open."""
+    try:
+        if not os.path.exists(PHASE_FILE):
+            return None
+        with open(PHASE_FILE, encoding="utf-8") as f:
+            phase = json.load(f)
+        return phase if isinstance(phase, dict) else None
+    except Exception:
+        return None
+
+
+def _call_cross_agent_wiki(command):
+    """Capture/refresh the shared wiki used for cross-agent continuity. Fail-open."""
+    try:
+        repo_root = os.getcwd()
+        script = os.path.join(repo_root, "scripts", "cross_agent_wiki.py")
+        if not os.path.exists(script):
+            return
+        subprocess.run(
+            [sys.executable, script, command],
+            capture_output=True, timeout=15,
+            cwd=repo_root,
+        )
+    except Exception:
+        pass
+
+
+def refresh_cross_agent_wiki(include_handoff=False):
+    """Best-effort wiki maintenance at loop boundaries. Fail-open."""
+    _call_cross_agent_wiki("capture")
+    _call_cross_agent_wiki("summary")
+    if include_handoff:
+        _call_cross_agent_wiki("handoff")
+
+
+def phase_header_hint():
+    """Render a short phase hint for the next iteration header. Empty when flat."""
+    phase = read_phase()
+    if not phase:
+        return ""
+    bits = [" phase=%s" % phase.get("phase", "?")]
+    strategy = str(phase.get("strategy", "")).strip()
+    guard = str(phase.get("tactical_guard", "")).strip()
+    if strategy:
+        bits.append(" strategy=%s" % strategy[:120])
+    if guard:
+        bits.append(" guard=%s" % guard[:120])
+    return "".join(bits)
+
+
 def emit_refeed(followup):
     """Emit the re-feed in BOTH schemas; each runtime reads its own key."""
     out = {
@@ -281,6 +478,13 @@ def main():
             except OSError:
                 meta, body = None, None
 
+        # Fire-and-forget simplicio CLI callout: verify claims and nest tree.
+        # Disabled when no scratchpad exists (no active loop). Silent failure
+        # if the CLI is not installed — the loop proceeds either way.
+        if os.path.exists(SCRATCHPAD):
+            _call_simplicio_claims()
+            _call_simplicio_nest()
+
         # Explicit STOP signal beats everything — but still hand off if there was live state.
         if os.path.exists(STOP_SIGNAL):
             if meta is not None:
@@ -309,19 +513,31 @@ def main():
         stdin = read_stdin_json()
         resp = last_assistant_text(stdin)
 
+        # 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()
+
+        # Pre-promise: watcher-gate — independent verification before any promise is honored.
+        # Per Asolaria N-Nest Corrective Gate: each agent PID has a watcher PID that
+        # independently re-computes the truth. Gate: reported == watcher.recomputed_truth.
+        watcher_pass, watcher_tag = watcher_verify()
+
         # Completion detection (capture folded in for single-hook runtimes like Claude).
         if promise and resp:
             m = PROMISE_RE.search(resp)
             if m and m.group(1).strip() == promise.strip():
                 has_evidence = bool(EVIDENCE_RE.search(resp))
-                # The promise is honored only with evidence AND no acceptance criterion still open
-                # in the task anchor — the mechanical anti-drift gate. Pending ACs ⇒ ignore the
-                # promise and keep looping (still bounded by max_iter), never a false "done".
-                if ((not evidence_required) or has_evidence) and not anchor_pending():
+                # The promise is honored only with evidence AND watcher verification AND no
+                # acceptance criterion still open in the task anchor. 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():
+                    refresh_cross_agent_wiki(include_handoff=False)
                     cleanup_and_stop()  # (3) promise fulfilled → stop, no handoff needed
-                # promise without evidence, or anchor still has open ACs → ignore, keep looping
+                # promise without evidence, or watcher disagrees, or anchor still has open ACs
+                # → ignore, keep looping
         # (3') Cursor capture may have raised the flag.
-        if os.path.exists(DONE_FLAG):
+        if os.path.exists(DONE_FLAG) or os.path.exists(LEGACY_DONE_FLAG):
             cleanup_and_stop()
         # (4) Iteration cap — incomplete stop, hand off.
         if max_iter > 0 and iteration >= max_iter:
@@ -332,6 +548,17 @@ def main():
         if budget_halted():
             write_handoff("budget halted", meta, body)
             cleanup_and_stop()
+        # (5b) Spindle handoff — latched handoff overrides re-feed.
+        if spindle_latched():
+            next_agent = "?"
+            try:
+                with open(SPINDLE_STATE, encoding="utf-8") as _f:
+                    _s = json.load(_f)
+                    next_agent = _s.get("next_agent", "?")
+            except Exception:
+                pass
+            write_handoff("spindle handoff (latched — waiting for '%s')" % next_agent, meta, body)
+            cleanup_and_stop()
         # (6) Continue: bump iteration in place, re-feed the goal body.
         nxt = iteration + 1
         with open(SCRATCHPAD, encoding="utf-8") as f:
@@ -361,11 +588,38 @@ def main():
             if pending
             else ""
         )
-        header = "[simplicio-loop iteration %d.%s%s]" % (nxt, promise_hint, ac_hint)
+        header = "[simplicio-loop iteration %d.%s%s%s %s]" % (
+            nxt, promise_hint, ac_hint, phase_header_hint(), watcher_tag
+        )
+        refresh_cross_agent_wiki(include_handoff=False)
         emit_refeed(header + "\n\n" + (body or ""))
     except Exception:
         allow_stop()  # fail-open, always
 
 
+def _call_hierarchical_planner():
+    """Run the HRM-style hierarchical planner if a scratchpad exists. Fail-open.
+
+    The planner reads the journal and current phase, then MAY write a new phase
+    (`.orchestrator/loop/phase.json`) on stall detection or every N iterations.
+    The phase context is consumed by the re-feed header or the loop's decision logic.
+    Fail-open: any error here must never trap the loop; the loop runs in flat mode
+    if the planner is missing or broken.
+    """
+    try:
+        if os.path.exists(SCRATCHPAD):
+            repo_root = os.getcwd()
+            script = os.path.join(repo_root, "scripts", "hierarchical_planner.py")
+            if not os.path.exists(script):
+                return
+            subprocess.run(
+                [sys.executable, script, "plan"],
+                capture_output=True, timeout=15,
+                cwd=repo_root,
+            )
+    except Exception:
+        pass  # fail-open
+
+
 if __name__ == "__main__":
     main()