@andresmassello/uscha 1.61.0 → 1.63.0

package/README.md

@@ -40,7 +40,7 @@ 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.61.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.63.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
 [changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG.md)
 (the per-release changelogs live in the repo, not in the npm tarball)
 
@@ -76,7 +76,7 @@ and see which file, which test, and when.
 | `/uscha-mirador` | Bird's-eye HTML dashboard: readiness, trail, acceptance, loops |
 | `/uscha-status` | One-line progress readout, in chat |
 
-**A measurement engine** (`qa_ledger.py`, 32 subcommands, Python stdlib) that ingests
+**A measurement engine** (`qa_ledger.py`, 33 subcommands, Python stdlib) that ingests
 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "1.61.0",
+  "version": "1.63.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",

package/uscha-kit/.claude/skills/uscha-devloop/qa_ledger.py

@@ -2629,6 +2629,35 @@ def _derive_phase(ledger, name, node, k, qa_order):
         reasons.append("la evidencia medida no contiene tests ejecutados")
     _go, sev = _gate_open_and_sev(node)
     blk = sev.get("BLOCKER", 0) + sev.get("CRITICAL", 0)
+    # clean-room gate (ADR-008). OPT-IN: no clean_room block, or mode "off", and this does not
+    # exist -- behavior identical to earlier releases. Declared "final": pr-ready additionally
+    # requires clean-room evidence that is GREEN and pinned to the CURRENT HEAD. A new commit
+    # makes the previous run stale for the gate, the same staleness posture the rest of the
+    # engine takes: evidence certifies the thing it was measured against, nothing later.
+    _cr = _cr_cfg(ledger)
+    if _cr and _cr.get("mode") == "final":
+        _head = None
+        _hr = None
+        _crcfg = (_repo_cfg(ledger, name) if name != "integration"
+                  else {"path": "."})          # synthetic scope: never in config["repos"]
+        try:
+            _hr = subprocess.run(["git", "rev-parse", "HEAD"],
+                                 cwd=_crcfg.get("path", "."),
+                                 capture_output=True, text=True, encoding="utf-8",
+                                 errors="replace")
+        except OSError:
+            _hr = None
+        if _hr is not None and _hr.returncode == 0:
+            _head = _hr.stdout.strip()
+        _run = _cr_latest(ledger, name, _head) if _head else None
+        if not _head:
+            reasons.append("clean-room declarado pero no se pudo resolver HEAD "
+                           "(no se mide, no se aprueba)")
+            conv = False
+        elif not _run or not _run.get("ok"):
+            reasons.append("falta clean-room verde para %s (evidencia del arbol no "
+                           "certifica el commit)" % _head[:8])
+            conv = False
     if conv and tests_measured_green and not tests_red and blk == 0:
         evidence = ["ciclo de agente limpio", "tests verdes (medidos)",
                     "0 BLOCKER/CRITICAL abiertos"]
@@ -3026,7 +3055,7 @@ def _sd_governs(path):
         return None
     if not lines or lines[0].strip() != "---":
         return None
-    globs, in_governs = None, False
+    globs, in_governs, explicit_empty = None, False, False
     # scan runs to the CLOSING fence, not an arbitrary window -- a governs: key late in a
     # long frontmatter block must not silently read as UNMAPPED (fresh-review finding).
     for ln in lines[1:]:
@@ -3038,6 +3067,8 @@ def _sd_governs(path):
             if rest.startswith("[") and rest.endswith("]"):
                 globs = [x.strip().strip("\x27\x22")
                          for x in rest[1:-1].split(",") if x.strip()]
+                # only an INLINE [] is a declaration of "nothing to govern"
+                explicit_empty = not globs
                 in_governs = False
             elif rest:
                 # bare scalar (`governs: src/**`) -- a plausible authoring shorthand;
@@ -3051,6 +3082,11 @@ def _sd_governs(path):
                 globs.append(s[2:].strip().strip("\x27\x22"))
             elif s and not ln.startswith((" ", "\t")):
                 in_governs = False
