@andresmassello/uscha 1.56.0 → 1.59.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.56.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
-[changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG-1.56.0.md)
+**Kit v1.59.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`, 29 subcommands, Python stdlib) that ingests
+**A measurement engine** (`qa_ledger.py`, 31 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.56.0",
+  "version": "1.59.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",
@@ -18,6 +18,7 @@
     "!uscha-kit/**/*.pyc",
     "!uscha-kit/**/*.pyo",
     "!uscha-kit/CHANGELOG-*.md",
+    "!uscha-kit/CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],

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

@@ -169,6 +169,27 @@ install `hooks/block-approved-writes.py` as a `PreToolUse` hook in
 `settings.json`, and add `*.approved.* binary` to `.gitattributes` (ships in
 `templates/.gitattributes`) so line endings can't lie in the byte-compare.
 
+## Phase 0a — Fast-path check (ADR-003; run FIRST, before planning ceremony)
+
+If `defaults.fast_path` exists in config, run the measured classifier before demanding a
+full spec package:
+
+```bash
+python qa_ledger.py fastpath-eval --repo <name> --json          # dry-run first
+```
+
+- **ALLOW** and the operator wants the shortcut: re-run with
+  `--intent "<one sentence: what and why>"` to record it, then skip Phase 0's full-package
+  demand. The micro-contract replaces it: the recorded INTENT plus at least one new/modified
+  asserting test (readiness stays capped until that test shows up in measured evidence).
+- **DENY**: state WHICH measured signal denied it — echo the engine's breakdown verbatim.
+  The skill wires; it never computes and never argues with the verdict. Proceed with the
+  normal full path. The operator may always choose the full path over an ALLOW; nothing —
+  operator, agent or flag — can force ALLOW over a DENY (INV-RIGOR-02).
+- **Re-evaluate before the PR step** (same command, same intent): thresholds exceeded mid-run
+  flip the run to `ESCALATED` — the derived phase blocks pr-ready and readiness is capped.
+  Produce the ADR + ACCEPTANCE the change turned out to deserve, then `resolve-escalation`.
+
 ## Phase 0 — Plan (ADR-first)
 
 - **Read `CONSTITUTION.md` first (if present).** It lists the project invariants no SPEC

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

@@ -59,6 +59,7 @@ import math
 import os
 import re
 import shutil
+import subprocess
 import sys
 import unicodedata
 import xml.etree.ElementTree as ET
@@ -96,6 +97,36 @@ SOURCE_EXT = {
 # --------------------------------------------------------------------------- #
 # ledger io
 # --------------------------------------------------------------------------- #
+# Reports come from the user's build, not from us, and the engine is stdlib-only by contract --
+# `defusedxml` is not available. A byte ceiling is the honest mitigation for the realistic
+# failure (a runaway or hostile report exhausting memory on the operator's own machine). It is
+# NOT protection against a determined attacker: entity expansion inside the ceiling still
+# expands. SECURITY.md says so rather than implying the parser is hardened.
+MAX_REPORT_BYTES = 64 * 1024 * 1024      # 64 MB: orders of magnitude above any real JUnit run
+
+
+class ReportTooLarge(Exception):
+    pass
+
+
+def _parse_xml(source):
+    """ET.parse with a size ceiling. Accepts a path or an open binary/text file object."""
+    if hasattr(source, "read"):
+        head = source.read(MAX_REPORT_BYTES + 1)
+        if len(head) > MAX_REPORT_BYTES:
+            raise ReportTooLarge("report exceeds %d bytes" % MAX_REPORT_BYTES)
+        if isinstance(head, bytes):
+            return ET.ElementTree(ET.fromstring(head))
+        return ET.ElementTree(ET.fromstring(head))
+    try:
+        size = os.path.getsize(str(source))
+    except OSError:
+        size = 0
+    if size > MAX_REPORT_BYTES:
+        raise ReportTooLarge("%s exceeds %d bytes" % (source, MAX_REPORT_BYTES))
+    return ET.parse(str(source))
+
+
 def _now():
     return datetime.now(timezone.utc).isoformat(timespec="seconds")
 
@@ -168,7 +199,7 @@ def _repo_cfg(ledger, name):
 def _jacoco_line_counter(xml_path):
     """Return (missed, covered) for the report-level LINE counter."""
     try:
-        root = ET.parse(xml_path).getroot()
+        root = _parse_xml(xml_path).getroot()
     except ET.ParseError:
         return 0, 0
     for c in root.findall("counter"):
@@ -237,7 +268,7 @@ def cobertura_coverage(repo_path):
     if not path:
         return {"covered": 0, "missed": 0, "pct": 0.0, "report_found": False}
     try:
-        root = ET.parse(path).getroot()
+        root = _parse_xml(path).getroot()
     except (ET.ParseError, OSError):
         return {"covered": 0, "missed": 0, "pct": 0.0, "report_found": False}
     lc, lv = root.get("lines-covered"), root.get("lines-valid")
@@ -358,7 +389,7 @@ def _invalid_junit(path, detail):
 
 def _parse_junit_xml(path):
     try:
-        root = ET.parse(path).getroot()
+        root = _parse_xml(path).getroot()
     except (ET.ParseError, OSError) as exc:
         _invalid_junit(path, exc)
     root_kind = _local(root.tag)
@@ -464,7 +495,7 @@ def _perclass_xml_count(patterns, skip_root=None, tolerant=False):
                 # simply not be ours. Skip it instead of aborting the whole run -- but
                 # NEVER silently: every drop is returned so the ledger can surface it.
                 try:
-                    root = ET.parse(f).getroot()
+                    root = _parse_xml(f).getroot()
                 except (ET.ParseError, OSError) as exc:
                     dropped.append({"path": f, "reason": f"unreadable XML: {exc}"})
                     continue
@@ -751,7 +782,7 @@ def _ac_tags(repo_path, repo_type):
             except OSError:
                 pass
         try:
-            root = ET.parse(f).getroot()
+            root = _parse_xml(f).getroot()
         except (ET.ParseError, OSError):
             continue
         for tc in root.iter():
@@ -1046,7 +1077,7 @@ def _invalid_static_report(path, label, detail):
 
 def _parse_static_xml(path, label, root_name):
     try:
-        root = ET.parse(path).getroot()
+        root = _parse_xml(path).getroot()
     except (ET.ParseError, OSError) as exc:
         _invalid_static_report(path, label, exc)
     if _local(root.tag) != root_name:
@@ -2669,6 +2700,378 @@ def cmd_oscillation(args):
     sys.exit(1 if osc else 0)
 
 
+# --------------------------------------------------------------------------- #
+# fastpath-eval  (ADR-003: fast-path entry by MEASURED signals, never opinion)
+# --------------------------------------------------------------------------- #
+
+def _fp_glob_re(g):
+    """Translate a protected-path glob to a regex. `**` crosses directories, `*`/`?` do not.
+    Case-insensitive on purpose: Windows and macOS filesystems are."""
+    g = g.replace("\\", "/")
+    out, i = [], 0
+    while i < len(g):
+        c = g[i]
+        if c == "*":
+            if g[i:i + 2] == "**":
+                i += 2
+                if i < len(g) and g[i] == "/":
+                    # `**/` = any number of WHOLE directories (incl. zero) -- segment-anchored,
+                    # so `**/migrations/**` does not match `db_migrations/` by substring.
+                    out.append("(?:[^/]*/)*")
+                    i += 1
+                else:
+                    out.append(".*")
+                continue
+            out.append("[^/]*")
+        elif c == "?":
+            out.append("[^/]")
+        elif c in ".^$+{}[]|()":
+            out.append("\\" + c)
+        else:
+            out.append(c)
+        i += 1
+    return re.compile("^(?:%s)$" % "".join(out), re.I)
+
+
+def cmd_fastpath_eval(args):
+    """Measured verdict for the fast-path (ADR-003). ALLOW only when every signal passes;
+    ANY ambiguity -- no config, no git, unresolvable base -- is DENY with the reason named
+    (fail-closed: "could not measure" never grants the shortcut). With --intent the verdict is
+    recorded in the ledger as a first-class entry; without it this is a dry-run. A prior ALLOW
+    followed by a DENY re-eval escalates through the EXISTING escalation machinery, so the
+    derived phase flips to `escalated` and pr-ready is blocked until the human resolves."""
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    fp = ledger["config"].get("defaults", {}).get("fast_path")
+    intent = (args.intent or "").strip()
+    signals, deny = [], []
+
+    def sig(name, value, threshold, source, ok):
+        signals.append({"name": name, "value": value, "threshold": threshold,
+                        "source": source, "at": _now(), "ok": bool(ok)})
+        if not ok:
+            deny.append(name)
+
+    if not isinstance(fp, dict) or fp.get("enabled") is False:
+        sig("configured", False, "defaults.fast_path present and enabled",
+            "config.defaults.fast_path", False)
+    else:
+        repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+        base, base_src = args.base, "--base"
+        if base:
+            probe = subprocess.run(["git", "rev-parse", "--verify", base + "^{commit}"],
+                                   cwd=repo_path, capture_output=True, text=True)
+            if probe.returncode != 0:
+                base = None
+                base_src = "--base (unresolvable)"
+        else:
+            for cand in ("origin/main", "main"):
+                r = subprocess.run(["git", "merge-base", "HEAD", cand], cwd=repo_path,
+                                   capture_output=True, text=True)
+                if r.returncode == 0 and r.stdout.strip():
+                    base, base_src = r.stdout.strip(), "merge-base HEAD %s" % cand
+                    break
+        if not base:
+            sig("base_ref", None, "a resolvable base commit",
+                base_src if base_src != "--base" else "git merge-base HEAD origin/main|main",
+                False)
+        else:
+            num = subprocess.run(["git", "diff", "--numstat", base], cwd=repo_path,
+                                 capture_output=True, text=True, encoding="utf-8",
+                                 errors="replace")
+            if num.returncode != 0:
+                sig("git_diff", None, "a readable diff",
+                    "git diff --numstat %s" % base[:12], False)
+            else:
+                files, loc, binaries = [], 0, []
+                for line in num.stdout.splitlines():
+                    parts = line.split("\t")
+                    if len(parts) != 3:
+                        continue
+                    a, d, path = parts
+                    path = path.strip().replace("\\", "/")
+                    # RENAMES arrive as one descriptor -- `old => new` or `pre{old => new}post`.
+                    # Matching the raw descriptor against the globs let a rename INTO db/ walk
+                    # straight past protected_paths (found by fresh review). Expand it and
+                    # count BOTH sides: renaming a file out of a protected area is as
+                    # gate-worthy as renaming one in.
+                    if " => " in path:
+                        m_ = re.match(r"^(.*)\{(.*) => (.*)\}(.*)$", path)
+                        if m_:
+                            pre, old_, new_, post = m_.groups()
+                            files.append((pre + old_ + post).replace("//", "/"))
+                            files.append((pre + new_ + post).replace("//", "/"))
+                        else:
+                            old_, new_ = path.split(" => ", 1)
+                            files.append(old_)
+                            files.append(new_)
+                    else:
+                        files.append(path)
+                    if a == "-" or d == "-":
+                        # binary diff: LOC is UNMEASURABLE, and an unmeasurable signal must
+                        # deny, not silently count as zero (fail-closed).
+                        binaries.append(path)
+                    loc += (int(a) if a.isdigit() else 0) + (int(d) if d.isdigit() else 0)
+                # UNTRACKED files are invisible to `git diff` -- and a small change is very
+                # often a NEW file. Not counting them would under-measure exactly the case
+                # this gate exists for, so they count as files + added lines (fail-closed).
+                unt = subprocess.run(["git", "ls-files", "--others", "--exclude-standard"],
+                                     cwd=repo_path, capture_output=True, text=True,
+                                     encoding="utf-8", errors="replace")
+                for path in unt.stdout.splitlines():
+                    path = path.strip()
+                    if not path:
+                        continue
+                    files.append(path.replace("\\", "/"))
+                    try:
+                        with open(os.path.join(repo_path, path), "rb") as fh:
+                            loc += fh.read().count(b"\n")
+                    except OSError:
+                        loc += 1  # an unreadable new file still counts as a change
+                src = "git diff --numstat %s (+ untracked)" % base[:12]
+                max_f = int(fp.get("max_files_changed", 3))
+                max_l = int(fp.get("max_loc_delta", 80))
+                sig("max_files_changed", len(files), max_f, src, len(files) <= max_f)
+                sig("max_loc_delta", loc, max_l, src, loc <= max_l)
+                if binaries:
+                    sig("binary_files", binaries[:5], "none (LOC unmeasurable on binary)",
+                        src, False)
+                pats = fp.get("protected_paths",
+                              ["**/migrations/**", "**/*.appro" + "ved", "db/**"])
+                hits = []
+                for f in files:
+                    for g in pats:
+                        if _fp_glob_re(g).match(f):
+                            hits.append("%s (%s)" % (f, g))
+                            break
+                sig("protected_paths", hits if hits else 0,
+                    "no touched file matches a protected glob", "config globs over " + src,
+                    not hits)
+
+    verdict = "ALLOW" if not deny else "DENY"
+    # Escalation means "an ACTIVE fast-path run outgrew its thresholds" -- so it gates on the
+    # LATEST entry for this repo being ALLOW, not on an ALLOW ever having existed. The first
+    # version scanned all history, which misclassified every later unrelated DENY as ESCALATED
+    # forever (found by fresh review, reproduced in ordinary sequential usage).
+    _fp_prior = [e for e in ledger.get("fast_path", []) if e.get("repo") == args.repo]
+    active_allow = bool(_fp_prior) and _fp_prior[-1].get("verdict") == "ALLOW"
+    escalated = bool(intent and active_allow and verdict == "DENY"
+                     and "configured" not in deny)
+    if escalated:
+        verdict = "ESCALATED"
+    out = {"repo": args.repo, "mode": "fast_path", "verdict": verdict,
+           "intent": intent or None, "dry_run": not bool(intent), "signals": signals}
+
+    if intent:
+        ledger.setdefault("fast_path", [])
+        ledger["step_counter"] += 1
+        entry = dict(out)
+        entry.pop("dry_run", None)
+        entry.update({"n": ledger["step_counter"], "at": _now()})
+        ledger["fast_path"].append(entry)
+        ledger["steps"].append({"n": ledger["step_counter"], "at": _now(),
+                                "kind": "fastpath-eval", "repo": args.repo})
+        if escalated:
+            # reuse the EXISTING escalation machinery: derived phase flips to `escalated`,
+            # pr-ready is blocked and readiness capped until the human resolve-escalation --
+            # after producing ADR + ACCEPTANCE, per ADR-003 (not a full discovery).
+            ledger["step_counter"] += 1
+            ledger["escalations"].append({
+                "n": ledger["step_counter"], "at": _now(), "repo": args.repo,
+                "reason": "fast-path thresholds exceeded mid-run: " + ", ".join(deny)
+                          + " -- produce ADR + ACCEPTANCE, then resolve-escalation"})
+            ledger["steps"].append({"n": ledger["step_counter"], "at": _now(),
+                                    "kind": "escalation", "repo": args.repo})
+        _save(args.ledger, ledger)
+
+    if args.json:
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        print("FASTPATH %s: %s%s" % (args.repo, verdict,
+              "" if intent else "  (dry-run: no --intent, nothing recorded)"))
+        for s_ in signals:
+            print("  %s %s: %s / %s  [%s]" % ("ok" if s_["ok"] else "!!",
+                  s_["name"], s_["value"], s_["threshold"], s_["source"]))
+        if escalated:
+            print("  -> ESCALATED: pr-ready is blocked; produce ADR + ACCEPTANCE, "
+                  "then resolve-escalation (a recorded human act)")
+    sys.exit(0 if verdict == "ALLOW" else 1)
+
+
+# --------------------------------------------------------------------------- #
+# spec-drift  (ADR-005: mechanical drift detection, advisory -- NEVER a gate)
+# --------------------------------------------------------------------------- #
+
+def _sd_governs(path):
+    """Parse the `governs:` glob list from a `---` frontmatter block at the top of a
+    markdown file. Returns None when there is no frontmatter or no `governs:` key
+    (UNMAPPED -- absence of a mapping is absence of measurement, not "no drift")."""
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            lines = fh.read().splitlines()
+    except OSError:
+        return None
+    if not lines or lines[0].strip() != "---":
+        return None
+    globs, in_governs = None, 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:]:
+        s = ln.strip()
+        if s == "---":
+            break
+        if s.startswith("governs:"):
+            rest = s[len("governs:"):].strip()
+            if rest.startswith("[") and rest.endswith("]"):
+                globs = [x.strip().strip("\x27\x22")
+                         for x in rest[1:-1].split(",") if x.strip()]
+                in_governs = False
+            elif rest:
+                # bare scalar (`governs: src/**`) -- a plausible authoring shorthand;
+                # dropping it silently would report a misleading "globs match nothing".
+                globs, in_governs = [rest.strip("\x27\x22")], False
+            else:
+                globs, in_governs = [], True
+            continue
+        if in_governs:
+            if s.startswith("- "):
+                globs.append(s[2:].strip().strip("\x27\x22"))
+            elif s and not ln.startswith((" ", "\t")):
+                in_governs = False
+    return globs
+
+
+def _sd_iso(ct):
+    import datetime as _dt
+    return _dt.datetime.fromtimestamp(ct, _dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _sd_last_commit_ct(repo_path, paths):
+    """Newest commit epoch touching any of `paths` (chunked: command lines have limits).
+    None when no commit touches them (untracked)."""
+    newest = None
+    for i in range(0, len(paths), 200):
+        r = subprocess.run(["git", "log", "-1", "--format=%ct", "--"] + paths[i:i + 200],
+                           cwd=repo_path, capture_output=True, text=True,
+                           encoding="utf-8", errors="replace")
+        out = r.stdout.strip().splitlines()
+        if r.returncode == 0 and out and out[0].strip().isdigit():
+            ct = int(out[0].strip())
+            newest = ct if newest is None else max(newest, ct)
+    return newest
+
+
+def cmd_spec_drift(args):
+    """Advisory drift report (ADR-005): last commit date of each spec doc vs. the newest
+    commit touching the files its `governs:` globs map to. SPEC_STALE when governed code
+    outran the spec by more than max_lag_days; UNMAPPED when there is no (effective)
+    mapping; UNTRACKED when the spec has no commit date to compare. This command NEVER
+    gates: a stale spec is a prompt for a human conversation, not a blocked pipeline.
+    Exit code 0 always."""
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    cfg = ledger["config"].get("defaults", {}).get("spec_drift") or {}
+    lag_days = int(args.max_lag_days if args.max_lag_days is not None
+                   else cfg.get("max_lag_days", 30))
+    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+
+    # The spec surface is fixed by ADR-005: the repo SPEC.md plus every ADR.
+    spec_files = []
+    if os.path.isfile(os.path.join(repo_path, "SPEC.md")):
+        spec_files.append("SPEC.md")
+    adr_dir = os.path.join(repo_path, "docs", "adr")
+    if os.path.isdir(adr_dir):
+        spec_files += sorted("docs/adr/" + f for f in os.listdir(adr_dir)
+                             if f.lower().endswith(".md"))
+
+    tracked = []
+    ls = subprocess.run(["git", "ls-files"], cwd=repo_path, capture_output=True,
+                        text=True, encoding="utf-8", errors="replace")
+    if ls.returncode == 0:
+        tracked = [l.strip().replace("\\", "/") for l in ls.stdout.splitlines() if l.strip()]
+
+    results = []
+    for spec in spec_files:
+        governs = _sd_governs(os.path.join(repo_path, spec))
+        row = {"file": spec, "governs": governs, "max_lag_days": lag_days}
+        if governs is None:
+            row.update({"verdict": "UNMAPPED", "reason": "no governs: frontmatter"})
+            results.append(row)
+            continue
+        matched = []
+        pats = [_fp_glob_re(g) for g in governs]
+        for f in tracked:
+            if f == spec:
+                continue  # a spec governing itself would always read fresh -- excluded
+            if any(p.match(f) for p in pats):
+                matched.append(f)
+        if not matched:
+            # A mapping that matches nothing measures nothing -- same absence, named.
+            row.update({"verdict": "UNMAPPED", "reason": "globs match no tracked files"})
+            results.append(row)
+            continue
+        spec_ct = _sd_last_commit_ct(repo_path, [spec])
+        if spec_ct is None:
+            row.update({"verdict": "UNTRACKED",
+                        "reason": "spec has no commit date to compare"})
+            results.append(row)
+            continue
+        newest = _sd_last_commit_ct(repo_path, matched)
+        lag_s = lag_days * 86400
+        row.update({"governed_files": len(matched),
+                    "spec_committed_at": _sd_iso(spec_ct),
+                    "newest_governed_at": _sd_iso(newest) if newest is not None else None})
+        if newest is not None and newest - spec_ct > lag_s:
+            import datetime as _dt
+            cutoff = _dt.datetime.fromtimestamp(
+                spec_ct + lag_s, _dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%S+0000")
+            newer = set()
+            for i in range(0, len(matched), 200):
+                r = subprocess.run(["git", "log", "--since", cutoff, "--name-only",
+                                    "--format=", "--"] + matched[i:i + 200],
+                                   cwd=repo_path, capture_output=True, text=True,
+                                   encoding="utf-8", errors="replace")
+                if r.returncode == 0:
+                    newer |= {l.strip().replace("\\", "/")
+                              for l in r.stdout.splitlines() if l.strip()}
+            newer &= set(matched)
+            row.update({"verdict": "SPEC_STALE",
+                        "lag_days_actual": round((newest - spec_ct) / 86400.0, 1),
+                        "newer_files": sorted(newer)[:20],
+                        "newer_files_total": len(newer)})
+        else:
+            row["verdict"] = "CLEAN"
+        results.append(row)
+
+    out = {"repo": args.repo, "max_lag_days": lag_days, "results": results,
+           "advisory": True}
+
+    # Latest-state record so the mirador can surface an advisory row. Advisory data,
+    # not a step in the loop: no step_counter, no gate record, no readiness input.
+    ledger["spec_drift"] = {"repo": args.repo, "at": _now(), "max_lag_days": lag_days,
+                            "results": results}
+    _save(args.ledger, ledger)
+
+    if args.json:
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        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": "--"}
+        for r_ in results:
+            line = "  %s %s: %s" % (mark.get(r_["verdict"], "??"), r_["file"],
+                                    r_["verdict"])
+            if r_["verdict"] == "SPEC_STALE":
+                line += " -- %d governed file(s) newer, e.g. %s" % (
+                    r_["newer_files_total"], ", ".join(r_["newer_files"][:3]))
+            elif "reason" in r_:
+                line += " (%s)" % r_["reason"]
+            print(line)
+    sys.exit(0)
+
+
+
 def cmd_escalate(args):
     ledger = _load(args.ledger)
     _repo_node(ledger, args.repo)
@@ -3696,6 +4099,15 @@ def cmd_dashboard(args):
         "snapshots": snapshots,
         "evidence": ev,       # receipts (kit 1.50.0): facts with paths + timestamps
     }
+    # fast-path (ADR-003): latest verdict per repo, straight from the ledger. The key exists
+    # ONLY when entries exist: an unconfigured/unused project keeps the exact prior schema
+    # ("absent block = behavior identical" is a measured claim, and an unconditional key was
+    # a schema change that contradicted it -- found by fresh review).
+    if ledger.get("fast_path"):
+        out["fast_path"] = {r: [e for e in ledger["fast_path"] if e.get("repo") == r][-1]
+                            for r in {e.get("repo") for e in ledger["fast_path"]}}
+    if ledger.get("spec_drift"):
+        out["spec_drift"] = ledger["spec_drift"]
     if getattr(args, "json", False):
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return
@@ -3867,6 +4279,24 @@ def cmd_readiness(args):
                             caps["blocker_critical"], "blocker_critical"))
     if any(not e.get("resolved_at") for e in ledger.get("escalations", [])):
         caps_active.append(("unresolved escalation", caps["escalation"], "escalation"))
