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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplicio-loop
-Version: 3.20.0
+Version: 3.21.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
@@ -19,8 +19,8 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: simplicio-mapper>=0.11.0
-Requires-Dist: simplicio-cli>=0.7.1
+Requires-Dist: simplicio-mapper>=0.14.0
+Requires-Dist: simplicio-cli>=0.9.1
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Provides-Extra: ml

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

@@ -6,7 +6,7 @@
 
 <p align="center">
   <a href="https://github.com/wesleysimplicio/simplicio-loop/stargazers"><img src="https://img.shields.io/github/stars/wesleysimplicio/simplicio-loop?style=social" alt="Stars"></a>
-  <a href="#-the-11-skills--accelerators"><img src="https://img.shields.io/badge/skills-11-7C3AED" alt="11 skills"></a>
+  <a href="#-the-6-skills--5-accelerators"><img src="https://img.shields.io/badge/skills-6-7C3AED" alt="6 skills"></a>
   <a href="#-source-adapters"><img src="https://img.shields.io/badge/source%20adapters-5-00E08A" alt="5 source adapters"></a>
   <a href="#-11-runtimes-one-protocol"><img src="https://img.shields.io/badge/runtimes-11-2563EB" alt="11 runtimes"></a>
   <a href="#-the-48-extension-points"><img src="https://img.shields.io/badge/extension%20points-48-00E08A" alt="48 extension points"></a>
@@ -17,7 +17,7 @@
 
 <p align="center">
   <a href="#-tldr">TL;DR</a> ·
-  <a href="#-the-11-skills--accelerators">11 Skills</a> ·
+  <a href="#-the-6-skills--5-accelerators">6 Skills</a> ·
   <a href="#-source-adapters">Source Adapters</a> ·
   <a href="#-11-runtimes-one-protocol">11 Runtimes</a> ·
   <a href="#-the-loop">The Loop</a> ·