+    if globs == [] and not explicit_empty:
+        # a `governs:` key with nothing usable under it (a placeholder, a comment, a typo) is
+        # an UNFINISHED declaration, not a statement that this spec governs nothing. Report it
+        # as UNMAPPED, which is what it is (fresh-review finding).
+        return None
     return globs
 
 
@@ -3111,6 +3147,16 @@ def cmd_spec_drift(args):
             row.update({"verdict": "UNMAPPED", "reason": "no governs: frontmatter"})
             results.append(row)
             continue
+        if not governs:
+            # An EXPLICIT empty list is a declaration, not an omission: this decision governs
+            # no code and never will. Negative ADRs ("we are NOT doing X, and why") are a
+            # documented practice in this kit, and reporting them UNMAPPED forever turns a
+            # correct state into permanent noise -- which is how an advisory gets ignored.
+            # Found by running spec-drift on this repo's own ADR-004.
+            row.update({"verdict": "NO-CODE",
+                        "reason": "declares governs: [] -- a decision that governs no code"})
+            results.append(row)
+            continue
         matched = []
         pats = [_fp_glob_re(g) for g in governs]
         for f in tracked:
@@ -3171,7 +3217,8 @@ def cmd_spec_drift(args):
         print("SPEC-DRIFT %s (advisory, lag > %dd):" % (args.repo, lag_days))
         if not results:
             print("  no spec documents found (SPEC.md / docs/adr/*.md)")
-        mark = {"SPEC_STALE": "!!", "CLEAN": "ok", "UNMAPPED": "--", "UNTRACKED": "--"}
+        mark = {"SPEC_STALE": "!!", "CLEAN": "ok", "UNMAPPED": "--", "UNTRACKED": "--",
+                "NO-CODE": "ok"}
         for r_ in results:
             line = "  %s %s: %s" % (mark.get(r_["verdict"], "??"), r_["file"],
                                     r_["verdict"])
@@ -3337,6 +3384,132 @@ def cmd_golden_coverage(args):
 
 
 