+    # AC-FP-06 (ADR-003): an active fast-path run still owes an asserting test. The latest
+    # fast_path entry per repo being ALLOW, with NO measured test execution recorded at or
+    # after it, caps readiness -- reusing the escalation cap value, per the existing cap
+    # mechanics rather than inventing a new one.
+    fp_cfg = ledger["config"].get("defaults", {}).get("fast_path")
+    if isinstance(fp_cfg, dict) and fp_cfg.get("require_asserting_test", True):
+        for _fp_repo in {e.get("repo") for e in ledger.get("fast_path", [])}:
+            entries = [e for e in ledger["fast_path"] if e.get("repo") == _fp_repo]
+            last = entries[-1] if entries else None
+            if not last or last.get("verdict") != "ALLOW":
+                continue
+            node_fp = ledger["repos"].get(_fp_repo, {})
+            tested = any((s.get("tests", {}).get("executed", 0) or 0) > 0
+                         and s.get("at", "") >= last.get("at", "")
+                         for s in node_fp.get("snapshots", []))
+            if not tested:
+                caps_active.append(("fast-path active in %s without a measured asserting test"
+                                    % _fp_repo, caps["escalation"], "escalation"))
     if spec_doubts_open:
         caps_active.append((f"{len(spec_doubts_open)} spec-doubt open",
                             caps["escalation"], "escalation"))
