@andresmassello/uscha 1.55.0 → 1.56.0

package/README.md

@@ -40,8 +40,8 @@ Requires **Python 3.8+** on the machine (the engine is Python stdlib — no pip
 runtime dependencies). The npm package is a thin router; the canonical installer is
 `uscha-kit/install-uscha.py`.
 
-**Kit v1.55.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
-[changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG-1.55.0.md)
+**Kit v1.56.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+[changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG-1.56.0.md)
 (the per-release changelogs live in the repo, not in the npm tarball)
 
 ---
@@ -80,6 +80,32 @@ and see which file, which test, and when.
 evidence from **11 language stacks** — maven, gradle, ant, python, node, go, rust, dotnet,
 cpp, swift, flutter — and computes a readiness score with hard caps and visible provenance.
 
+## Compatibility matrix
+
+Generated from `TARGETS`/`SKILL_ROOTS` in the installer, so it cannot drift from the code.
+
+| target | agent | installs to | INV-GOLDEN-01 | exercised against a real agent |
+|---|---|---|---|---|
+| `codex` | Codex | `~/plugins/uscha` | advisory | **yes** |
+| `claude` | Claude Code | `~/.claude/skills` | **enforced** (PreToolUse hook, best-effort) | **yes** |
+| `pi` | pi (Earendil) | `~/.agents/skills` | advisory | no — placement + read-back only |
+| `cursor` | Cursor | `~/.cursor/skills` | advisory | no — placement + read-back only |
+| `copilot` | VS Code / Copilot | `~/.copilot/skills` | advisory | no — placement + read-back only |
+| `gemini` | Gemini CLI | `~/.gemini/skills` | advisory | no — placement + read-back only |
+| `cline` | Cline | `~/.cline/skills` | advisory | no — placement + read-back only |
+
+**"Exercised" is the column that matters.** For every target but Claude Code and Codex, what
+is measured is that the nine skills land where that agent documents reading them and that
+`doctor` reads them back — *that they load is a documented expectation, not a measurement.*
+INV-GOLDEN-01 is mechanically attempted only where a blocking pre-tool hook exists; everywhere
+else `doctor` reports `advisory` rather than implying a guard it cannot see.
+
+| OS | how it is verified | status |
+|---|---|---|
+| Linux | CI matrix (py3.8 + py3.13) + local WSL | **measured** |
+| Windows | CI matrix (py3.8 + py3.13) + native local | **measured** |
+| macOS | CI matrix (py3.8 + py3.13), real runners | **measured** |
+
 ## The loop, in short
 
 1. **Model first.** `/uscha-discovery` (new) or `/uscha-adr-refine` (known feature) writes
@@ -135,7 +161,11 @@ audits/                 # adversarial audit outputs
 
 The rules are in [`CLAUDE.md`](CLAUDE.md). The short version: no doc may claim what the
 engine does not do; the ES and EN twins travel together; every engine change carries a
-smoke test; and the agent never writes a `.approved` file — that one is enforced by a hook.
+smoke test; and a PreToolUse hook stops the agent from writing a `.approved` golden.
+**Scoped honestly**: that hook is a *best-effort* guard and it is registered on the Claude
+target only — it inspects a tool call as TEXT, so an indirect write (a script that assembles
+the filename, a symlink) gets through, and every other target reports `golden_guard:
+advisory`. The MEASURED control is `golden-diff`, which compares bytes.
 
 ## History
 

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "1.55.0",
+  "version": "1.56.0",
   "description": "Spec-driven development for LLM coding agents: 9 skills + a stdlib evidence engine. Facts block, guesses advise; the human approves.",