+# --------------------------------------------------------------------------- #
+# cleanroom  (ADR-008: verify the COMMIT, not the tree -- opt-in, human-supplied command)
+# --------------------------------------------------------------------------- #
+
+CLEAN_ROOM_KEY = "clean_room"
+
+
+def _cr_cfg(ledger):
+    cfg = ledger["config"].get("defaults", {}).get(CLEAN_ROOM_KEY)
+    return cfg if isinstance(cfg, dict) else None
+
+
+def _cr_latest(ledger, repo, ref=None):
+    """Latest clean-room record for a repo, optionally pinned to one ref."""
+    runs = [e for e in ledger.get(CLEAN_ROOM_KEY, [])
+            if e.get("repo") == repo and (ref is None or e.get("ref") == ref)]
+    return runs[-1] if runs else None
+
+
+def cmd_cleanroom(args):
+    """Run a command against a CLEAN CHECKOUT of one commit, in a throwaway worktree.
+
+    Evidence produced in the maker's tree is true of the TREE; this produces evidence true
+    of the COMMIT. As a side effect maker != checker becomes physical: the worktree cannot
+    see uncommitted state.
+
+    The engine does NOT decide what to run. The command arrives explicitly via --run, the
+    same contract golden-coverage uses for --harness: the engine owns what it can guarantee
+    (isolation, the SHA binding, cleanup) and never guesses what a project's suite is.
+    Reading test_command_* from config and executing it would make the engine an executor
+    of config-supplied shell, which it is not (ADR-008)."""
+    import time
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+
+    def git(*a, **kw):
+        cwd = kw.pop("cwd", repo_path)
+        try:
+            return subprocess.run(["git"] + list(a), cwd=cwd, capture_output=True,
+                                  text=True, encoding="utf-8", errors="replace")
+        except OSError:
+            return None
+
+    rev = git("rev-parse", "--verify", (args.ref or "HEAD") + "^{commit}")
+    if rev is None or rev.returncode != 0 or not rev.stdout.strip():
+        print("[qa_ledger] cannot resolve ref %r in %s - nothing to verify."
+              % (args.ref or "HEAD", repo_path), file=sys.stderr)
+        sys.exit(2)
+    sha = rev.stdout.strip()
+
+    wt = tempfile.mkdtemp(prefix="uscha-cleanroom-")
+    target = os.path.join(wt, "tree")
+    started = time.time()
+    record = {"repo": args.repo, "ref": sha, "at": _now(), "ok": False,
+              "status": None, "wall_ms": None, "worktree_sha": None}
+    keep = bool((_cr_cfg(ledger) or {}).get("keep_worktree_on_failure"))
+    try:
+        add = git("worktree", "add", "--detach", target, sha)
+        if add is None or add.returncode != 0:
+            record["status"] = "WORKTREE_FAILED"
+            print("[qa_ledger] git worktree add failed:\n%s"
+                  % ((add.stderr if add else "git unavailable") or "")[-800:], file=sys.stderr)
+        else:
+            # a worktree of a commit must be clean by construction; if it is not, something
+            # (a smudge filter, a hook, a stale index) intervened and the isolation claim is
+            # already false. Say so rather than measure in it.
+            st = git("status", "--porcelain", cwd=target)
+            if st is None or st.returncode != 0 or st.stdout.strip():
+                record["status"] = "WORKTREE_DIRTY"
+            else:
+                record["worktree_sha"] = sha
+                if args.setup:
+                    r = subprocess.run(args.setup, cwd=target, shell=True,
+                                       capture_output=True, text=True,
+                                       encoding="utf-8", errors="replace")
+                    if r.returncode != 0:
+                        record["status"] = "SETUP_FAILED"
+                        print((r.stderr or "")[-800:], file=sys.stderr)
+                if record["status"] is None:
+                    r = subprocess.run(args.run, cwd=target, shell=True,
+                                       capture_output=True, text=True,
+                                       encoding="utf-8", errors="replace")
+                    record["exit_code"] = r.returncode
+                    record["status"] = "GREEN" if r.returncode == 0 else "RED"
+                    record["ok"] = r.returncode == 0
+                    if r.returncode != 0:
+                        print((r.stdout or "")[-1500:], file=sys.stderr)
+    finally:
+        record["wall_ms"] = int((time.time() - started) * 1000)
+        # Cleanup is unconditional unless the human asked to inspect a FAILURE: a zombie
+        # worktree is a defect, and `git worktree remove` alone leaves the admin entry behind.
+        if record["ok"] or not keep:
+            git("worktree", "remove", "--force", target)
+            git("worktree", "prune")
+            shutil.rmtree(wt, ignore_errors=True)
+            # VERIFY the removal instead of assuming it. rmtree(ignore_errors=True) and a
+            # discarded git return code can both fail in silence -- typically on Windows,
+            # where a handle the caller's command left open blocks removal.
+            if os.path.exists(target):
+                record["cleanup_failed"] = True
+                record["worktree_kept_at"] = target
+                print("[qa_ledger] WARNING: the clean-room worktree could not be removed and "
+                      "is still at %s (a process may still hold a handle). Remove it with: "
+                      "git worktree remove --force %s && git worktree prune"
+                      % (target, target), file=sys.stderr)
+        else:
+            record["worktree_kept_at"] = target
+
+    ledger.setdefault(CLEAN_ROOM_KEY, []).append(record)
+    ledger["step_counter"] += 1
+    ledger["steps"].append({"n": ledger["step_counter"], "at": _now(),
+                            "kind": "cleanroom", "repo": args.repo})
+    _save(args.ledger, ledger)
+
+    if args.json:
+        print(json.dumps(record, indent=2, ensure_ascii=False))
+    else:
+        print("CLEANROOM %s @ %s: %s (%.1fs)"
+              % (args.repo, sha[:8], record["status"], (record["wall_ms"] or 0) / 1000.0))
+        if record.get("worktree_kept_at"):
+            print("  worktree kept for inspection: " + record["worktree_kept_at"])
+    sys.exit(0 if record["ok"] else 1)
+
+
+
 def cmd_escalate(args):
     ledger = _load(args.ledger)
     _repo_node(ledger, args.repo)