@@ -120,7 +120,7 @@ re-query stays empty K rounds). Both still obey the universal exits (promise+evi
 
 ---
 
-## 🧠 The 11 skills & accelerators
+## 🧠 The 6 skills + 5 accelerators
 
 The orchestrator core + five satellites + five accelerators/integrations. Each satellite is
 **optional** — when loaded, the orchestrator delegates to it (richer + cheaper); when absent, the

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simplicio-loop"
-version = "3.20.0"
+version = "3.21.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"
@@ -25,8 +25,8 @@ classifiers = [
 #   simplicio-mapper -> the repo-survey step (binds `orient`)
 #   simplicio-cli    -> the operator that applies+verifies changes (binds `execute`/`deterministic_edit`)
 dependencies = [
-  "simplicio-mapper>=0.11.0",
-  "simplicio-cli>=0.7.1",
+  "simplicio-mapper>=0.14.0",
+  "simplicio-cli>=0.9.1",
 ]
 
 # Optional: the real embedding backend for `simplicio-cli semantic --ml` / `simplicio-cli rag --ml`.

{simplicio_loop-3.20.0 → simplicio_loop-3.21.0}/simplicio_loop/_bundle/hooks/README.md

@@ -15,7 +15,6 @@ not a pass. It still lets every benign command through, so it never bricks norma
 | `action_gate.py` | safety: **fail-closed** — block irreversible ops + secret-laden commits/pushes BEFORE they run | `PreToolUse` (Bash) / git pre-push |
 | `orient_clamp.py` | simplicio-orient: **wrapper** — run a command, return reduced output + tee-on-failure | called directly, any runtime |
 | `orient_rewrite.py` | simplicio-orient: auto-route heavy read-only commands through the clamp (opt-in) | `PreToolUse` |
-| `learn_stop.py` | simplicio-learn: queue the finished run for a retrospective | `stop` / `SubagentStop` |
 
 ## The safety gate (`action_gate.py`)
 
@@ -65,8 +64,7 @@ Add (paths relative to the repo root, or absolute):
   "hooks": {
     "Stop": [
       { "hooks": [
-        { "type": "command", "command": "python3 ./hooks/loop_stop.py" },
-        { "type": "command", "command": "python3 ./hooks/learn_stop.py" }
+        { "type": "command", "command": "python3 ./hooks/loop_stop.py" }
       ] }
     ],
     "PreToolUse": [

{simplicio_loop-3.20.0 → simplicio_loop-3.21.0}/simplicio_loop/_bundle/hooks/hooks.claude.json

@@ -3,8 +3,7 @@
     "Stop": [
       {
         "hooks": [
-          { "type": "command", "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/loop_stop.py\"" },
-          { "type": "command", "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/learn_stop.py\"" }
+          { "type": "command", "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/loop_stop.py\"" }
         ]
       }
     ],

{simplicio_loop-3.20.0 → simplicio_loop-3.21.0}/simplicio_loop/_bundle/hooks/hooks.json

@@ -5,8 +5,7 @@
       { "command": "python3 ./hooks/loop_capture.py" }
     ],
     "stop": [
-      { "command": "python3 ./hooks/loop_stop.py", "loop_limit": null },
-      { "command": "python3 ./hooks/learn_stop.py" }
+      { "command": "python3 ./hooks/loop_stop.py", "loop_limit": null }
     ]
   }
 }

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

@@ -21,9 +21,11 @@ the dead-end attempts. A successful (promise-fulfilled) stop needs no handoff.
 import json
 import os
 import re
+import shutil
 import subprocess
 import sys
 import time
+import uuid
 
 LOOP_DIR = os.path.join(".orchestrator", "loop")
 SCRATCHPAD = os.path.join(LOOP_DIR, "scratchpad.md")
@@ -38,8 +40,13 @@ 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")
+WATCHER_CHALLENGE = os.path.join(LOOP_DIR, "watcher_challenge.json")
 SPINDLE_STATE = os.path.join(LOOP_DIR, "spindle_state.json")
 PHASE_FILE = os.path.join(LOOP_DIR, "phase.json")
+FLOW_AUDIT_RECEIPT = os.path.join(".orchestrator", "flow-audit.json")
+SIMPLICIO_LOOP_SKILL_MARKER = os.path.join(".claude", "skills", "simplicio-loop", "SKILL.md")
+BOUND_OPERATORS = ("simplicio-mapper", "simplicio-dev-cli")
+WEB_EXTS = {".tsx", ".jsx", ".vue", ".svelte", ".html"}
 
 EVIDENCE_RE = re.compile(
     r"(https?://\S+/pull/\d+)"          # a PR URL
@@ -57,7 +64,7 @@ def allow_stop():
 
 
 def cleanup_and_stop():
-    for p in (SCRATCHPAD, DONE_FLAG, LEGACY_DONE_FLAG, LAST_RESP, WATCHER_STATE):
+    for p in (SCRATCHPAD, DONE_FLAG, LEGACY_DONE_FLAG, LAST_RESP, WATCHER_STATE, WATCHER_CHALLENGE):
         try:
             if os.path.exists(p):
                 os.remove(p)
@@ -270,7 +277,12 @@ 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)
+        # include_handoff=False: this function just wrote the RICH handoff (frozen goal + AC
+        # checklist + last attempts) directly above. cross_agent_wiki.py's own `handoff` command
+        # writes the SAME path with a thinner layout — calling it here would immediately clobber
+        # what we just wrote (the three-writer bug, #68). Only capture + summary run; HANDOFF.md
+        # keeps a single owner for an INCOMPLETE stop.
+        refresh_cross_agent_wiki(include_handoff=False)
     except Exception:
         pass  # fail-open: a broken handoff write must never block the stop
 
@@ -290,6 +302,160 @@ def budget_halted():
         return False  # fail-open: budget unreadable ≠ trap
 
 
+def missing_bound_operators():
+    """Return the bound-operator binaries missing from PATH, or [] if not applicable.
+
+    CLAUDE.md / `simplicio-loop` SKILL.md: when a body-of-work loop is driven by the
+    `simplicio-loop` companion skill, `simplicio-mapper` (survey) and `simplicio-dev-cli`
+    (operate) are REQUIRED — "the loop BLOCKS if either is absent". That contract was previously
+    enforced only at install/doctor time (#83); the running driver never checked it, so a
+    marketplace install, a PATH mismatch, or an operator uninstalled after setup silently
+    degraded to LLM hand-survey/hand-edit — exactly what the operators exist to prevent.
+
+    Scoped to repos that actually ship the `simplicio-loop` skill (its SKILL.md is the marker) —
+    a bare `simplicio-tasks` loop with no `simplicio-loop` companion has no operator requirement.
+    Fail-open: any probe error is treated as "present" (never trap the loop over a probe bug).
+    """
+    try:
+        if not os.path.exists(SIMPLICIO_LOOP_SKILL_MARKER):
+            return []
+        return [b for b in BOUND_OPERATORS if shutil.which(b) is None]
+    except Exception:
+        return []
+
+
+def _flow_audit_module():
+    """Best-effort import of scripts/flow_audit.py for its FRONT_HINTS/BACK_HINTS. None on failure."""
+    try:
+        repo_root = os.getcwd()
+        scripts_dir = os.path.join(repo_root, "scripts")
+        if scripts_dir not in sys.path:
+            sys.path.insert(0, scripts_dir)
+        import flow_audit as _fa  # noqa: local import, optional dependency
+        return _fa
+    except Exception:
+        return None
+
+
+def _changed_files():
+    """Best-effort set of files touched in the working tree (uncommitted + untracked + last
+    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.
+    """
+    out = set()
+    for args in (
+        ["git", "diff", "--name-only", "HEAD"],
+        ["git", "diff", "--name-only", "HEAD~1", "HEAD"],
+        ["git", "ls-files", "--others", "--exclude-standard"],
+    ):
+        try:
+            r = subprocess.run(args, capture_output=True, text=True, timeout=10)
+            if r.returncode == 0:
+                out.update(ln.strip() for ln in r.stdout.splitlines() if ln.strip())
+        except Exception:
+            continue
+    return {
+        f for f in out
+        if not f.startswith(".orchestrator/") and "__pycache__" not in f and not f.endswith((".pyc", ".pyo"))
+    }
+
+
+def _touches_web_surface(files):
+    fa = _flow_audit_module()
+    front = tuple(getattr(fa, "FRONT_HINTS", ()) or ())
+    back = tuple(getattr(fa, "BACK_HINTS", ()) or ())
+    for f in files:
+        ext = os.path.splitext(f)[1].lower()
+        if ext in WEB_EXTS:
+            return True
+        fl = "/" + f.replace(os.sep, "/").lower()
+        if any(h in fl for h in front) or any(h in fl for h in back):
+            return True
+    return False
+
+
+def flow_audit_gap():
+    """Return a human-readable gap string when a web-touching diff lacks a fresh, passing
+    `.orchestrator/flow-audit.json` receipt; None when there is nothing to require (#80).
+
+    Mechanizes what was previously prose-only (SKILL.md instructions the agent could skip under
+    context pressure): the anchor gate, watcher gate, cap, and budget are all enforced IN this
+    hook — the front→back integration gate now is too. Fail-open only when `flow_audit.py` itself
+    is absent (a bare `simplicio-tasks` repo with no flow_audit worker) or the diff/receipt can't
+    be read — never trap the loop over an audit-plumbing error.
+    """
+    try:
+        fa = _flow_audit_module()
+        if fa is None:
+            return None
+        files = _changed_files()
+        if not _touches_web_surface(files):
+            return None
+        if not os.path.exists(FLOW_AUDIT_RECEIPT):
+            return ("flow audit missing — run `python3 scripts/flow_audit.py audit . "
+                     "--fail-on high --json > .orchestrator/flow-audit.json`")
+        receipt_mtime = os.path.getmtime(FLOW_AUDIT_RECEIPT)
+        for f in files:
+            try:
+                if os.path.getmtime(f) > receipt_mtime:
+                    return ("flow audit stale — re-run `python3 scripts/flow_audit.py audit . "
+                             "--fail-on high --json > .orchestrator/flow-audit.json`")
+            except OSError:
+                continue
+        with open(FLOW_AUDIT_RECEIPT, encoding="utf-8") as f:
+            receipt = json.load(f)
+        if not receipt.get("ok", False):
+            high = receipt.get("counts", {}).get("high_issues", "?")
+            return "flow audit failing (%s high issue(s)) — fix and re-run flow_audit.py" % high
+        return None
+    except Exception:
+        return None  # fail-open: a broken audit read must never trap the loop
+
+
+def auto_record_journal(iteration, has_evidence):
+    """Fallback journal record so the hierarchical planner is never blind (#67).
+
+    `scripts/hierarchical_planner.py` derives `iterations_run` from
+    `.orchestrator/loop/journal.jsonl` — but nothing auto-writes that file; only the manual
+    `loop_journal.py record` call (SKILL.md Step 4) does. An agent that forgets it leaves the
+    planner permanently frozen at "no history". This writes a minimal fallback record for THIS
+    iteration if — and only if — the agent hasn't already recorded one itself this turn (checked
+    by inspecting the last row), so a rich manual record is never overwritten or double-counted.
+    Gate is intentionally "blocked", never "fail": this is a presence signal for phase timing, not
+    a substitute for the real attempt-memory the agent records on a genuine failure. Fail-open.
+    """
+    try:
+        if os.path.exists(JOURNAL):
+            with open(JOURNAL, encoding="utf-8") as f:
+                lines = [ln for ln in f if ln.strip()]
+            if lines:
+                try:
+                    last = json.loads(lines[-1])
+                    if int(last.get("iteration", -1)) == iteration:
+                        return  # agent already recorded this turn manually
+                except Exception:
+                    pass
+        repo_root = os.getcwd()
+        script = os.path.join(repo_root, "scripts", "loop_journal.py")
+        if not os.path.exists(script):
+            return
+        gate = "pass" if has_evidence else "blocked"
+        subprocess.run(
+            [sys.executable, script, "record",
+             "--iteration", str(iteration),
+             "--action", "auto: turn %d (no manual loop_journal record)" % iteration,
+             "--gate", gate,
+             "--note", "auto-recorded fallback"],
+            capture_output=True, timeout=10, cwd=repo_root,
+        )
+    except Exception:
+        pass
+
+
 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.
@@ -347,6 +513,44 @@ def _call_simplicio_nest():
             continue
 
 
+def read_watcher_challenge():
+    """Return the current per-iteration watcher challenge dict, or None. Fail-open."""
+    try:
+        with open(WATCHER_CHALLENGE, encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+
+def write_watcher_challenge(iteration):
+    """Issue a fresh per-iteration nonce the watcher receipt must echo (#82 challenge binding).
+
+    Written at the END of a turn that re-feeds (so it is on disk BEFORE the next turn's agent
+    acts, letting `scripts/watcher_verify.py` — run mid-turn, before the Stop hook fires — read
+    and echo it). A promise turn's receipt is checked against whatever challenge is on disk when
+    THIS Stop hook runs; a receipt that predates the challenge, or answers a different one, fails
+    the gate. This is what makes the watcher gate more than a plain unauthenticated JSON write:
+    the agent would have to notice, read, and correctly echo a value it does not control the
+    timing of — a visible, journaled action, not a silent one-call spoof. Fail-open: any write
+    error must never block the re-feed itself.
+    """
+    try:
+        anchor = read_anchor() or {}
+        os.makedirs(LOOP_DIR, exist_ok=True)
+        payload = {
+            "challenge": uuid.uuid4().hex[:20],
+            "iteration": iteration,
+            "goal_fp": anchor.get("goal_fp", ""),
+            "written_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        }
+        tmp = WATCHER_CHALLENGE + ".tmp"
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(payload, f)
+        os.replace(tmp, WATCHER_CHALLENGE)
+    except Exception:
+        pass
+
+
 def watcher_verify():
     """Run pre-promise watcher verification per Asolaria N-Nest Corrective Gate pattern.
 
@@ -354,6 +558,12 @@ def watcher_verify():
     agent/PID that independently re-executes the work and compares results against the agent's
     reported output). Gate: `reported == watcher.recomputed_truth`.
 
+    Challenge binding (#82): a receipt must additionally echo the CURRENT per-iteration
+    `watcher_challenge.json` nonce (and the frozen anchor's `goal_fp`, when an anchor exists) —
+    otherwise it is rejected even if `match: true`. This closes the plain self-attestation gap: a
+    receipt hand-written once at iteration 1 (or copied from a stale run) can no longer satisfy the
+    gate on a later, different iteration/goal.
+
     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.
@@ -365,9 +575,21 @@ def watcher_verify():
             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"
+        if not (match and status == "MEASURED"):
+            return False, "UNVERIFIED"
+        challenge = read_watcher_challenge()
+        if not challenge:
+            return False, "UNVERIFIED"  # no challenge on disk — nothing valid to echo yet
+        if state.get("challenge") != challenge.get("challenge"):
+            return False, "UNVERIFIED"
+        expected_fp = challenge.get("goal_fp") or ""
+        if expected_fp and state.get("goal_fp") != expected_fp:
+            return False, "UNVERIFIED"
+        checked_at = state.get("checked_at") or ""
+        written_at = challenge.get("written_at") or ""
+        if checked_at and written_at and checked_at < written_at:
+            return False, "UNVERIFIED"  # receipt predates the challenge it claims to answer
+        return True, "MEASURED"
     except Exception:
         return False, "UNVERIFIED"
 
@@ -510,8 +732,23 @@ def main():
         promise = None if promise in (None, "null", "") else promise
         evidence_required = str(meta.get("evidence_required", "true")).lower() != "false"
 
+        # (2b) Bound operators required (#83) — when this repo ships the simplicio-loop
+        # companion skill, `simplicio-mapper`/`simplicio-dev-cli` are hard deps of the running
+        # loop, not just the installer. A genuine BLOCK (handoff + stop), mirroring the cap and
+        # budget gates, so a marketplace install / PATH gap can never silently degrade to LLM
+        # hand-survey/hand-edit.
+        missing_ops = missing_bound_operators()
+        if missing_ops:
+            write_handoff("bound operator missing: %s" % ", ".join(missing_ops), meta, body)
+            cleanup_and_stop()
+
         stdin = read_stdin_json()
         resp = last_assistant_text(stdin)
+        has_evidence = bool(resp and EVIDENCE_RE.search(resp))
+
+        # Fallback attempt-memory record (#67) so the hierarchical planner is never blind to
+        # this turn even if the agent forgot the manual `loop_journal.py record` call.
+        auto_record_journal(iteration, has_evidence)
 
         # HRM-style hierarchical planner: re-assess phase on stall or every N iterations.
         # Runs BEFORE the promise gate so the phase context is available.
@@ -522,20 +759,23 @@ def main():
         # independently re-computes the truth. Gate: reported == watcher.recomputed_truth.
         watcher_pass, watcher_tag = watcher_verify()
 
+        # 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).
         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 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():
+                # 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):
                     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
-                # → ignore, keep looping
+                # promise without evidence, or watcher disagrees, or anchor still has open ACs,
+                # or a flow-audit gap remains → ignore, keep looping
         # (3') Cursor capture may have raised the flag.
         if os.path.exists(DONE_FLAG) or os.path.exists(LEGACY_DONE_FLAG):
             cleanup_and_stop()
@@ -588,9 +828,14 @@ def main():
             if pending
             else ""
         )
-        header = "[simplicio-loop iteration %d.%s%s%s %s]" % (
-            nxt, promise_hint, ac_hint, phase_header_hint(), watcher_tag
+        flow_hint = " Flow-audit gap: %s." % flow_gap if flow_gap else ""
+        header = "[simplicio-loop iteration %d.%s%s%s%s %s]" % (
+            nxt, promise_hint, ac_hint, flow_hint, phase_header_hint(), watcher_tag
         )
+        # Issue the NEXT iteration's watcher challenge before re-feeding (#82) — must be on disk
+        # before the next turn's agent acts, so a mid-turn `watcher_verify.py` run can read and
+        # echo it.
+        write_watcher_challenge(nxt)
         refresh_cross_agent_wiki(include_handoff=False)
         emit_refeed(header + "\n\n" + (body or ""))
     except Exception:

{simplicio_loop-3.20.0 → simplicio_loop-3.21.0}/simplicio_loop/_bundle/scripts/cross_agent_wiki.py

@@ -126,7 +126,8 @@ def _read_watcher_state():
     except FileNotFoundError:
         return {
             "state": "missing",
-            "line": "UNVERIFIED|watcher: no receipt (.orchestrator/loop/watcher_state.json missing)",
+            "line": "UNVERIFIED|watcher: no receipt (producer: `python3 scripts/watcher_verify.py "
+                    "verify` — not yet run this turn, or the challenge hasn't been issued yet)",
         }
     except (OSError, json.JSONDecodeError):
         return {

{simplicio_loop-3.20.0 → simplicio_loop-3.21.0}/simplicio_loop/_bundle/skills/simplicio-loop/SKILL.md

@@ -49,7 +49,7 @@ hard dependencies of the `simplicio-loop` package (`pip install simplicio-loop`
 
 | 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. This survey, not an ad-hoc LLM read, is what feeds the goal each turn. |
+| **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
@@ -81,6 +81,38 @@ long runs) remains the synchronous full (re)build of `.simplicio/`. Read the sur
 never re-scan the tree by hand when a fresh map exists. For a multi-repo survey, run the mapper per
 repo root and aggregate the JSON.
 
+**Survey evidence gate + context-pack (v0.13+).** Before trusting the deep artifacts, gate on
+`simplicio-mapper inspect . --json [--await]` (`simplicio.map-inspection/v1`): it reports, per
+artifact (project-map, precedent-index, symbol-index, call-graph, index-state, map-job,
+context-cache), whether the file **exists on disk** with size + mtime, plus `warnings`. An artifact
+the inspection says is missing must be treated as absent — re-run `scan`/`index`, don't guess its
+content. This is the same evidence-not-claims discipline the promise gate applies, applied to the
+survey itself. Then feed the goal from `simplicio-mapper handoff . --json [--await]`
+(`simplicio.map-handoff/v1`): its `context_pack` carries the relevant files with symbols, imports,
+dependencies, `recent_changes` and a `pack_hash` — a pre-compressed orientation bundle that
+substitutes for re-reading the tree (token economy: pack first, raw `Read` only for the few files
+the pack points at). Honor `context_pack.llm_directives` (no-think / no-internet / minimal tools)
+for the mechanical steps, and use `needs_broader_context` as the signal that the pack alone is not
+enough.
+
+**Structured queries + docs gates (v0.14+).** For triage questions the map alone doesn't answer,
+query the built artifacts instead of grepping the tree:
+`simplicio-mapper ask . <callers|callees|reaches|impact|flows|rules|tests-for|term> <arg> --json`
+(`simplicio.ask/v1`) — e.g. `ask . impact src/api.py` before an edit (which flows/dependents does
+this touch — feeds the `dependency_graph` widening), `ask . tests-for <symbol>` to pick the
+affected tests to run, `ask . callers <symbol>` during review. Two mechanical verify-side gates
+join the DoD pass: `simplicio-mapper sync . --check --json` (`simplicio.docs-sync/v1`) reports
+generated docs now stale relative to the diff, and `simplicio-mapper drift . --check --json`
+(`simplicio.spec-drift/v1`) reports spec↔code drift (orphan spec refs, unresolved placeholders,
+stale docs) — surface their findings in the turn report; they BLOCK only when the task's own AC is
+documentation. For an explicit docs/onboarding task, the producers are `flows` (end-to-end flow
+inventory), `survey` (new-developer onboarding report), `business` (observable business rules +
+glossary), and `history`/`diff` (architecture snapshots + semantic deltas).
+
+If the installed mapper predates 0.13 (`inspect`/`handoff` absent from `--help`), the
+preflight auto-update already pulls a current build; offline, fall back to `status` + reading
+`.simplicio/*.json` directly — the gate is then the file-existence check you do by hand.
+
 **Operate step (every turn that mutates code).** Once the AC and the change are DECIDED, delegate
 the mutation to the operator, one decided change at a time:
 ```bash
@@ -97,8 +129,9 @@ 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 |
-| 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 |
-| Loop contract step 2 — Triage (every turn) | mapper | re-read `.simplicio/*.json`; `simplicio-mapper macro . --json` for an instant skeleton, or `scan`/`status` to refresh if the tree changed |
+| 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 . --json` (context-pack) |
+| Loop contract step 2 — Triage (every turn) | mapper | `simplicio-mapper handoff . --json` → 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 |
 | Loop contract step 3 — Work the goal | dev-cli | `simplicio-dev-cli task "<decided change>" --target <file> [--json]` |
 | Evidence-gated `<promise>` / `simplicio-tasks` Step 4b | dev-cli | the operator's passing test+verify pass = in-turn evidence |
 
@@ -190,11 +223,17 @@ detector below. It is the difference between a loop that converges and one that
    AC-scoped change; the **`simplicio-dev-cli` operator APPLIES and verifies it**
    (`simplicio-dev-cli task "<change>" --target <file>`) — do not hand-edit inside the loop. End EVERY
    iteration with a short, concrete verification — the operator's passing test run, or one gate /
-   command / `file:line` receipt. **After the operator passes, the watcher-gate re-runs
-   independently** — a separate agent/PID re-executes the work and writes
-   `.orchestrator/loop/watcher_state.json` with `{"match": true, "status": "MEASURED"}` only when
-   `reported == watcher.recomputed_truth`. A `match: false` or missing watcher state is treated as
-   `UNVERIFIED` and gates the promise. If the actual edit surface expands, rerun `impact_audit.py` with
+   command / `file:line` receipt. **After the operator passes, run the watcher producer**:
+   `python3 scripts/watcher_verify.py verify` — it reads the per-iteration challenge the stop-hook
+   issued (`.orchestrator/loop/watcher_challenge.json`) and independently recomputes the frozen
+   anchor's done/pending state from disk (never trusting anything asserted in-context), then
+   writes `.orchestrator/loop/watcher_state.json` with `{"match": true, "status": "MEASURED",
+   "challenge": ..., "goal_fp": ...}` only when `reported == watcher.recomputed_truth` AND the
+   receipt echoes the current challenge. **Never hand-write `watcher_state.json` directly** — a
+   hand-written receipt cannot know the current challenge and will be rejected by the gate; this is
+   the mechanical fix for the plain-unauthenticated-JSON self-attestation gap. A `match: false`,
+   missing, or unchallenged watcher state is treated as `UNVERIFIED` and gates the promise. If the
+   actual edit surface expands, rerun `impact_audit.py` with
    the new seeds/cover and treat uncovered reverse dependents as failed verification; use
    `--fail-on medium` for shared/public contracts or signature changes. If the change crosses
    UI/API/service boundaries, rerun
@@ -363,15 +402,20 @@ The classic Ralph loop trusts the model to be honest. We do not. A `<promise>` i
 only if, in the SAME turn, there is concrete evidence the work is truly done, AND the
 **watcher-gate** has independently verified the result:
 
-- the **watcher-gate** itself (Asolaria N-Nest Corrective Gate) — a separate agent/PID
-  re-executes the work and compares results; `.orchestrator/loop/watcher_state.json` is written
-  with `{"match": true, "status": "MEASURED"}` only when `reported == watcher.recomputed_truth`,
-  or
+- the **watcher-gate** itself (Asolaria N-Nest Corrective Gate) — `python3
+  scripts/watcher_verify.py verify` independently re-executes the anchor's recompute and writes
+  `.orchestrator/loop/watcher_state.json` with `{"match": true, "status": "MEASURED", "challenge":
+  ..., "goal_fp": ...}` only when `reported == watcher.recomputed_truth`; the receipt must ALSO
+  echo the current per-iteration challenge the stop-hook issued (`watcher_challenge.json`) — a
+  receipt that doesn't, or predates the challenge, is rejected even if `match: true` (closes the
+  plain-unauthenticated-JSON self-attestation gap — never hand-write this file), or
 - the run-verification gate passed ("works, not just compiles" — `simplicio-tasks` Step 4b) —
   the `simplicio-dev-cli` operator's passing test+verify pass (its contract step 5/6) satisfies this, or
 - the flow coverage gate passed for a mixed front/back/service change —
   `python3 scripts/flow_audit.py audit <root> --fail-on high` (or `--fail-on medium` for ACs that
-  promise backend integration) found no unhandled UI/API/service gaps, or
+  promise backend integration) found no unhandled UI/API/service gaps — the stop-hook mechanically
+  requires a fresh, green `.orchestrator/flow-audit.json` receipt before honoring the promise
+  whenever the diff touches web-surface files, so this is enforced, not prose-only, or
 - the scope/impact gate passed for the changed shared files —
   `python3 scripts/impact_audit.py audit <root> --file <seed> ...` found no uncovered reverse
   dependents (and, for shared/public contracts, no uncovered local deps/tests under `--fail-on medium`), or
@@ -463,7 +507,7 @@ Where the host runtime supports lifecycle hooks, bind the two cross-platform hoo
 | Hook | Fires | Job |
 |---|---|---|
 | `afterAgentResponse` → `loop_capture.py` | after every turn | extract `<promise>…</promise>`; if it exactly equals `completion_promise` AND in-turn evidence exists → `touch .orchestrator/loop/done`. Fire-and-forget, `exit 0`. Never stops the loop itself. |
-| `stop` → `loop_stop.py` | when the turn ends | guard clauses, each ends the loop cleanly (remove state, `exit 0`): (1) no scratchpad → stop; (2) corrupt frontmatter → stop; (3) `done` flag present → stop (promise fulfilled); (4) `iteration >= max_iterations > 0` → write `HANDOFF.md`, then stop (cap); (5) budget halted → write `HANDOFF.md` (frozen goal + AC status + last attempts) for a different agent to resume, then stop; (6) **spindle handoff latched** → write `HANDOFF.md` and stop (the next agent will pick up); **before promise check: runs watcher-gate** — reads `.orchestrator/loop/watcher_state.json` and rejects the promise if `match: false` or `status: UNVERIFIED`; the re-feed header is tagged with `MEASURED`/`UNVERIFIED` accordingly; else increment `iteration` in place and emit `{"followup_message": "<header>\\n\\n<goal body>"}` to re-feed. |
+| `stop` → `loop_stop.py` | when the turn ends | guard clauses, each ends the loop cleanly (remove state, `exit 0`): (1) no scratchpad → stop; (2) corrupt frontmatter → stop; (2b) **bound operator missing** (when this repo ships `simplicio-loop`, `simplicio-mapper`/`simplicio-dev-cli` absent from PATH) → write `HANDOFF.md`, then stop (never silently degrade to LLM hand-survey/hand-edit); (3) `done` flag present → stop (promise fulfilled); (4) `iteration >= max_iterations > 0` → write `HANDOFF.md`, then stop (cap); (5) budget halted → write `HANDOFF.md` (frozen goal + AC status + last attempts) for a different agent to resume, then stop; (6) **spindle handoff latched** → write `HANDOFF.md` and stop (the next agent will pick up); **before promise check: runs watcher-gate** — reads `.orchestrator/loop/watcher_state.json` and rejects the promise if `match: false`, `status: UNVERIFIED`, or the receipt doesn't echo the current `watcher_challenge.json` nonce/goal_fp; also runs the **flow-audit gate** — a web-touching diff with no fresh, green `.orchestrator/flow-audit.json` rejects the promise too; the re-feed header is tagged with `MEASURED`/`UNVERIFIED` and names any flow-audit gap; a fallback `loop_journal.py record` fires if the agent didn't record one manually this turn, so the phase planner is never blind; a fresh watcher challenge is written before the re-feed; else increment `iteration` in place and emit `{"followup_message": "<header>\\n\\n<goal body>"}` to re-feed. |
 
 Detection (`capture`) and termination (`stop`) are split on purpose — neither parses the
 other's inline state. Iteration carries forward through git history + the working tree, not

{simplicio_loop-3.20.0 → simplicio_loop-3.21.0}/simplicio_loop/_bundle/skills/simplicio-tasks/SKILL.md

@@ -298,7 +298,8 @@ short evidence comment (PR link + verification). **Assemble the PR body mechanic
 carries prints + an item-by-item AC check** — `python3 scripts/pr_evidence.py build --item <id>
 --title "<t>" --summary "<s>" --require-evidence --out .orchestrator/pr_body.md` pulls the
 item-by-item acceptance-criteria checklist from the task anchor (Step 2b/4) AND embeds the
-screenshots/recordings captured by `web_verify`/`video_evidence` under `.orchestrator/tee/web`; with
+screenshots (`web_verify`, under `.orchestrator/tee/web`) and recordings (`video_evidence`, under
+`.orchestrator/tee/video`); with
 `--require-evidence` it EXITS 3 (blocked) rather than open a PR with no prints and no checklist (the
 "PR sem evidência" fix). It honors the discovered `.github/PULL_REQUEST_TEMPLATE.md` (the
 `pr_template` extension point) — appending the checklist + prints under the maintainer's sections —