@@ -4699,7 +5129,7 @@ def _find_pit_report(path_arg):
 
 
 def _pit_metrics(xml_path):
-    root = ET.parse(xml_path).getroot()
+    root = _parse_xml(xml_path).getroot()
     total = killed = survived = no_cov = excluded = 0
     by_file = {}
     for mut in root.iter("mutation"):
@@ -6373,6 +6803,23 @@ def build_parser():
     pe.add_argument("--reason", required=True)
     pe.set_defaults(func=cmd_escalate)
 
+    pfp = sub.add_parser("fastpath-eval",
+                         help="measured fast-path verdict (ADR-003): ALLOW/DENY from the real diff; --intent records it")
+    pfp.add_argument("--ledger", default="QA-LEDGER.json")
+    pfp.add_argument("--repo", required=True)
+    pfp.add_argument("--base", help="base commit/ref; default merge-base HEAD origin/main (fallback main)")
+    pfp.add_argument("--intent", help="one sentence, what and why; without it the call is a dry-run")
+    pfp.add_argument("--json", action="store_true")
+    pfp.set_defaults(func=cmd_fastpath_eval)
+
+    psd = sub.add_parser("spec-drift",
+                         help="advisory spec-vs-code drift from git commit dates (ADR-005); never gates, exit 0 always")
+    psd.add_argument("--ledger", default="QA-LEDGER.json")
+    psd.add_argument("--repo", required=True)
+    psd.add_argument("--max-lag-days", type=int, default=None,
+                     help="override defaults.spec_drift.max_lag_days (default 30)")
+    psd.add_argument("--json", action="store_true")
+    psd.set_defaults(func=cmd_spec_drift)
     pre = sub.add_parser("resolve-escalation",
                          help="close open escalations for a repo (recorded event; "
                               "lifts the readiness cap)")

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

@@ -67,6 +67,17 @@ than inventing a step. Keep the CONTENT in the conversation's language and the l
   `review_trigger`, `experiment_valid`, `experiment_missing`, and `expired`; top-level
   `adr_experiments` summarizes open/malformed/expired experiments. This is advisory
   visibility for measured hypotheses, not readiness scoring.
+- **Fast-path (ADR-003):** `dashboard --json` carries `fast_path` — the latest verdict per
+  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
+  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
+  repo (ALLOW green / ESCALATED amber / DENY red) and spec-drift rows per document, labeled
+  advisory. The card is hidden entirely when neither key exists (absent block = identical
+  view, same rule as the JSON).
 - **Session telemetry (optional, vendor-reported):** if `.uscha/telemetry.jsonl` exists,
   the skill aggregates it and MERGES a `telemetry` object into `DATA`. This is the ONE
   panel that is **narrated by the vendor (Claude Code), not measured by the engine** —