@@ -4383,6 +4556,9 @@ def cmd_dashboard(args):
             _org[_rn] = _snaps[-1]["origin"]
     if _org:
         out["evidence_origin"] = _org
+    if ledger.get(CLEAN_ROOM_KEY):
+        out["clean_room"] = {r: [e for e in ledger[CLEAN_ROOM_KEY] if e.get("repo") == r][-1]
+                             for r in {e.get("repo") for e in ledger[CLEAN_ROOM_KEY]}}
     if getattr(args, "json", False):
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return
@@ -7087,6 +7263,17 @@ def build_parser():
     pfp.add_argument("--json", action="store_true")
     pfp.set_defaults(func=cmd_fastpath_eval)
 
+    pcr = sub.add_parser("cleanroom",
+                         help="run a command against a CLEAN checkout of one commit in a throwaway worktree (ADR-008)")
+    pcr.add_argument("--ledger", default="QA-LEDGER.json")
+    pcr.add_argument("--repo", required=True)
+    pcr.add_argument("--ref", default=None, help="commit to verify; default HEAD")
+    pcr.add_argument("--run", required=True,
+                     help="the command to run inside the worktree; the engine never guesses it")
+    pcr.add_argument("--setup", default=None, help="optional bootstrap before --run (e.g. npm ci)")
+    pcr.add_argument("--json", action="store_true")
+    pcr.set_defaults(func=cmd_cleanroom)
+
     pgc = sub.add_parser("golden-coverage",
                          help="record the MEASURED source files a golden's harness exercises (ADR-006)")
     pgc.add_argument("--harness", required=True, help="script that drives the subject")

package/uscha-kit/.claude/skills/uscha-mirador/SKILL.md

@@ -71,7 +71,7 @@ than inventing a step. Keep the CONTENT in the conversation's language and the l
   repo straight from the ledger, or null when none was requested. The template degrades when
   absent, like every other field.
 - **Spec-drift (ADR-005):** `dashboard --json` carries `spec_drift` — the latest advisory
-  run (per-document verdicts: SPEC_STALE / CLEAN / UNMAPPED / UNTRACKED) — only when a run
+  run (per-document verdicts: SPEC_STALE / CLEAN / UNMAPPED / UNTRACKED / NO-CODE) — only when a run
   exists in the ledger; a virgin ledger keeps the exact prior schema. Advisory visibility of
   the spec-maintenance tax, never readiness input.
 - **Modes card:** the template draws one card for both modes — fast-path verdict chips per

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

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.61.0",
+  "version": "1.63.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, 32 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
+  "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, 33 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {
     "name": "Andres Massello",
     "url": "https://github.com/andresmassello"

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

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "1.61.0",
+  "version": "1.63.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.61.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.63.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`,
@@ -123,7 +123,8 @@ Per document: **`SPEC_STALE`** when governed code outran the spec by more than
 `defaults.spec_drift.max_lag_days` (default 30), listing the newer files; **`CLEAN`** when it
 did not; **`UNMAPPED`** when there is no `governs:` frontmatter *or its globs match nothing*
 — absence of a mapping is absence of measurement, not "no drift"; **`UNTRACKED`** when the
-spec has no commit date to compare. The latest run lands in the ledger (`spec_drift`) so the
+spec has no commit date to compare; **`NO-CODE`** when it declares `governs: []`, i.e. a
+decision that governs no source (negative ADRs) — a declaration, not an omission. The latest run lands in the ledger (`spec_drift`) so the
 mirador can surface it. No readiness impact, no exit-code gate: a stale spec is a prompt for
 a human conversation, not a blocked pipeline.
 
@@ -148,6 +149,35 @@ knowing a tree was dirty does not tell you the evidence is wrong, only that it w
 produced from a commit alone. The git-worktree clean-room that would answer the stronger
 question is deliberately deferred; ADR-007 records why.
 
