substratum-cli 0.2.6__tar.gz → 0.2.7__tar.gz

{substratum_cli-0.2.6 → substratum_cli-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: substratum-cli
-Version: 0.2.6
+Version: 0.2.7
 Summary: Substratum: verified-or-refused code, with provenance. The terminal over the comprehension engine.
 Author: Substratum
 License: LicenseRef-Proprietary

{substratum_cli-0.2.6 → substratum_cli-0.2.7}/substratum_cli/__init__.py

@@ -5,4 +5,4 @@ Import budget: this package is stdlib-only; the ONLY module reaching into backen
 """
 # SINGLE SOURCE OF TRUTH for the release version. pyproject reads this (dynamic version), the boot shows
 # it, and the update-check compares against it. To cut a release, bump ONLY this line, then publish.
-__version__ = "0.2.6"
+__version__ = "0.2.7"

{substratum_cli-0.2.6 → substratum_cli-0.2.7}/substratum_cli/build_state.py

@@ -8,7 +8,6 @@ from __future__ import annotations
 
 import json
 import os
-import time
 from typing import Optional
 
 from . import run_store
@@ -19,14 +18,12 @@ def _path(repo: str) -> str:
 
 
 def record(repo: str, kind: str, ts: Optional[int] = None, **fields) -> None:
-    """Append one event. kind: 'query' | 'decision' | 'apply' | 'commit'. Never raises."""
-    try:
-        rec = {"t": int(ts if ts is not None else time.time()), "kind": kind, **fields}
-        os.makedirs(os.path.dirname(_path(repo)), exist_ok=True)
-        with open(_path(repo), "a", encoding="utf-8") as fh:
-            fh.write(json.dumps(rec) + "\n")
-    except Exception:
-        pass
+    """Append one event. kind: 'query' | 'decision' | 'apply' | 'commit'. Never raises.
+
+    Delegates to run_store.append_event, the single ledger writer, so apply/commit etc. carry actor +
+    session attribution when session state is on (logged out they stay byte-identical to prior
+    releases -- identity.stamp() is empty)."""
+    run_store.append_event(repo, kind, ts=ts, **fields)
 
 
 def _events(repo: str) -> list:
@@ -95,6 +92,55 @@ def recall_decision(repo: str, intent: str, sig: str, into: str = None) -> str:
     return got
 
 
+def sessions(repo: str) -> list:
+    """PS0b: distinct working sessions from the ledger: [{session, actor, events, first, last}],
+    oldest->newest. A session groups the runs/acts of one working context (a REPL lifetime, or a
+    burst of one-shots sharing SUBSTRATUM_SESSION_ID) so a build is legible per session and resumable
+    (`substratum log --session <id>`)."""
+    agg: dict = {}
+    for e in _events(repo):
+        sid = e.get("session")
+        if not sid:
+            continue
+        t = e.get("t", 0)
+        a = agg.get(sid)
+        if a is None:
+            agg[sid] = {"session": sid, "actor": e.get("actor", ""), "events": 1, "first": t, "last": t}
+        else:
+            a["events"] += 1
+            a["first"] = min(a["first"], t)
+            a["last"] = max(a["last"], t)
+    return sorted(agg.values(), key=lambda s: s["last"])
+
+
+def record_rule(repo: str, text: str, scope: str = "") -> None:
+    """Persist a STANDING rule/preference the user set once (e.g. 'always use pathlib', 'never catch
+    bare except', 'our error type is AppError'). Recalled on every future build so intent is
+    CUMULATIVE, not re-stated each session -- the offense against drift: a rule you set once can never
+    be forgotten or drifted away from 15 rounds later."""
+    t = " ".join((text or "").split())
+    if t:
+        record(repo, "rule", text=t, scope=(scope or ""))
+
+
+def forget_rule(repo: str, text: str) -> None:
+    t = " ".join((text or "").split())
+    if t:
+        record(repo, "unrule", text=t)
+
+
+def rules(repo: str) -> list:
+    """Active standing rules: every 'rule' not later 'unrule'd, most-recent first, deduped by text.
+    Each entry carries who set it + when (attribution) when session state was on."""
+    active: dict = {}
+    for e in _events(repo):
+        if e.get("kind") == "rule" and e.get("text"):
+            active[e["text"]] = e
+        elif e.get("kind") == "unrule" and e.get("text"):
+            active.pop(e["text"], None)
+    return list(reversed(list(active.values())))
+
+
 def standing(repo: str) -> dict:
     """The welcome-back summary a session shows on open, so the persistent state is FELT, not just
     queryable: how much has been built, the last run, any verified work still waiting to be applied,
@@ -115,4 +161,5 @@ def standing(repo: str) -> dict:
         "unapplied": unapplied[:3],
         "unapplied_total": len(unapplied),
         "decisions": decision_count(repo),
+        "rules": len(rules(repo)),
     }

{substratum_cli-0.2.6 → substratum_cli-0.2.7}/substratum_cli/cli.py

@@ -52,6 +52,15 @@ def build_parser() -> argparse.ArgumentParser:
         ("scaffold-test", "emit a runnable failing test pinning a target (the flip engine)"),
         ("summarize", "describe the codebase in plain English (grounded in real symbols)"),
         ("runs", "run history + the refusal->verified conversion ledger (the proof store)"),
+        ("log", "the attributed decision timeline (who/when/verdict/target); filterable (pure read)"),
+        ("why", "the decisions that shaped a file/symbol, newest first + provenance (pure read)"),
+        ("blame-decision", "which verified decision last touched a line (reasoning-blame; pure read)"),
+        ("recheck", "re-verify a past decision against current code (regression sentinel; --suite)"),
+        ("remember", "record a standing rule/preference for this repo (recalled every build)"),
+        ("rules", "list the active standing rules (who set each, when)"),
+        ("forget", "retire a standing rule"),
+        ("sessions", "the working sessions of this build (who, how many decisions, when)"),
+        ("gc", "compact: keep the decision index forever, drop heavy logs older than --keep-days"),
         ("undo", "reverse-apply a run (the inverse of apply)"),
         ("commit", "proof-carrying git commit of a verified, applied run"),
         ("pr", "open a proof-carrying pull request (pushes with your git; proof in the body)"),
@@ -88,10 +97,33 @@ def build_parser() -> argparse.ArgumentParser:
             p.add_argument("--title", default=None)
         if name in ("apply", "show", "replay", "attest", "explain", "undo", "commit"):
             p.add_argument("run_id")
+        if name == "apply":
+            p.add_argument("--reverify", action="store_true",
+                           help="re-run the gate against your current tree before writing (gold standard)")
         if name == "commit":
             p.add_argument("--message", default=None)
         if name == "explain":
             p.add_argument("--line", default=None)
+        if name == "why":
+            p.add_argument("target", help="file path or symbol to recall decisions for")
+        if name == "blame-decision":
+            p.add_argument("spec", help="path or path:line to blame the decision for")
+        if name == "recheck":
+            p.add_argument("run_id", nargs="?", default=None, help="run to re-verify (omit with --suite)")
+            p.add_argument("--suite", action="store_true", help="re-prove every past verified decision")
+        if name in ("remember", "forget"):
+            p.add_argument("text", help="the standing rule / preference text")
+        if name == "gc":
+            p.add_argument("--keep-days", type=int, default=90,
+                           help="retain heavy artifacts newer than this many days (index kept forever)")
+        if name == "log":
+            p.add_argument("--limit", type=int, default=30)
+            p.add_argument("--verdict", default=None, help="filter by verdict (VERIFIED/REFUSED/...)")
+            p.add_argument("--actor", default=None, help="filter by who made the decision")
+            p.add_argument("--session", default=None, help="filter by session id")
+            p.add_argument("--target", default=None, help="filter by target substring (file/test)")
+            p.add_argument("--since", default=None, help="only the last N days")
+            p.add_argument("--mine", action="store_true", help="only your own decisions")
     return ap
 
 
@@ -106,13 +138,15 @@ def dispatch(args) -> "_result.SubstratumResult":
         return cmd_verify(args)
     if cmd == "fix":
         from .commands.fix import cmd_fix
-        return cmd_fix(args)
+        from . import rulebook
+        return rulebook.gate(cmd_fix(args), args.repo)   # final conformance layer (display transform)
     if cmd == "write":
         from .commands.write import cmd_write
-        return cmd_write(args)
+        from . import rulebook
+        return rulebook.gate(cmd_write(args), args.repo)
     if cmd == "apply":
         from .commands.apply import cmd_apply
-        return cmd_apply(args.repo, args.run_id)
+        return cmd_apply(args.repo, args.run_id, reverify=getattr(args, "reverify", False))
     if cmd == "init":
         from .commands.init_cmd import cmd_init
         return cmd_init(args.repo)
@@ -137,6 +171,38 @@ def dispatch(args) -> "_result.SubstratumResult":
     if cmd == "runs":
         from .commands.history import cmd_runs
         return cmd_runs(args.repo)
+    if cmd == "log":
+        from .commands.history import cmd_log
+        return cmd_log(args)
+    if cmd == "why":
+        from .commands.recall import cmd_why
+        return cmd_why(args.repo, args.target)
+    if cmd == "blame-decision":
+        from .commands.recall import cmd_blame_decision
+        return cmd_blame_decision(args.repo, args.spec)
+    if cmd == "recheck":
+        from .commands.recheck import cmd_recheck, cmd_recheck_suite
+        if getattr(args, "suite", False):
+            return cmd_recheck_suite(args.repo)
+        if not args.run_id:
+            return _result.make(codes.REFUSED, "recheck", "recheck", code=codes.RUN_NOT_FOUND,
+                                summary="recheck needs a run id or --suite")
+        return cmd_recheck(args.repo, args.run_id)
+    if cmd == "remember":
+        from .commands.rules import cmd_remember
+        return cmd_remember(args.repo, args.text)
+    if cmd == "forget":
+        from .commands.rules import cmd_forget
+        return cmd_forget(args.repo, args.text)
+    if cmd == "rules":
+        from .commands.rules import cmd_rules
+        return cmd_rules(args.repo)
+    if cmd == "sessions":
+        from .commands.history import cmd_sessions
+        return cmd_sessions(args.repo)
+    if cmd == "gc":
+        from .commands.history import cmd_gc
+        return cmd_gc(args.repo, keep_days=getattr(args, "keep_days", 90))
     if cmd == "undo":
         from .commands.undo import cmd_undo
         return cmd_undo(args.repo, args.run_id)

{substratum_cli-0.2.6 → substratum_cli-0.2.7}/substratum_cli/codes.py

@@ -34,6 +34,7 @@ REPLAY_STATE_DRIFT = "REPLAY_STATE_DRIFT"           # 11
 NO_DRIVER = "NO_DRIVER"                             # 12: no gate runner / no filetype driver
 AUTONOMY_LOCKED = "AUTONOMY_LOCKED"                 # 12: an L2/L3 action attempted at L1
 UNDERDETERMINED_INTENT = "UNDERDETERMINED_INTENT"   # 13: candidates composed, all failed the gate
+RULEBOOK_VIOLATION = "RULEBOOK_VIOLATION"           # 13: verified output violates a standing rule
 FLAKY_OR_VACUOUS_WARRANT = "FLAKY_OR_VACUOUS_WARRANT"  # 14: tests pass at base (nothing to fix / flaky)
 FLAKY_TEST = "FLAKY_TEST"                           # 14: quarantined nondeterministic test
 RUN_NOT_FOUND = "RUN_NOT_FOUND"                     # 11: show/explain/replay on an unknown id
@@ -43,8 +44,8 @@ NO_TEST_RUNNER = "NO_TEST_RUNNER"                   # 12: `failing` found no tes
 REFUSAL_CODES = (
     NO_GROUNDED_CANDIDATE, GATE_PRECONDITION, NO_WARRANT_TESTS, HUNK_CONTEXT_STALE,
     APPLY_STATE_DRIFT, REPLAY_STATE_DRIFT, NO_DRIVER, AUTONOMY_LOCKED,
-    UNDERDETERMINED_INTENT, FLAKY_OR_VACUOUS_WARRANT, FLAKY_TEST, RUN_NOT_FOUND,
-    NO_ENGINE, NO_TEST_RUNNER,
+    UNDERDETERMINED_INTENT, RULEBOOK_VIOLATION, FLAKY_OR_VACUOUS_WARRANT, FLAKY_TEST,
+    RUN_NOT_FOUND, NO_ENGINE, NO_TEST_RUNNER,
 )
 
 # ---- the exit-code table (closed; the machine contract) ----------------------
@@ -66,6 +67,7 @@ _REFUSAL_EXIT = {
     NO_ENGINE: 12,
     NO_TEST_RUNNER: 12,
     UNDERDETERMINED_INTENT: 13,
+    RULEBOOK_VIOLATION: 13,
     FLAKY_OR_VACUOUS_WARRANT: 14,
     FLAKY_TEST: 14,
 }

substratum_cli-0.2.7/substratum_cli/commands/apply.py

@@ -0,0 +1,95 @@
+"""`substratum apply <run-id>` -- apply a stored run's verified diff. L1 default: apply is the ONLY
+writer. The write is a deliberate ceremony (PS2d), built around what an engineer actually expects
+before code lands: see exactly what changes, know it is still valid against the tree RIGHT NOW (not a
+stale proof), see that it was proven, know it is reversible, and know it is recorded. Refuses
+APPLY_STATE_DRIFT if HEAD moved or the diff no longer applies cleanly to the current tree."""
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+
+from .. import codes
+from .. import gitio
+from .. import refusals
+from .. import result as _result
+from .. import run_store
+
+
+def _proof_of(res) -> "dict | None":
+    """The stored correctness proof, surfaced at apply time so the write is transparently grounded."""
+    g = res.gate
+    if not g or not g.base_status:
+        return None
+    return {"base": g.base_status, "patched": g.patched_status, "tests": list(g.test_ids),
+            "kind": g.kind}
+
+
+def cmd_apply(repo: str, run_id: str, reverify: bool = False) -> "_result.SubstratumResult":
+    repo = os.path.abspath(repo)
+    loaded = run_store.load_run(repo, run_id)
+    if loaded is None:
+        return _result.make(codes.REFUSED, run_id, "apply", code=codes.RUN_NOT_FOUND,
+                            refusal=refusals.build(codes.RUN_NOT_FOUND,
+                                                   ctx={"target": run_id, "run_id": run_id}))
+    res, inputs = loaded
+    recorded_head = (inputs.get("run_key") or {}).get("head_sha")
+    current_head = gitio.head_sha(repo)
+    if recorded_head and current_head != recorded_head:
+        return _result.make(codes.REFUSED, run_id, "apply", code=codes.APPLY_STATE_DRIFT,
+                            refusal=refusals.build(codes.APPLY_STATE_DRIFT,
+                                                   ctx={"target": run_id, "run_id": run_id}))
+    if not res.diff.strip():
+        return _result.make(codes.REFUSED, run_id, "apply", code=codes.NO_GROUNDED_CANDIDATE,
+                            refusal=refusals.build(codes.NO_GROUNDED_CANDIDATE,
+                                                   ctx={"target": run_id, "run_id": run_id}))
+
+    with tempfile.NamedTemporaryFile("w", suffix=".patch", delete=False) as fh:
+        fh.write(res.diff)
+        patch = fh.name
+    try:
+        # Ceremony 1 -- re-check against the tree AT THIS INSTANT (a dry run; the proof isn't stale).
+        chk = subprocess.run(["git", "-C", repo, "apply", "--check", patch],
+                             capture_output=True, text=True, errors="replace")
+        rechecked = chk.returncode == 0
+        if not rechecked:
+            return _result.make(codes.REFUSED, run_id, "apply", code=codes.APPLY_STATE_DRIFT,
+                                refusal=refusals.build(codes.APPLY_STATE_DRIFT,
+                                                       ctx={"target": run_id, "run_id": run_id}))
+
+        # Ceremony 2 (opt-in gold standard) -- re-run the gate against the current tree, live.
+        reverified = None
+        if reverify and res.gate and res.gate.test_ids:
+            from .verify import run_verify
+            vr = run_verify(repo, res.diff, tuple(res.gate.test_ids))
+            reverified = vr.verdict
+            if vr.verdict not in (codes.PASS, codes.VERIFIED):
+                return _result.make(codes.REFUSED, run_id, "apply", code=codes.APPLY_STATE_DRIFT,
+                                    refusal=refusals.build(
+                                        codes.APPLY_STATE_DRIFT, ctx={"target": run_id, "run_id": run_id},
+                                        why="the fix no longer passes the gate against your current tree; "
+                                            "not writing a stale proof."))
+
+        # The write (unchanged core: index apply, 3-way fallback).
+        r = subprocess.run(["git", "-C", repo, "apply", "--index", patch],
+                           capture_output=True, text=True, errors="replace")
+        if r.returncode != 0:
+            r2 = subprocess.run(["git", "-C", repo, "apply", "--3way", patch],
+                                capture_output=True, text=True, errors="replace")
+            if r2.returncode != 0:
+                return _result.make(codes.REFUSED, run_id, "apply", code=codes.APPLY_STATE_DRIFT,
+                                    refusal=refusals.build(codes.APPLY_STATE_DRIFT,
+                                                           ctx={"target": run_id, "run_id": run_id}))
+    finally:
+        os.unlink(patch)
+
+    # Ceremony 3 -- record the effectful decision (who / against-what-base / with-what-proof).
+    from .. import build_state
+    build_state.record(repo, "apply", run_id=run_id, files=list(res.files),
+                       base=current_head, effect="write")
+    return _result.make(codes.PASS, run_id, "apply", files=res.files,
+                        data={"applied": list(res.files),
+                              "rechecked": "applies cleanly to your working tree",
+                              "head_unchanged": bool(recorded_head) and current_head == recorded_head,
+                              "reverified": reverified, "proof": _proof_of(res),
+                              "reversible": f"substratum undo {run_id}"})

{substratum_cli-0.2.6 → substratum_cli-0.2.7}/substratum_cli/commands/auth.py

@@ -32,6 +32,6 @@ def cmd_whoami() -> int:
     if account.is_logged_in():
         sys.stdout.write(f"  {account.github_login() or 'logged in'}  ·  {account.server()}\n")
     else:
-        sys.stdout.write("  not logged in — run  substratum login  to use the hosted engine "
+        sys.stdout.write("  not logged in -- run  substratum login  to use the hosted engine "
                          "(local commands work offline)\n")
     return 0

substratum_cli-0.2.7/substratum_cli/commands/history.py

@@ -0,0 +1,84 @@
+"""`runs` / `log` -- the proof store made visible: the newest runs (every VERIFIED and every
+REFUSED) plus the refusal->VERIFIED conversion ledger. This is the persistent, proof-carrying
+memory that no LLM tool has, surfaced in the terminal."""
+from __future__ import annotations
+
+import time
+
+from .. import build_state, codes, identity, run_store, runid
+from .. import result as _result
+
+
+def cmd_sessions(repo: str) -> "_result.SubstratumResult":
+    """PS0b: the working sessions of this build -- who, how many decisions, when. Resume any with
+    `log --session <id>`."""
+    ss = build_state.sessions(repo)
+    rid, _key = runid.compute(repo, "sessions", {"n": len(ss)})
+    return _result.make(codes.PASS, rid, "sessions",
+                        data={"sessions": list(reversed(ss)),   # newest first for display
+                              "session_on": identity.session_state_on()})
+
+
+def cmd_gc(repo: str, keep_days: int = 90) -> "_result.SubstratumResult":
+    """PS4b: keep the decision index forever; GC heavy gate logs + patches older than keep_days."""
+    stats = run_store.compact(repo, keep_days)
+    rid, _key = runid.compute(repo, "gc", {"keep_days": keep_days})
+    return _result.make(codes.PASS, rid, "gc",
+                        data={"keep_days": keep_days, **stats})
+
+
+def cmd_runs(repo: str, limit: int = 15) -> "_result.SubstratumResult":
+    runs = run_store.list_runs(repo, limit)
+    refn, conv = run_store.refusal_stats(repo, window_days=36500)   # all-time ledger
+    rid, _key = runid.compute(repo, "runs", {"n": len(runs)})
+    return _result.make(codes.PASS, rid, "runs",
+                        data={"runs": runs, "ledger": {"refusals": refn, "converted": conv}})
+
+
+def _matches(e: dict, args, me: str) -> bool:
+    """PS1a filters over the attributed timeline. All pure read; a filter never re-runs anything."""
+    vf = getattr(args, "verdict", None)
+    if vf and (e.get("verdict") or "").upper() != vf.upper():
+        return False
+    af = getattr(args, "actor", None)
+    if af and (e.get("actor") or "") != af:
+        return False
+    sf = getattr(args, "session", None)
+    if sf and (e.get("session") or "") != sf:
+        return False
+    if getattr(args, "mine", False) and (e.get("actor") or "") != me:
+        return False
+    tf = getattr(args, "target", None)
+    if tf and tf.lower() not in (e.get("target") or "").lower():
+        return False
+    since = getattr(args, "since", None)
+    if since:
+        try:
+            if e.get("t", 0) < time.time() - float(since) * 86400.0:
+                return False
+        except (TypeError, ValueError):
+            pass
+    return True
+
+
+def cmd_log(args) -> "_result.SubstratumResult":
+    """PS1a: the attributed, filterable decision timeline (pure read; never re-executes). Logged in ->
+    the attributed 'run' events (who/when/verdict/target/effect), filtered. Logged out / no ledger ->
+    the base run history, unattributed (identical to `runs`)."""
+    repo = args.repo
+    limit = getattr(args, "limit", None) or 30
+    me = identity.actor()
+    runs = [e for e in run_store.read_activity(repo) if e.get("kind") == "run"]
+    attributed = bool(runs)
+    if attributed:
+        entries = [e for e in runs if _matches(e, args, me)]
+        entries.sort(key=lambda e: e.get("t", 0), reverse=True)
+        entries = entries[:limit]
+    else:
+        entries = run_store.list_runs(repo, limit)   # base history when session state is off
+    refn, conv = run_store.refusal_stats(repo, window_days=36500)
+    rid, _key = runid.compute(repo, "log", {"n": len(entries)})
+    return _result.make(codes.PASS, rid, "log",
+                        data={"timeline": entries, "attributed": attributed,
+                              "ledger": {"refusals": refn, "converted": conv},
+                              "session_on": identity.session_state_on()})

substratum_cli-0.2.7/substratum_cli/commands/recall.py

@@ -0,0 +1,91 @@
+"""PS1b/PS1c: recall the DECISIONS behind code.
+
+`why <file/symbol>`      -- every decision that shaped a target, newest first, with its provenance.
+`blame-decision <f:line>`-- the decision that last touched a specific line (git-blame for reasoning).
+
+Both are PURE READ over the activity ledger + the proof store: they never re-execute and never write.
+When session state is off (logged out) there is no attributed timeline, so they surface a login hint
+and fall back to whatever base records exist.
+"""
+from __future__ import annotations
+
+from .. import codes, diffs, identity, run_store, runid
+from .. import result as _result
+
+
+def _runs_touching(repo: str, needle: str) -> list:
+    """'run' events whose target or files mention `needle` (case-insensitive substring), in ledger
+    order (oldest->newest)."""
+    n = (needle or "").lower()
+    out = []
+    for e in run_store.read_activity(repo):
+        if e.get("kind") != "run":
+            continue
+        files = e.get("files") or []
+        if n in (e.get("target") or "").lower() or any(n in (f or "").lower() for f in files):
+            out.append(e)
+    return out
+
+
+def _enrich(repo: str, e: dict) -> dict:
+    """Fold the stored proof's provenance + summary into a timeline entry."""
+    prov, summary = [], ""
+    loaded = run_store.load_run(repo, e.get("run_id"))
+    if loaded:
+        res, _inp = loaded
+        summary = res.summary or ""
+        if res.provenance:
+            prov = list(res.provenance.entries)
+    return {"run_id": e.get("run_id"), "verdict": e.get("verdict"), "operation": e.get("operation"),
+            "actor": e.get("actor"), "session": e.get("session"), "t": e.get("t"),
+            "effect": e.get("effect"), "files": e.get("files") or [],
+            "provenance": prov, "summary": summary}
+
+
+def cmd_why(repo: str, target: str) -> "_result.SubstratumResult":
+    matched = _runs_touching(repo, target)
+    decisions = [_enrich(repo, e) for e in matched][-25:]
+    decisions.reverse()  # newest first
+    rid, _k = runid.compute(repo, "why", {"target": target})
+    return _result.make(codes.PASS, rid, "why",
+                        data={"target": target, "decisions": decisions,
+                              "session_on": identity.session_state_on()})
+
+
+def _diff_touches(diff_text: str, path: str, line: int) -> bool:
+    """Does any hunk for `path` cover new-side `line`?"""
+    if not diff_text:
+        return False
+    try:
+        for fd in diffs.parse(diff_text):
+            if not (fd.path == path or fd.path.endswith("/" + path) or path.endswith("/" + fd.path)):
+                continue
+            for h in fd.hunks:
+                if h.new_start <= line < h.new_start + max(h.new_len, 1):
+                    return True
+    except Exception:
+        return False
+    return False
+
+
+def cmd_blame_decision(repo: str, spec: str) -> "_result.SubstratumResult":
+    """spec = 'path' or 'path:line'. The most recent decision that touched that line (or, with no
+    line, the file). Reasoning-blame: not who committed it, but which verified decision established
+    it and why."""
+    path, _, lno = (spec or "").partition(":")
+    line = int(lno) if lno.isdigit() else None
+    candidates = _runs_touching(repo, path)
+    hit = None
+    for e in reversed(candidates):                # newest first
+        if line is None:
+            hit = e
+            break
+        loaded = run_store.load_run(repo, e.get("run_id"))
+        if loaded and _diff_touches(loaded[0].diff, path, line):
+            hit = e
+            break
+    blame = _enrich(repo, hit) if hit else None
+    rid, _k = runid.compute(repo, "blame", {"spec": spec})
+    return _result.make(codes.PASS, rid, "blame",
+                        data={"spec": spec, "path": path, "line": line, "blame": blame,
+                              "session_on": identity.session_state_on()})

substratum_cli-0.2.7/substratum_cli/commands/recheck.py

@@ -0,0 +1,89 @@
+"""PS2a/PS2c: `recheck` -- re-verify a past decision against the CURRENT code (the regression /
+conformance sentinel). Distinct from `replay`, which proves determinism when nothing changed:
+recheck EXPECTS the world to have moved and reports the delta.
+
+It RE-DERIVES the original intent against the current base -- a pure function of intent + base +
+versions (zero-LLM, air-gapped, no tokens) -- and NEVER writes the working tree. Turning a re-
+derivation into a change is always a separate, gated `apply` (PS2b: derivation vs effect stay split).
+
+`regressed` (was VERIFIED, now not) is the alarm: zero-wrong extended across TIME. `recheck --suite`
+re-proves every past verified decision so an engine/library/version bump can never silently regress
+what your repo already established.
+"""
+from __future__ import annotations
+
+from .. import codes, refusals, run_store, runid
+from .. import result as _result
+
+_OK = ("VERIFIED", "PASS")
+
+
+def classify_delta(base_verdict: str, now_verdict: str, base_diff: str, now_diff: str) -> str:
+    """Pure: the status of a re-derivation vs its stored decision. 'regressed' is the alarm."""
+    was, now = base_verdict in _OK, now_verdict in _OK
+    if was and not now:
+        return "regressed"
+    if not was and now:
+        return "recovered"
+    if base_verdict == now_verdict:
+        return "stable" if (base_diff or "") == (now_diff or "") else "drifted"
+    return "changed"
+
+
+def _reexecute(repo: str, op: str, inputs: dict):
+    """Re-derive the ORIGINAL intent against the CURRENT base. Producers only (fix/write); NEVER
+    writes the tree (op_* return a proposal + store a record; apply is the only writer). Returns a
+    fresh SubstratumResult, or None if this op cannot be re-derived (informational ops)."""
+    inp = inputs.get("inputs") or {}
+    if op == "fix" and inp.get("failing_tests"):
+        from .. import product_ops
+        return product_ops.op_fix_from_failing_test(
+            repo, list(inp["failing_tests"]), intent=inp.get("intent", ""),
+            test_command=inp.get("test_command"))
+    if op == "write" and inp.get("sig"):
+        from .. import product_ops
+        return product_ops.op_write_from_intent(
+            repo, inp.get("intent", ""), inp["sig"], into=inp.get("into"),
+            prefer_purpose=inp.get("prefer"))
+    return None
+
+
+def cmd_recheck(repo: str, run_id: str) -> "_result.SubstratumResult":
+    loaded = run_store.load_run(repo, run_id)
+    if loaded is None:
+        return _result.make(codes.REFUSED, run_id, "recheck", code=codes.RUN_NOT_FOUND,
+                            refusal=refusals.build(codes.RUN_NOT_FOUND,
+                                                   ctx={"target": run_id, "run_id": run_id}))
+    stored, inputs = loaded
+    re_res = _reexecute(repo, stored.operation, inputs)
+    if re_res is None:
+        return _result.make(codes.REFUSED, run_id, "recheck", code=codes.GATE_PRECONDITION,
+                            refusal=refusals.build(codes.GATE_PRECONDITION,
+                                                   ctx={"target": run_id, "run_id": run_id},
+                                                   why=f"a {stored.operation} run cannot be re-derived"))
+    status = classify_delta(stored.verdict, re_res.verdict, stored.diff, re_res.diff)
+    verdict = codes.FAIL if status == "regressed" else codes.PASS
+    rid, _k = runid.compute(repo, "recheck", {"of": run_id})
+    return _result.make(verdict, rid, "recheck",
+                        data={"of": run_id, "status": status, "base_verdict": stored.verdict,
+                              "now_verdict": re_res.verdict, "now_run_id": re_res.run_id,
+                              "diff_changed": (stored.diff or "") != (re_res.diff or "")})
+
+
+def cmd_recheck_suite(repo: str, limit: int = 500) -> "_result.SubstratumResult":
+    """Re-prove every past VERIFIED producer decision against current HEAD. Any regression fails the
+    suite. This is the sentinel: run it in CI after an engine/library bump."""
+    runs = run_store.list_runs(repo, limit)
+    verified = [r for r in runs if r.get("verdict") in _OK and r.get("operation") in ("fix", "write")]
+    results, regressed = [], 0
+    for r in verified:
+        res = cmd_recheck(repo, r["run_id"])
+        st = (res.data or {}).get("status", "?")
+        regressed += (st == "regressed")
+        results.append({"run_id": r["run_id"], "status": st,
+                        "now_verdict": (res.data or {}).get("now_verdict")})
+    verdict = codes.FAIL if regressed else codes.PASS
+    rid, _k = runid.compute(repo, "recheck_suite", {"n": len(verified)})
+    return _result.make(verdict, rid, "recheck",
+                        data={"suite": True, "checked": len(verified), "regressed": regressed,
+                              "results": results})

substratum_cli-0.2.7/substratum_cli/commands/rules.py

@@ -0,0 +1,45 @@
+"""PS3c: standing rules / preferences -- intent made cumulative.
+
+`remember "<rule>"`  records a standing rule for this repo (login-gated: it's session state).
+`rules`              lists the active standing rules (who set each, when).
+`forget "<rule>"`    retires a rule.
+
+A rule set once is recalled on every future build, so the user never re-states intent and the system
+can never drift off an established preference. Applying rules INTO derivation as grounding is the
+engine-side lever (PS3b); this is the record + recall + surface side. Pure client, never touches the
+gate.
+"""
+from __future__ import annotations
+
+from .. import build_state, codes, identity, runid
+from .. import result as _result
+
+
+def _snapshot(repo: str, extra: dict = None) -> dict:
+    d = {"rules": build_state.rules(repo), "session_on": identity.session_state_on()}
+    if extra:
+        d.update(extra)
+    return d
+
+
+def cmd_remember(repo: str, text: str) -> "_result.SubstratumResult":
+    rid, _k = runid.compute(repo, "remember", {"text": text})
+    if not identity.session_state_on():
+        return _result.make(codes.REFUSED, rid, "rules", code=codes.AUTONOMY_LOCKED,
+                            data=_snapshot(repo, {"recorded": None}))
+    build_state.record_rule(repo, text)
+    return _result.make(codes.PASS, rid, "rules",
+                        data=_snapshot(repo, {"recorded": " ".join((text or "").split())}))
+
+
+def cmd_forget(repo: str, text: str) -> "_result.SubstratumResult":
+    rid, _k = runid.compute(repo, "forget", {"text": text})
+    if identity.session_state_on():
+        build_state.forget_rule(repo, text)
+    return _result.make(codes.PASS, rid, "rules",
+                        data=_snapshot(repo, {"forgot": " ".join((text or "").split())}))
+
+
+def cmd_rules(repo: str) -> "_result.SubstratumResult":
+    rid, _k = runid.compute(repo, "rules", {})
+    return _result.make(codes.PASS, rid, "rules", data=_snapshot(repo))