+  "author": {
+    "name": "Andres Massello",
+    "url": "https://github.com/andresmassello"
+  },
   "bin": {
     "uscha": "bin/uscha.js",
     "uscha-kit": "bin/uscha.js"

package/uscha-kit/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.55.0",
+  "version": "1.56.0",
   "displayName": "Uscha",
   "description": "Spec-driven development for LLM coding agents: 9 skills (discovery, adr-refine, reverse-discovery, characterize, devloop, sysdoc, rubric, mirador, status) + a stdlib measurement engine (qa_ledger.py, 29 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {

package/uscha-kit/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "1.55.0",
+  "version": "1.56.0",
   "description": "Uscha spec-driven development methodology for coding agents. Includes npm/npx router.",
   "author": {
     "name": "Andres Massello",

package/uscha-kit/README.md

@@ -1,6 +1,6 @@
 # uscha-kit
 
-**Kit version:** v1.55.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.56.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
 
 Spec-driven orchestrator + multi-repo QA for Claude Code, with a deterministic ledger.
 **Nine skills** (`uscha-discovery`, `uscha-adr-refine`, `uscha-devloop`, `uscha-sysdoc`, `uscha-reverse-discovery`,
@@ -18,7 +18,7 @@ uscha-kit/
 ?? install-uscha.py             # canonical installer used by npm/npx
 ├─ uscha.config.json            # config: repos, thresholds, commands
 ├─ hooks/
-│  └─ block-approved-writes.py     # PreToolUse: the agent CANNOT write .approved (INV-GOLDEN-01)
+│  └─ block-approved-writes.py     # PreToolUse: best-effort block on writing a golden (Claude only)
 ├─ templates/
 │  ├─ CLAUDE.md                    # permanent repo protocol
 │  ├─ CONSTITUTION.md              # inviolable invariants (fill in the domain)
@@ -60,7 +60,7 @@ BEFORE touching anything.
 /uscha-reverse-discovery   # FACTS map of the old system (endpoints, contracts, dependencies)
    ↓
 /uscha-characterize        # runs the ORIGINAL code with a real corpus → .received → STOPS:
-   ↓                 #   a HUMAN approves the .approved (the agent never writes them — hook)
+   ↓                 #   a HUMAN approves the golden (a best-effort hook discourages the agent; golden-diff measures)
 /uscha-devloop            # migrates; golden-diff byte-compares against the .approved on each pass
 ```
 

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.55.0
+uscha-kit 1.56.0

package/uscha-kit/hooks/block-approved-writes.py

@@ -1,24 +1,130 @@
 #!/usr/bin/env python3
-"""Portable Claude PreToolUse hook for INV-GOLDEN-01."""
+"""PreToolUse hook for INV-GOLDEN-01 -- a BEST-EFFORT guard, not a sandbox.
+
+What it does
+------------
+Stops the obvious ways an agent writes, renames or deletes an approved golden
+fixture, so the human stays the only author of field truth. Reads are allowed on
+purpose: golden-diff has to read the file it compares against.
+
+What it CANNOT do -- read this before trusting it
+-------------------------------------------------
+It inspects the tool call as TEXT. It cannot know a command's real filesystem
+effects, so any indirect write gets through: a Python or Node one-liner that
+assembles the filename from pieces, a script whose contents it never sees, a
+symlink pointing at the golden, a process spawned by another process. Treat this
+as a guardrail against accident and casual shortcut -- NOT as a security boundary
+against an adversarial agent. The measured control is `golden-diff`, which
+compares bytes; this hook only lowers the odds of ever needing it.
+
+It also only exists where a blocking pre-tool hook exists. `install-uscha.py`
+registers it for the Claude target only; every Agent-Skills target
+(codex/pi/cursor/copilot/gemini/cline) reports `golden_guard: advisory`, which is
+the doctor telling the truth rather than implying a guard it cannot see.
+
+Posture
+-------
+FAIL-CLOSED. An unparseable payload blocks instead of allowing: a guard that
+opens when it is confused is not a guard. Matching is case-insensitive, because
+Windows and macOS filesystems are.
+"""
 import json
+import re
 import sys
 
+GOLDEN = ".approved"
+
+BLOCK_MSG = (
+    "BLOCKED by INV-GOLDEN-01: the agent may not create, edit, rename or delete an "
+    "approved golden. The approved file is field truth -- a HUMAN signs it. Emit a "
+    ".received instead and stop for human approval."
+)
+
+# Tools that cannot write. Reading a golden is legitimate (golden-diff does it).
+READ_ONLY_TOOLS = {"read", "grep", "glob", "notebookread", "websearch", "webfetch",
+                   "ls", "listdirectory"}
+
+# Shell words that read without modifying. Anything NOT here is treated as a write.
+READ_ONLY_SHELL = {
+    "cat", "less", "more", "head", "tail", "grep", "egrep", "fgrep", "rg", "ag",
+    "diff", "cmp", "wc", "md5sum", "sha1sum", "sha256sum", "shasum", "file", "stat",
+    "od", "xxd", "hexdump", "strings", "awk", "cut", "sort", "uniq", "tr", "column",
+    "echo", "printf", "test", "true", "false", "ls", "find", "basename", "dirname",
+    "git", "python", "python3", "py", "node", "bash", "sh", "env", "which", "type",
+}
+# ... except these, which are how a "reader" still writes.
+WRITE_FLAGS = {"-i", "--in-place", "-o", "--output", "-w", "--write"}
+
+
+def _touches_golden(text):
+    return GOLDEN in str(text).lower()
+
+
+def _bash_writes(command):
+    """True when a shell command plausibly WRITES a golden. Default-deny: anything
+    this cannot prove is read-only counts as a write."""
+    low = command.lower()
+    # any redirection at all in a command naming a golden -- `cat a.approved > b.approved`
+    # starts with a reader and still writes one.
+    if ">" in low:
+        return True
+    if any(w in WRITE_FLAGS for w in low.split()):
+        return True
+    # EVERY segment of the pipeline must start with a known reader. Splitting on the
+    # separators FIRST matters: an earlier version blanked them before looking, so it only
+    # ever saw the first verb and `echo x | tee y.approved` read as a plain `echo`.
+    segments = re.split(r"\|\||&&|[|;&]", low)
+    verbs = []
+    for seg in segments:
+        words = seg.split()
+        if words:
+            verbs.append(words[0].split("/")[-1].split("\\")[-1])
+    if not verbs:
+        return True
+    return not all(v in READ_ONLY_SHELL for v in verbs)
+
+
+def decide(payload):
+    """Return True to BLOCK."""
+    tool = str(payload.get("tool_name", "")).strip().lower()
+    tool_input = payload.get("tool_input")
+    if not isinstance(tool_input, dict):
+        tool_input = {}
+    if tool == "bash" or tool == "shell":
+        command = tool_input.get("command", "")
+        return _touches_golden(command) and _bash_writes(str(command))
+    if tool in READ_ONLY_TOOLS:
+        return False
+    # Any other tool: if a golden appears ANYWHERE in its arguments, block. Unknown
+    # write-capable tools must not slip through just because they are unknown.
+    def walk(v):
+        if isinstance(v, str):
+            return _touches_golden(v)
+        if isinstance(v, dict):
+            return any(walk(x) for x in v.values())
+        if isinstance(v, (list, tuple)):
+            return any(walk(x) for x in v)
+        return False
+    return walk(tool_input)
+
 
 def main():
     try:
         payload = json.load(sys.stdin)
-    except (json.JSONDecodeError, OSError):
-        return 0
-    tool = payload.get("tool_name")
-    target = ""
-    if tool in {"Write", "Edit", "NotebookEdit", "MultiEdit"}:
-        target = str(payload.get("tool_input", {}).get("file_path", ""))
-    elif tool == "Bash":
-        target = str(payload.get("tool_input", {}).get("command", ""))
-    if ".approved" not in target:
-        return 0
-    print("BLOCKED by INV-GOLDEN-01: the agent may not write or rename an .approved golden. Emit a .received instead and stop for human approval.", file=sys.stderr)
-    return 2
+    except Exception:
+        # FAIL-CLOSED: previously this returned 0 (allow), so a malformed payload
+        # silently disabled the guard.
+        print("BLOCKED by INV-GOLDEN-01: the hook could not read its input, so it "
+              "cannot prove this call is safe (fail-closed).", file=sys.stderr)
+        return 2
+    if not isinstance(payload, dict):
+        print("BLOCKED by INV-GOLDEN-01: unexpected hook payload shape (fail-closed).",
+              file=sys.stderr)
+        return 2
+    if decide(payload):
+        print(BLOCK_MSG, file=sys.stderr)
+        return 2
+    return 0
 
 
 if __name__ == "__main__":

package/uscha-kit/install-uscha.py

@@ -807,6 +807,141 @@ def cmd_mirador(args):
         print("\n[uscha mirador] stopped")
 
 
+def settings_without_hook(path):
+    """Return (new_settings, removed_count): the user's settings with OUR PreToolUse entries
+    dropped and nothing else touched. A foreign hook -- including one in the same group -- is
+    preserved; an emptied group disappears rather than being left as an empty shell."""
+    if not path.exists():
+        return None, 0
+    data = load_json(path, "Claude settings.json")
+    if not isinstance(data, dict):
+        raise InstallError("[install-uscha] Claude settings.json must be an object: %s" % path)
+    hooks_data = data.get("hooks")
+    if not isinstance(hooks_data, dict):
+        return None, 0
+    groups = hooks_data.get("PreToolUse")
+    if not isinstance(groups, list):
+        return None, 0
+    removed = 0
+    new_groups = []
+    for group in groups:
+        if not isinstance(group, dict):
+            new_groups.append(group); continue
+        items = group.get("hooks")
+        if not isinstance(items, list):
+            new_groups.append(group); continue
+        keep = []
+        for item in items:
+            c = item.get("command") if isinstance(item, dict) else None
+            if isinstance(c, str) and HOOK_NAME in c:
+                removed += 1
+            else:
+                keep.append(item)
+        if keep:
+            g = dict(group); g["hooks"] = keep; new_groups.append(g)
+        elif not items:
+            new_groups.append(group)          # was already empty; not ours to prune
+    if not removed:
+        return None, 0
+    result = dict(data)
+    hooks = dict(hooks_data)
+    if new_groups:
+        hooks["PreToolUse"] = new_groups
+    else:
+        hooks.pop("PreToolUse", None)
+    if hooks:
+        result["hooks"] = hooks
+    else:
+        result.pop("hooks", None)
+    return result, removed
+
+
+def uninstall_target(target, home, dry_run, operations, force):
+    """Remove one target. Refuses on ambiguity instead of guessing: without OUR marker there is
+    no proof the files at that root are ours, and deleting a stranger's skills would be a far
+    worse bug than leaving ours behind. --force overrides, and says what it assumed."""
+    removed, kept = [], []
+    if target == "codex":
+        root = home / "plugins" / PLUGIN_NAME
+        marker_path = root / "uscha-install.json"
+        market_path = home / ".agents" / "plugins" / "marketplace.json"
+    elif target in SKILL_ROOTS:
+        root = home.joinpath(*SKILL_ROOTS[target])
+        marker_path = root / "uscha-install.json"
+        market_path = None
+    else:
+        root = home / ".claude"
+        marker_path = root / "uscha-install.json"
+        market_path = None
+
+    valid, _ = marker_ok(marker_path, target)
+    if not valid and not force:
+        raise InstallError(
+            "[install-uscha] %s: no uscha install marker at %s -- refusing to delete files this "
+            "kit cannot prove it wrote. Re-run with --force if you are sure." % (target, marker_path))
+
+    def drop(p, why):
+        operations.append({"action": "remove", "path": str(p), "reason": why})
+        if p.exists() or p.is_symlink():
+            if not dry_run:
+                remove_path(p)
+            removed.append(str(p))
+
+    if target == "codex":
+        drop(root, "codex plugin tree (ours: marker verified)")
+        if market_path and market_path.is_file():
+            try:
+                data = load_json(market_path, "marketplace.json")
+                plugins = [p for p in data.get("plugins", []) if p != marketplace_entry()]
+                if len(plugins) != len(data.get("plugins", [])):
+                    data = dict(data); data["plugins"] = plugins
+                    operations.append({"action": "edit", "path": str(market_path),
+                                       "reason": "drop the uscha marketplace entry, keep the rest"})
+                    if not dry_run:
+                        atomic_json(market_path, data)
+                    removed.append(str(market_path) + " (entry)")
+                else:
+                    kept.append(str(market_path) + " (no uscha entry)")
+            except InstallError:
+                kept.append(str(market_path) + " (unreadable, left untouched)")
+    elif target in SKILL_ROOTS:
+        for skill in SKILLS:
+            drop(root / skill, "uscha skill")
+        drop(marker_path, "install marker")
+    else:
+        skills_root = root / "skills"
+        for skill in SKILLS:
+            drop(skills_root / skill, "uscha skill")
+        drop(root / "hooks" / HOOK_NAME, "INV-GOLDEN-01 hook")
+        drop(marker_path, "install marker")
+        settings_path = root / "settings.json"
+        try:
+            new_settings, n = settings_without_hook(settings_path)
+        except InstallError:
+            new_settings, n = None, 0
+            kept.append(str(settings_path) + " (unreadable, left untouched)")
+        if n:
+            operations.append({"action": "edit", "path": str(settings_path),
+                               "reason": "drop %d uscha PreToolUse entry(ies), keep foreign hooks" % n})
+            if not dry_run:
+                atomic_json(settings_path, new_settings)
+            removed.append(str(settings_path) + " (%d hook entry)" % n)
+        else:
+            kept.append(str(settings_path) + " (no uscha hook entry)")
+    return {"removed": removed, "kept": kept}
+
+
+def cmd_uninstall(args):
+    home, operations, result = home_path(args), [], {}
+    for target in selected_targets(args.target):
+        result[target] = uninstall_target(target, home, args.dry_run, operations, args.force)
+    emit({"status": "planned" if args.dry_run else "uninstalled", "dry_run": args.dry_run,
+          "home": str(home), "targets": result, "operations": operations,
+          "next": ["Run: python install-uscha.py doctor --target %s" % args.target,
+                   "Your own files were left alone: only paths this kit wrote are removed."]},
+         args.json)
+
+
 def next_steps(target):
     picked = selected_targets(target)   # resolves both/all so each installed target speaks
     steps = []
@@ -826,7 +961,16 @@ def next_steps(target):
 def emit(data, as_json):
     if as_json:
         print(json.dumps(data, indent=2, ensure_ascii=False)); return
-    if "targets" in data and isinstance(data["targets"], dict):
+    # uninstall also reports per-target, but with removed/kept instead of health -- match on
+    # the SHAPE, not just the key name, or a payload that merely has "targets" crashes here.
+    if data.get("status") in ("uninstalled", "planned") and isinstance(data.get("targets"), dict):
+        print("Uscha uninstall%s" % ("  (dry-run: nothing was touched)" if data.get("dry_run") else ""))
+        for name, res in data["targets"].items():
+            print("  %-8s removed %d, left alone %d" % (name, len(res.get("removed", [])), len(res.get("kept", []))))
+        for k in res.get("kept", []) if data["targets"] else []:
+            print("     kept: %s" % k)
+    elif ("targets" in data and isinstance(data["targets"], dict)
+            and all(isinstance(v, dict) and "healthy" in v for v in data["targets"].values())):
         print("Uscha %s" % data.get("source_version"))
         for name, status in data["targets"].items(): print("  %s %s" % ("OK" if status["healthy"] else "WARN", name))
     elif "operations" in data:
@@ -846,6 +990,13 @@ def build_parser():
     doctor.add_argument("--target", choices=list(TARGETS) + ["both", "all"], default="both"); doctor.add_argument("--home"); doctor.add_argument("--json", action="store_true"); doctor.set_defaults(func=cmd_doctor)
     init = sub.add_parser("init", help="prepare a repo with Uscha config/templates")
     init.add_argument("--repo", default="."); init.add_argument("--force", action="store_true", help="replace differing init files deliberately"); init.add_argument("--dry-run", action="store_true"); init.add_argument("--json", action="store_true"); init.set_defaults(func=cmd_init)
+    uninstall = sub.add_parser("uninstall", help="remove what this kit installed, and nothing else")
+    uninstall.add_argument("--target", choices=list(TARGETS) + ["both", "all"], default="both")
+    uninstall.add_argument("--home"); uninstall.add_argument("--dry-run", action="store_true")
+    uninstall.add_argument("--json", action="store_true")
+    uninstall.add_argument("--force", action="store_true",
+                           help="remove even without an install marker (you assert the files are ours)")
+    uninstall.set_defaults(func=cmd_uninstall)
     mirador = sub.add_parser("mirador", help="render + open the project's mirador dashboard from QA-LEDGER.json")
     mirador.add_argument("--ledger", default="QA-LEDGER.json", help="ledger to read (default: the QA-LEDGER.json convention)")
     mirador.add_argument("--out", default="mirador.html")

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.55.0",
+  "version": "1.56.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,