+## Clean-room (ADR-008) - verify the commit, not your tree
+
+A suite can pass in your working tree *because of uncommitted state* and fail against the
+commit alone. The ledger records that as measured, with provenance true of the TREE and not of
+the COMMIT that will merge.
+
+```bash
+python qa_ledger.py cleanroom --repo <name> --run "<your test command>" [--setup "npm ci"]
+```
+
+It creates a detached `git worktree` of the commit, verifies it is clean by construction, runs
+what you gave it, records `ref` / `worktree_sha` / `status` / wall-clock, and removes the
+worktree unconditionally (a zombie worktree is a defect). Status is specific:
+`GREEN`, `RED`, `SETUP_FAILED` (a bootstrap failure is not a failing suite),
+`WORKTREE_FAILED`, `WORKTREE_DIRTY`.
+
+**The engine never decides what to run.** The command arrives via `--run`, the same contract
+`golden-coverage` uses for `--harness`: the engine owns isolation, the SHA binding and
+cleanup, and never turns a config file into a code-execution surface. That is also why it
+works for any stack - it never had to know the stack.
+
+**Opt-in gate:** `defaults.clean_room.mode` absent or `"off"` and nothing changes. `"final"`
+makes `pr-ready` require a GREEN run pinned to the current HEAD; a new commit makes the
+previous run stale for the gate.
+
+Honest limit: this is **not** a substitute for CI. A local worktree runs on your machine, your
+OS, your shell - environment variance is invisible to it. Different failure class, different
+instrument.
+
 ## End-to-end flow
 
 `uscha-discovery` is the front for something new (you only have the idea); `uscha-adr-refine` is the front

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.61.0
+uscha-kit 1.63.0

package/uscha-kit/reports/junit/.cleanroom-cases.json

@@ -0,0 +1 @@
+{"AC-CR-06": true, "AC-CR-02": true, "AC-CR-04": true, "AC-CR-05": true, "AC-CR-03": true, "AC-CR-01": true, "AC-CR-07": true, "AC-CR-08": true}

package/uscha-kit/reports/junit/.specdrift-cases.json

@@ -1 +1 @@
-{"AC-SD-01": true, "AC-SD-03": true, "AC-SD-02": true, "AC-SD-04": true}
+{"AC-SD-01": true, "AC-SD-03": true, "AC-SD-05": true, "AC-SD-02": true, "AC-SD-04": true}

package/uscha-kit/skills/uscha-devloop/qa_ledger.py

@@ -2629,6 +2629,35 @@ def _derive_phase(ledger, name, node, k, qa_order):
         reasons.append("la evidencia medida no contiene tests ejecutados")
     _go, sev = _gate_open_and_sev(node)
     blk = sev.get("BLOCKER", 0) + sev.get("CRITICAL", 0)
+    # clean-room gate (ADR-008). OPT-IN: no clean_room block, or mode "off", and this does not
+    # exist -- behavior identical to earlier releases. Declared "final": pr-ready additionally
+    # requires clean-room evidence that is GREEN and pinned to the CURRENT HEAD. A new commit
+    # makes the previous run stale for the gate, the same staleness posture the rest of the
+    # engine takes: evidence certifies the thing it was measured against, nothing later.
+    _cr = _cr_cfg(ledger)
+    if _cr and _cr.get("mode") == "final":
+        _head = None
+        _hr = None
+        _crcfg = (_repo_cfg(ledger, name) if name != "integration"
+                  else {"path": "."})          # synthetic scope: never in config["repos"]
+        try:
+            _hr = subprocess.run(["git", "rev-parse", "HEAD"],
+                                 cwd=_crcfg.get("path", "."),
+                                 capture_output=True, text=True, encoding="utf-8",
+                                 errors="replace")
+        except OSError:
+            _hr = None
+        if _hr is not None and _hr.returncode == 0:
+            _head = _hr.stdout.strip()
+        _run = _cr_latest(ledger, name, _head) if _head else None
+        if not _head:
+            reasons.append("clean-room declarado pero no se pudo resolver HEAD "
+                           "(no se mide, no se aprueba)")
+            conv = False
+        elif not _run or not _run.get("ok"):
+            reasons.append("falta clean-room verde para %s (evidencia del arbol no "
+                           "certifica el commit)" % _head[:8])
+            conv = False
     if conv and tests_measured_green and not tests_red and blk == 0:
         evidence = ["ciclo de agente limpio", "tests verdes (medidos)",
                     "0 BLOCKER/CRITICAL abiertos"]
@@ -3026,7 +3055,7 @@ def _sd_governs(path):
         return None
     if not lines or lines[0].strip() != "---":
         return None
-    globs, in_governs = None, False
+    globs, in_governs, explicit_empty = None, False, False
     # scan runs to the CLOSING fence, not an arbitrary window -- a governs: key late in a
     # long frontmatter block must not silently read as UNMAPPED (fresh-review finding).
     for ln in lines[1:]:
@@ -3038,6 +3067,8 @@ def _sd_governs(path):
             if rest.startswith("[") and rest.endswith("]"):
                 globs = [x.strip().strip("\x27\x22")
                          for x in rest[1:-1].split(",") if x.strip()]
+                # only an INLINE [] is a declaration of "nothing to govern"
+                explicit_empty = not globs
                 in_governs = False
             elif rest:
                 # bare scalar (`governs: src/**`) -- a plausible authoring shorthand;
@@ -3051,6 +3082,11 @@ def _sd_governs(path):
                 globs.append(s[2:].strip().strip("\x27\x22"))
             elif s and not ln.startswith((" ", "\t")):
                 in_governs = False
+    if globs == [] and not explicit_empty:
+        # a `governs:` key with nothing usable under it (a placeholder, a comment, a typo) is
+        # an UNFINISHED declaration, not a statement that this spec governs nothing. Report it
+        # as UNMAPPED, which is what it is (fresh-review finding).
+        return None
     return globs
 
 
@@ -3111,6 +3147,16 @@ def cmd_spec_drift(args):
             row.update({"verdict": "UNMAPPED", "reason": "no governs: frontmatter"})
             results.append(row)
             continue
+        if not governs:
+            # An EXPLICIT empty list is a declaration, not an omission: this decision governs
+            # no code and never will. Negative ADRs ("we are NOT doing X, and why") are a
+            # documented practice in this kit, and reporting them UNMAPPED forever turns a
+            # correct state into permanent noise -- which is how an advisory gets ignored.
+            # Found by running spec-drift on this repo's own ADR-004.
+            row.update({"verdict": "NO-CODE",
+                        "reason": "declares governs: [] -- a decision that governs no code"})
+            results.append(row)
+            continue
         matched = []
         pats = [_fp_glob_re(g) for g in governs]
         for f in tracked:
@@ -3171,7 +3217,8 @@ def cmd_spec_drift(args):
         print("SPEC-DRIFT %s (advisory, lag > %dd):" % (args.repo, lag_days))
         if not results:
             print("  no spec documents found (SPEC.md / docs/adr/*.md)")
-        mark = {"SPEC_STALE": "!!", "CLEAN": "ok", "UNMAPPED": "--", "UNTRACKED": "--"}
+        mark = {"SPEC_STALE": "!!", "CLEAN": "ok", "UNMAPPED": "--", "UNTRACKED": "--",
+                "NO-CODE": "ok"}
         for r_ in results:
             line = "  %s %s: %s" % (mark.get(r_["verdict"], "??"), r_["file"],
                                     r_["verdict"])
@@ -3337,6 +3384,132 @@ def cmd_golden_coverage(args):
 
 
 
+# --------------------------------------------------------------------------- #
+# cleanroom  (ADR-008: verify the COMMIT, not the tree -- opt-in, human-supplied command)
+# --------------------------------------------------------------------------- #
+
+CLEAN_ROOM_KEY = "clean_room"
+
+
+def _cr_cfg(ledger):
+    cfg = ledger["config"].get("defaults", {}).get(CLEAN_ROOM_KEY)
+    return cfg if isinstance(cfg, dict) else None
+
+
+def _cr_latest(ledger, repo, ref=None):
+    """Latest clean-room record for a repo, optionally pinned to one ref."""
+    runs = [e for e in ledger.get(CLEAN_ROOM_KEY, [])
+            if e.get("repo") == repo and (ref is None or e.get("ref") == ref)]
+    return runs[-1] if runs else None
+
+
+def cmd_cleanroom(args):
+    """Run a command against a CLEAN CHECKOUT of one commit, in a throwaway worktree.
+
+    Evidence produced in the maker's tree is true of the TREE; this produces evidence true
+    of the COMMIT. As a side effect maker != checker becomes physical: the worktree cannot
+    see uncommitted state.
+
+    The engine does NOT decide what to run. The command arrives explicitly via --run, the
+    same contract golden-coverage uses for --harness: the engine owns what it can guarantee
+    (isolation, the SHA binding, cleanup) and never guesses what a project's suite is.
+    Reading test_command_* from config and executing it would make the engine an executor
+    of config-supplied shell, which it is not (ADR-008)."""
+    import time
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+
+    def git(*a, **kw):
+        cwd = kw.pop("cwd", repo_path)
+        try:
+            return subprocess.run(["git"] + list(a), cwd=cwd, capture_output=True,
+                                  text=True, encoding="utf-8", errors="replace")
+        except OSError:
+            return None
+
+    rev = git("rev-parse", "--verify", (args.ref or "HEAD") + "^{commit}")
+    if rev is None or rev.returncode != 0 or not rev.stdout.strip():
+        print("[qa_ledger] cannot resolve ref %r in %s - nothing to verify."
+              % (args.ref or "HEAD", repo_path), file=sys.stderr)
+        sys.exit(2)
+    sha = rev.stdout.strip()
+
+    wt = tempfile.mkdtemp(prefix="uscha-cleanroom-")
+    target = os.path.join(wt, "tree")
+    started = time.time()
+    record = {"repo": args.repo, "ref": sha, "at": _now(), "ok": False,
+              "status": None, "wall_ms": None, "worktree_sha": None}
+    keep = bool((_cr_cfg(ledger) or {}).get("keep_worktree_on_failure"))
+    try:
+        add = git("worktree", "add", "--detach", target, sha)
+        if add is None or add.returncode != 0:
+            record["status"] = "WORKTREE_FAILED"
+            print("[qa_ledger] git worktree add failed:\n%s"
+                  % ((add.stderr if add else "git unavailable") or "")[-800:], file=sys.stderr)
+        else:
+            # a worktree of a commit must be clean by construction; if it is not, something
+            # (a smudge filter, a hook, a stale index) intervened and the isolation claim is
+            # already false. Say so rather than measure in it.
+            st = git("status", "--porcelain", cwd=target)
+            if st is None or st.returncode != 0 or st.stdout.strip():
+                record["status"] = "WORKTREE_DIRTY"
+            else:
+                record["worktree_sha"] = sha
+                if args.setup:
+                    r = subprocess.run(args.setup, cwd=target, shell=True,
+                                       capture_output=True, text=True,
+                                       encoding="utf-8", errors="replace")
+                    if r.returncode != 0:
+                        record["status"] = "SETUP_FAILED"
+                        print((r.stderr or "")[-800:], file=sys.stderr)
+                if record["status"] is None:
+                    r = subprocess.run(args.run, cwd=target, shell=True,
+                                       capture_output=True, text=True,
+                                       encoding="utf-8", errors="replace")
+                    record["exit_code"] = r.returncode
+                    record["status"] = "GREEN" if r.returncode == 0 else "RED"
+                    record["ok"] = r.returncode == 0
+                    if r.returncode != 0:
+                        print((r.stdout or "")[-1500:], file=sys.stderr)
+    finally:
+        record["wall_ms"] = int((time.time() - started) * 1000)
+        # Cleanup is unconditional unless the human asked to inspect a FAILURE: a zombie
+        # worktree is a defect, and `git worktree remove` alone leaves the admin entry behind.
+        if record["ok"] or not keep:
+            git("worktree", "remove", "--force", target)
+            git("worktree", "prune")
+            shutil.rmtree(wt, ignore_errors=True)
+            # VERIFY the removal instead of assuming it. rmtree(ignore_errors=True) and a
+            # discarded git return code can both fail in silence -- typically on Windows,
+            # where a handle the caller's command left open blocks removal.
+            if os.path.exists(target):
+                record["cleanup_failed"] = True
+                record["worktree_kept_at"] = target
+                print("[qa_ledger] WARNING: the clean-room worktree could not be removed and "
+                      "is still at %s (a process may still hold a handle). Remove it with: "
+                      "git worktree remove --force %s && git worktree prune"
+                      % (target, target), file=sys.stderr)
+        else:
+            record["worktree_kept_at"] = target
+
+    ledger.setdefault(CLEAN_ROOM_KEY, []).append(record)
+    ledger["step_counter"] += 1
+    ledger["steps"].append({"n": ledger["step_counter"], "at": _now(),
+                            "kind": "cleanroom", "repo": args.repo})
+    _save(args.ledger, ledger)
+
+    if args.json:
+        print(json.dumps(record, indent=2, ensure_ascii=False))
+    else:
+        print("CLEANROOM %s @ %s: %s (%.1fs)"
+              % (args.repo, sha[:8], record["status"], (record["wall_ms"] or 0) / 1000.0))
+        if record.get("worktree_kept_at"):
+            print("  worktree kept for inspection: " + record["worktree_kept_at"])
+    sys.exit(0 if record["ok"] else 1)
+
+
+
 def cmd_escalate(args):
     ledger = _load(args.ledger)
     _repo_node(ledger, args.repo)
@@ -4383,6 +4556,9 @@ def cmd_dashboard(args):
             _org[_rn] = _snaps[-1]["origin"]
     if _org:
         out["evidence_origin"] = _org
+    if ledger.get(CLEAN_ROOM_KEY):
+        out["clean_room"] = {r: [e for e in ledger[CLEAN_ROOM_KEY] if e.get("repo") == r][-1]
+                             for r in {e.get("repo") for e in ledger[CLEAN_ROOM_KEY]}}
     if getattr(args, "json", False):
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return
@@ -7087,6 +7263,17 @@ def build_parser():
     pfp.add_argument("--json", action="store_true")
     pfp.set_defaults(func=cmd_fastpath_eval)
 
+    pcr = sub.add_parser("cleanroom",
+                         help="run a command against a CLEAN checkout of one commit in a throwaway worktree (ADR-008)")
+    pcr.add_argument("--ledger", default="QA-LEDGER.json")
+    pcr.add_argument("--repo", required=True)
+    pcr.add_argument("--ref", default=None, help="commit to verify; default HEAD")
+    pcr.add_argument("--run", required=True,
+                     help="the command to run inside the worktree; the engine never guesses it")
+    pcr.add_argument("--setup", default=None, help="optional bootstrap before --run (e.g. npm ci)")
+    pcr.add_argument("--json", action="store_true")
+    pcr.set_defaults(func=cmd_cleanroom)
+
     pgc = sub.add_parser("golden-coverage",
                          help="record the MEASURED source files a golden's harness exercises (ADR-006)")
     pgc.add_argument("--harness", required=True, help="script that drives the subject")

package/uscha-kit/skills/uscha-mirador/SKILL.md

@@ -71,7 +71,7 @@ than inventing a step. Keep the CONTENT in the conversation's language and the l
   repo straight from the ledger, or null when none was requested. The template degrades when
   absent, like every other field.
 - **Spec-drift (ADR-005):** `dashboard --json` carries `spec_drift` — the latest advisory
-  run (per-document verdicts: SPEC_STALE / CLEAN / UNMAPPED / UNTRACKED) — only when a run
+  run (per-document verdicts: SPEC_STALE / CLEAN / UNMAPPED / UNTRACKED / NO-CODE) — only when a run
   exists in the ledger; a virgin ledger keeps the exact prior schema. Advisory visibility of
   the spec-maintenance tax, never readiness input.
 - **Modes card:** the template draws one card for both modes — fast-path verdict chips per

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.61.0",
+  "version": "1.63.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,
@@ -55,6 +55,10 @@
     "spec_drift": {
       "max_lag_days": 30
     },
+    "clean_room": {
+      "mode": "off",
+      "keep_worktree_on_failure": false
+    },
     "static_gate_zero_at": 10,
     "constitution_file": "CONSTITUTION.md",
     "rebuild": {