@andresmassello/uscha 1.59.0 → 1.61.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.59.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.61.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`, 31 subcommands, Python stdlib) that ingests
+**A measurement engine** (`qa_ledger.py`, 32 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.59.0",
+  "version": "1.61.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-characterize/SKILL.md

@@ -190,3 +190,21 @@ covered.
 
 Never overwrite an existing approved golden. If a `.received` already exists, regenerate it;
 if a `.approved` exists, it is the human's — leave it untouched and surface the diff.
+
+## Record the coverage map (ADR-006)
+
+After the `.received` is produced and while the harness is still the thing that just ran,
+record WHICH source files it exercised — the mapping that lets the fast-path veto a change
+touching code a golden froze:
+
+```bash
+python qa_ledger.py golden-coverage --harness <harness> --golden <the .approved sibling>
+```
+
+This is **derived measurement, not judgment**: the agent may write `golden.coverage.json`.
+INV-GOLDEN-01 governs the `.approved` bytes, which encode judgment, and nothing here changes
+that — the human still approves the golden itself.
+
+`coverage.py` is a capture-time dependency. Without it the command writes **nothing** and exits
+2: an empty map would read as "this golden covers nothing", which is exactly the lie that would
+let the veto pass. Skipping the map is honest; recording an empty one is not.

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

@@ -61,6 +61,7 @@ import re
 import shutil
 import subprocess
 import sys
+import tempfile
 import unicodedata
 import xml.etree.ElementTree as ET
 from datetime import datetime, timezone
@@ -1857,6 +1858,58 @@ def cmd_init(args):
           f"coverage_threshold={defaults.get('coverage_threshold')})")
 
 
+def _origin_label(origin):
+    """Render an origin for humans. An unmeasurable tree state reads `unknown`, never
+    `clean` -- the whole reason the field distinguishes False from None."""
+    o = origin or {}
+    sha = (o.get("commit") or "")[:8] or "no-commit"
+    dirty = o.get("dirty")
+    state = "unknown" if dirty is None else ("dirty" if dirty else "clean")
+    return "%s/%s" % (sha, state)
+
+
+def _evidence_origin(repo_path):
+    """WHERE the evidence came from: the commit it was measured at, and whether the tree
+    was clean (ADR-007). The engine's freshness check compares file MTIMES, so until now a
+    snapshot could say "tests green" without being able to say green AT WHAT -- provenance
+    true of the tree, not of the commit that will merge.
+
+    Absence is NAMED, never guessed: no git, no repo, unreadable -> both None. `dirty is
+    None` must never read as clean; that distinction is the entire point of recording it.
+    Advisory only -- nothing here scores or blocks.
+
+    Untracked files COUNT as dirty (plain --porcelain): an untracked file the suite depends
+    on is exactly the contamination this records, and treating untracked as invisible is a
+    mistake this engine already paid for once (fast-path, 1.57.0)."""
+    origin = {"commit": None, "dirty": None}
+
+    def _git(*args):
+        # OSError covers BOTH ways this used to take the whole snapshot down: git absent
+        # from PATH (FileNotFoundError) and a repo_path that does not exist or is a file
+        # (NotADirectoryError). Every sibling measurement in _snapshot already tolerates a
+        # missing path; provenance must not be the one field that can crash the command it
+        # only annotates. Same posture as _spike_branch. (Both found by fresh review, both
+        # reproduced: an unconfigured or not-yet-cloned repo path is ordinary, not exotic.)
+        try:
+            return subprocess.run(["git"] + list(args), cwd=repo_path,
+                                  capture_output=True, text=True, encoding="utf-8",
+                                  errors="replace")
+        except OSError:
+            return None
+
+    rev = _git("rev-parse", "HEAD")
+    if rev is not None and rev.returncode == 0 and rev.stdout.strip():
+        origin["commit"] = rev.stdout.strip()
+    # `-- .` scopes the answer to repo_path. Without it, a repo entry pointing at a
+    # SUBDIRECTORY of a larger working tree reports the whole outer repo's state, so an
+    # unrelated edit elsewhere would mark this repo's evidence dirty -- and the ADR would
+    # be claiming a per-path fact the code did not deliver.
+    st = _git("status", "--porcelain", "--", ".")
+    if st is not None and st.returncode == 0:
+        origin["dirty"] = bool(st.stdout.strip())
+    return origin
+
+
 def _snapshot(ledger, name):
     node = _repo_node(ledger, name)
     cfg = _repo_cfg(ledger, name) if name != "integration" else {"path": ".", "type": "maven"}
@@ -1867,6 +1920,7 @@ def _snapshot(ledger, name):
         "coverage": coverage(path, rtype),
         "tests": test_count(path, rtype),
         "loc": count_loc(path, rtype),
+        "origin": _evidence_origin(path),
     }
     node["snapshots"].append(snap)
     return snap
@@ -1886,6 +1940,7 @@ def cmd_snapshot(args):
           f"coverage={cov['pct']}% (found={cov['report_found']}), "
           f"tests={tests['total']} (found={tests['report_found']}), "
           f"freshness={freshness.get('status', 'unknown')}, "
+          f"origin={_origin_label(snap.get('origin'))}, "
           f"prod_loc={loc['prod_loc']}, test_loc={loc['test_loc']}")
     if freshness.get("status") == "stale":
         print(f"  test evidence stale: {freshness.get('reason')}")
@@ -2847,6 +2902,64 @@ def cmd_fastpath_eval(args):
                 sig("protected_paths", hits if hits else 0,
                     "no touched file matches a protected glob", "config globs over " + src,
                     not hits)
+                # ADR-006: the golden-touched veto. OPT-IN -- absent flag, no signal at all
+                # and behavior identical to 1.57.0+. DECLARED -- fail-closed: a missing or
+                # empty mapping DENIES, because "could not measure" never grants a shortcut.
+                if fp.get("forbid_when_golden_touched"):
+                    gcm = _load_golden_coverage(repo_path)   # malformed -> exit 2, never silent
+                    gmap = (gcm or {}).get("goldens") or {}
+                    # Enumerate the goldens that actually EXIST. A manifest knowing only SOME
+                    # of them would otherwise assert "no touched file is covered by a golden"
+                    # about goldens it has never measured -- an ALLOW built on ignorance, which
+                    # is precisely the silent bypass this veto exists to prevent. Found by
+                    # fresh review and reproduced: 2 goldens in the tree, 1 in the map, a diff
+                    # touching the unmapped one's source -> ALLOW. Same glob shape cmd_golden_diff
+                    # already uses to locate goldens; no new mechanism.
+                    _sfx = ".appro" + "ved"
+                    _hits = set(glob.glob(os.path.join(repo_path, "**", "*" + _sfx),
+                                          recursive=True))
+                    _hits |= set(glob.glob(os.path.join(repo_path, "**", "*" + _sfx + ".*"),
+                                           recursive=True))
+                    _tree = set()
+                    for _p in _hits:
+                        if os.path.isfile(_p):
+                            _r = _gc_rel(os.path.abspath(_p), os.path.abspath(repo_path))
+                            if _r:
+                                _tree.add(_r)
+                    _unmapped = sorted(_tree - set(gmap))
+                    if _unmapped:
+                        # covers the manifest-absent case too: with goldens present and no
+                        # manifest, every one of them is unmapped.
+                        sig("golden_touched", _unmapped[:5],
+                            "every golden in the tree carries a measured map",
+                            GOLDEN_COVERAGE_FILE + " (missing or incomplete -- run "
+                            "golden-coverage for each golden)", False)
+                    elif not _tree:
+                        # No golden exists, so none can be touched. This is a MEASUREMENT
+                        # ("nothing to cover"), not an absence of one -- denying forever a
+                        # repo that has no goldens would be ceremony, not rigor.
+                        sig("golden_touched", 0, "no golden in the tree to be covered",
+                            "glob over " + repo_path, True)
+                    else:
+                        covered = {}
+                        _commits, _tools = set(), set()
+                        for _g, _e in gcm["goldens"].items():
+                            for _f in _e.get("files", []):
+                                covered.setdefault(_f, []).append(_g)
+                            if _e.get("captured_at_commit"):
+                                _commits.add(_e["captured_at_commit"][:8])
+                            if _e.get("tool"):
+                                _tools.add(_e["tool"])
+                        ghits = ["%s (golden: %s)" % (f, ", ".join(covered[f]))
+                                 for f in files if f in covered]
+                        # provenance travels with the verdict (ADR-006: no freshness gate,
+                        # but every verdict says which capture it trusted)
+                        prov = "%s @ %s (%s)" % (
+                            GOLDEN_COVERAGE_FILE,
+                            ",".join(sorted(_commits)) if _commits else "no commit recorded",
+                            ", ".join(sorted(_tools)) if _tools else "no tool recorded")
+                        sig("golden_touched", ghits if ghits else 0,
+                            "no touched file is covered by a golden", prov, not ghits)
 
     verdict = "ALLOW" if not deny else "DENY"
     # Escalation means "an ACTIVE fast-path run outgrew its thresholds" -- so it gates on the
@@ -3072,6 +3185,158 @@ def cmd_spec_drift(args):
 
 
 
+# --------------------------------------------------------------------------- #
+# golden-coverage  (ADR-006: the golden<->source mapping, DERIVED BY MEASUREMENT)
+# --------------------------------------------------------------------------- #
+
+GOLDEN_COVERAGE_FILE = "golden.coverage.json"
+
+
+def _load_golden_coverage(root):
+    """Read the measured golden<->source manifest. Strict shape, mirroring
+    _load_scrub_rules: a typo must NOT degrade into "no mapping" in silence, because
+    under a declared veto that silence would GRANT the shortcut it exists to deny.
+    Absent file -> None (the caller decides; with the veto declared, absent is DENY)."""
+    path = os.path.join(root, GOLDEN_COVERAGE_FILE)
+    if not os.path.isfile(path):
+        return None
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            spec = json.load(fh)
+        if not isinstance(spec, dict) or not isinstance(spec.get("goldens"), dict):
+            raise TypeError('expected {"goldens": {"<golden path>": {"files": [...]}}}')
+        for g, entry in spec["goldens"].items():
+            if not isinstance(entry, dict) or not isinstance(entry.get("files"), list):
+                raise TypeError("golden %r has no files list" % g)
+            for f in entry["files"]:
+                if not isinstance(f, str):
+                    raise TypeError("golden %r maps a non-string file" % g)
+        return spec
+    except (json.JSONDecodeError, TypeError, KeyError) as exc:
+        print("[qa_ledger] %s invalid (%s) - the golden mapping is not skipped in "
+              "silence: fix the file or delete it." % (path, exc), file=sys.stderr)
+        sys.exit(2)
+
+
+def _gc_rel(path, root):
+    # realpath BOTH sides before comparing. On Windows a temp dir under a username longer
+    # than 8 chars is reported in 8.3 short form (RUNNER~1) by one side and long form by the
+    # other; relpath then yields "../.." and a file INSIDE the repo is filtered out as
+    # outside it -- silently shrinking the map. Invisible on a machine whose username does
+    # not mangle (which is why local Windows was green and Windows CI was not).
+    try:
+        rel = os.path.relpath(os.path.realpath(path), os.path.realpath(root))
+    except ValueError:      # different drive on Windows -- outside the repo either way
+        return None
+    rel = rel.replace("\\", "/")
+    return None if rel.startswith("../") else rel
+
+
+def cmd_golden_coverage(args):
+    """Record the MEASURED source files a golden's harness exercises (ADR-006).
+
+    The harnesses drive their subject through subprocess, so instrumenting only the parent
+    measures nothing: coverage is injected into EVERY python the harness spawns via a
+    sitecustomize on PYTHONPATH plus COVERAGE_PROCESS_START -- the documented multiprocess
+    technique, and the same PYTHONPATH-injection shape this repo's fault tests already use.
+
+    coverage.py is an optional CAPTURE-time dependency (the engine stays stdlib-only at
+    runtime). Absent, this writes NOTHING and exits 2: an empty map would read as
+    "this golden covers nothing", which is the one lie that would let the veto pass."""
+    try:
+        import coverage
+    except ImportError:
+        print("[qa_ledger] coverage.py is not installed - refusing to write a map that was "
+              "not measured (an empty map reads as 'covers nothing'). pip install coverage",
+              file=sys.stderr)
+        sys.exit(2)
+
+    root = os.path.abspath(args.dir or ".")
+    harness = os.path.abspath(args.harness)
+    if not os.path.isfile(harness):
+        print("[qa_ledger] harness not found: %s" % harness, file=sys.stderr)
+        sys.exit(2)
+
+    tmp = tempfile.mkdtemp(prefix="uscha-gc-")
+    try:
+        data_file = os.path.join(tmp, ".coverage")
+        rc = os.path.join(tmp, "cov.rc")
+        with open(rc, "w", encoding="utf-8") as fh:
+            fh.write("[run]\nparallel = True\ndata_file = %s\n"
+                     % data_file.replace("\\", "/"))
+        with open(os.path.join(tmp, "sitecustomize.py"), "w", encoding="utf-8") as fh:
+            fh.write("import coverage\ncoverage.process_startup()\n")
+
+        env = dict(os.environ)
+        env["COVERAGE_PROCESS_START"] = rc
+        env["PYTHONPATH"] = tmp + os.pathsep + env.get("PYTHONPATH", "")
+        env["PYTHONIOENCODING"] = "utf-8"
+        r = subprocess.run([sys.executable, harness], cwd=root, env=env,
+                           capture_output=True, text=True, encoding="utf-8",
+                           errors="replace")
+        if r.returncode != 0:
+            print("[qa_ledger] the harness failed (exit %d) - no map recorded from a run "
+                  "that did not complete:\n%s" % (r.returncode, (r.stderr or "")[-1500:]),
+                  file=sys.stderr)
+            sys.exit(2)
+
+        cov = coverage.Coverage(data_file=data_file)
+        try:
+            cov.combine()
+            cov.save()
+        except Exception as exc:
+            # Never silent: a PARTIAL combine yields an incomplete-but-non-empty file list,
+            # which slips past the empty-map guard below and records a map that under-reports
+            # what the golden covers. The empty case still exits 2; this one is announced so a
+            # human sees the map may be short (fresh-review finding).
+            print("[qa_ledger] coverage combine reported: %s - the map below may be "
+                  "incomplete; re-run before trusting it." % exc, file=sys.stderr)
+        measured = sorted(cov.get_data().measured_files())
+        harness_rel = _gc_rel(harness, root)
+        files = []
+        for m in measured:
+            rel = _gc_rel(os.path.abspath(m), root)
+            # the harness measures the SUBJECT, not itself; sitecustomize is our scaffolding
+            if not rel or rel == harness_rel or rel.endswith("/sitecustomize.py"):
+                continue
+            files.append(rel)
+        files = sorted(set(files))
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+    if not files:
+        print("[qa_ledger] the run measured no source file inside %s - refusing to record "
+              "an empty map (it would read as 'covers nothing')." % root, file=sys.stderr)
+        sys.exit(2)
+
+    head = subprocess.run(["git", "rev-parse", "HEAD"], cwd=root,
+                          capture_output=True, text=True)
+    commit = head.stdout.strip() if head.returncode == 0 else None
+    golden_rel = _gc_rel(os.path.abspath(args.golden), root) or args.golden
+
+    path = os.path.join(root, GOLDEN_COVERAGE_FILE)
+    manifest = _load_golden_coverage(root) or {"goldens": {}}
+    manifest["goldens"][golden_rel] = {
+        "harness": harness_rel,
+        "files": files,
+        "captured_at": _now(),
+        "captured_at_commit": commit,
+        "tool": "coverage.py " + coverage.__version__,
+    }
+    with open(path, "w", encoding="utf-8", newline="\n") as fh:
+        json.dump(manifest, fh, indent=2, ensure_ascii=False, sort_keys=True)
+        fh.write("\n")
+
+    if args.json:
+        print(json.dumps(manifest["goldens"][golden_rel], indent=2, ensure_ascii=False))
+    else:
+        print("GOLDEN-COVERAGE %s: %d source file(s) measured -> %s"
+              % (golden_rel, len(files), GOLDEN_COVERAGE_FILE))
+        for f in files[:20]:
+            print("  " + f)
+
+
+
 def cmd_escalate(args):
     ledger = _load(args.ledger)
     _repo_node(ledger, args.repo)
@@ -4108,6 +4373,16 @@ def cmd_dashboard(args):
                             for r in {e.get("repo") for e in ledger["fast_path"]}}
     if ledger.get("spec_drift"):
         out["spec_drift"] = ledger["spec_drift"]
+    # evidence_origin: the latest snapshot's origin per repo, and ONLY when one exists --
+    # a ledger predating ADR-007 keeps the exact prior schema (same conditional-key rule
+    # fast_path and spec_drift already follow).
+    _org = {}
+    for _rn, _rnode in ledger["repos"].items():
+        _snaps = _rnode.get("snapshots") or []
+        if _snaps and _snaps[-1].get("origin"):
+            _org[_rn] = _snaps[-1]["origin"]
+    if _org:
+        out["evidence_origin"] = _org
     if getattr(args, "json", False):
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return
@@ -6812,6 +7087,14 @@ def build_parser():
     pfp.add_argument("--json", action="store_true")
     pfp.set_defaults(func=cmd_fastpath_eval)
 
+    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")
+    pgc.add_argument("--golden", required=True, help="the golden this map belongs to")
+    pgc.add_argument("--dir", default=".", help="repo root holding " + GOLDEN_COVERAGE_FILE)
+    pgc.add_argument("--json", action="store_true")
+    pgc.set_defaults(func=cmd_golden_coverage)
+
     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")

package/uscha-kit/.claude/skills/uscha-mirador/mirador-watch.ps1

@@ -1,22 +1,22 @@
-# mirador-watch.ps1 -- live second-screen mirador (uscha-kit 1.34.0), Windows.
-# Regenerates mirador.html every N seconds from the current ledger; the page is rendered
-# with a meta-refresh at the same interval, so a browser open on it updates on its own.
-#
-# Usage (run in a spare terminal, from the project root):
-#   powershell -NoProfile -File <kit>\.claude\skills\uscha-mirador\mirador-watch.ps1 [-Interval 30]
-# then open mirador.html in a browser on your second screen. Ctrl-C to stop.
-#
-# Overridable via env: ENGINE, LEDGER, TEMPLATE, OUT, PYTHON.
-param([int]$Interval = 30)
-$here     = Split-Path -Parent $MyInvocation.MyCommand.Path
-$engine   = if ($env:ENGINE)   { $env:ENGINE }   else { Join-Path $here "..\uscha-devloop\qa_ledger.py" }
-$ledger   = if ($env:LEDGER)   { $env:LEDGER }   else { "QA-LEDGER.json" }
-$template = if ($env:TEMPLATE) { $env:TEMPLATE } else { Join-Path $here "mirador.template.html" }
-$out      = if ($env:OUT)      { $env:OUT }      else { "mirador.html" }
-$py       = if ($env:PYTHON)   { $env:PYTHON }   else { "python" }
-Write-Host "mirador-watch: regenerating $out every ${Interval}s (Ctrl-C to stop). Open $out in a browser."
-while ($true) {
-  & $py (Join-Path $here "mirador-render.py") --engine $engine --ledger $ledger --template $template --out $out --refresh $Interval --no-open
-  if ($LASTEXITCODE -ne 0) { Write-Host "mirador-watch: render failed (ledger missing? run uscha-devloop first) -- retrying" }
-  Start-Sleep -Seconds $Interval
-}
+# mirador-watch.ps1 -- live second-screen mirador (uscha-kit 1.34.0), Windows.
+# Regenerates mirador.html every N seconds from the current ledger; the page is rendered
+# with a meta-refresh at the same interval, so a browser open on it updates on its own.
+#
+# Usage (run in a spare terminal, from the project root):
+#   powershell -NoProfile -File <kit>\.claude\skills\uscha-mirador\mirador-watch.ps1 [-Interval 30]
+# then open mirador.html in a browser on your second screen. Ctrl-C to stop.
+#
+# Overridable via env: ENGINE, LEDGER, TEMPLATE, OUT, PYTHON.
+param([int]$Interval = 30)
+$here     = Split-Path -Parent $MyInvocation.MyCommand.Path
+$engine   = if ($env:ENGINE)   { $env:ENGINE }   else { Join-Path $here "..\uscha-devloop\qa_ledger.py" }
+$ledger   = if ($env:LEDGER)   { $env:LEDGER }   else { "QA-LEDGER.json" }
+$template = if ($env:TEMPLATE) { $env:TEMPLATE } else { Join-Path $here "mirador.template.html" }
+$out      = if ($env:OUT)      { $env:OUT }      else { "mirador.html" }
+$py       = if ($env:PYTHON)   { $env:PYTHON }   else { "python" }
+Write-Host "mirador-watch: regenerating $out every ${Interval}s (Ctrl-C to stop). Open $out in a browser."
+while ($true) {
+  & $py (Join-Path $here "mirador-render.py") --engine $engine --ledger $ledger --template $template --out $out --refresh $Interval --no-open
+  if ($LASTEXITCODE -ne 0) { Write-Host "mirador-watch: render failed (ledger missing? run uscha-devloop first) -- retrying" }
+  Start-Sleep -Seconds $Interval
+}

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

@@ -90,6 +90,12 @@ Line guide:
 block with the latest verdict per repo (`fast-path: ALLOW (intent...)` / `ESCALATED`). Absent
 entries → no line at all: silence is honest when no mode was requested.
 
+**Evidence origin (ADR-007):** if the latest snapshot was measured on a DIRTY tree, add ONE
+line: `evidence: measured dirty at <sha8> - not from the commit alone`. Say nothing when the
+tree was clean (the normal case needs no words) and nothing when it is `null` (unmeasurable,
+and inventing a state is worse than silence). This never explains a blocked phase: it scores
+nothing and gates nothing.
+
 **Spec-drift (ADR-005):** if the ledger carries a `spec_drift` run, add ONE line:
 `spec-drift: N stale / M docs (advisory)` — or `spec-drift: no drift measured` when zero are
 stale. Always label it advisory; it never explains a blocked phase. Absent key → no line.

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.59.0",
+  "version": "1.61.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, 31 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, 32 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.59.0",
+  "version": "1.61.0",
   "description": "Uscha spec-driven development methodology for coding agents. Includes npm/npx router.",
   "author": {
     "name": "Andres Massello",

package/uscha-kit/INSTALL.md

@@ -1,128 +1,128 @@
-# Install Uscha
-
-Uscha installs as a machine-level helper for coding agents. The recommended path
-is npm/npx because it works the same on a fresh Codex or Claude Code machine.
-
-The method itself — the paradigm, the five rules, the skills and the library — lives at
-**[uscha.dev](https://uscha.dev)**.
-
-## Quick path
-
-### Codex Desktop
-
-```bash
-npx --yes @andresmassello/uscha@latest version
-npx --yes @andresmassello/uscha@latest install --target codex --dry-run
-npx --yes @andresmassello/uscha@latest install --target codex
-npx --yes @andresmassello/uscha@latest doctor --target codex
-```
-
-Then restart Codex or open a new thread. The installer registers Uscha as a
-personal local plugin under `~/plugins/uscha` and updates
-`~/.agents/plugins/marketplace.json`. It preflights that marketplace before replacing the plugin tree and writes the install marker last.
-
-### Claude Code
-
-```bash
-npx --yes @andresmassello/uscha@latest install --target claude --dry-run
-npx --yes @andresmassello/uscha@latest install --target claude
-npx --yes @andresmassello/uscha@latest doctor --target claude
-```
-
-This installs the `uscha-*` skills and registers a portable Python `PreToolUse` hook under `~/.claude` while preserving unrelated `settings.json` entries. Restart or reload Claude Code after installing.
-
-### Same machine uses both
-
-```bash
-npx --yes @andresmassello/uscha@latest install --target both --dry-run
-npx --yes @andresmassello/uscha@latest install --target both
-npx --yes @andresmassello/uscha@latest doctor --target both
-```
-
-## Prepare a project repo
-
-After the machine install, initialize each project where Uscha should govern the
-workflow:
-
-```bash
-npx --yes @andresmassello/uscha@latest init --repo . --dry-run
-npx --yes @andresmassello/uscha@latest init --repo .
-# Existing differing files are preserved; use --force only to replace them deliberately.
-npx --yes @andresmassello/uscha@latest init --repo . --force
-```
-
-`init` exits nonzero and reports conflicts for differing `uscha.config.json`, `CLAUDE.md`, `CONSTITUTION.md`, or `.gitattributes`; `--dry-run` performs the same conflict check without writing.
-
-`init` also installs the **progress statusline** (kit 1.46.0): it copies
-`.claude/scripts/uscha_{statusline,progress}.py` and merges a `statusLine` + a `Stop` hook into
-`.claude/settings.json` (never clobbering an existing `statusLine`). Add a `label`, `roadmap`
-and `build_priority` to your `repos[]` entry to drive it; with no data it stays hidden.
-
-Project state stays in the project: `uscha.config.json`, `QA-LEDGER.json`,
-`ACCEPTANCE.md`, and approved golden fixtures when used.
-
-## See the dashboard (mirador)
-
-From the root of any project that has a `QA-LEDGER.json`, one command renders the mirador and
-opens it — no python, no paths:
-
-```bash
-npx --yes @andresmassello/uscha@latest mirador           # one glance: render + open
-npx --yes @andresmassello/uscha@latest mirador --watch   # live second-screen view (auto-refresh)
-```
-
-It defaults to the `QA-LEDGER.json` convention in the current directory (pass `--ledger` to
-point elsewhere) and prints the absolute path it wrote. `--watch` re-renders every `--interval`
-seconds (default 30) into one self-reloading tab.
-
-## Requirements
-
-| Requirement | Why |
-|-------------|-----|
-| Node.js + npm | Runs the universal `npx` entrypoint. |
-| Python 3.8+ | Runs the canonical stdlib installer and engine. |
-| Git | Used by the method and by project setup checks. |
-| Codex Desktop and/or Claude Code | The agent runtime you want to install Uscha into. |
-
-No `pip install` is required. The engine is Python stdlib-only.
-
-## Other install options
-
-| Option | Use when | Tradeoff |
-|--------|----------|----------|
-| `npx @andresmassello/uscha@latest ...` | Normal install/update on any machine. | Requires npm registry access. |
-| Git checkout + `python uscha-kit/install-uscha.py ...` | Developing Uscha itself or testing unreleased changes. | You must clone/pull the repo yourself. |
-| `--mode link` from a checkout | This machine develops the kit and installed skills should follow local edits. | Links are great for development, risky for normal users. |
-| Claude Code plugin commands | You specifically want Claude Code's native plugin flow. | Codex still needs the npm/git installer path. |
-| Manual copy | Debugging the installer. | Easy to drift; not recommended for adoption. |
-
-Development checkout example:
-
-```bash
-git clone https://github.com/andresmassello/uscha.git
-cd uscha
-python uscha-kit/install-uscha.py install --target both --mode link --dry-run
-python uscha-kit/install-uscha.py install --target both --mode link
-```
-
-Claude Code plugin option:
-
-```text
-/plugin marketplace add andresmassello/uscha
-/plugin install uscha@uscha
-```
-
-## Update and verify
-
-```bash
-npm view @andresmassello/uscha version
-npx --yes @andresmassello/uscha@latest version
-npx --yes @andresmassello/uscha@latest install --target both
-npx --yes @andresmassello/uscha@latest doctor --target both
-```
-
-`doctor` exits 1 for any unhealthy target in either text or `--json` mode. It checks installed skill presence, manifest/marketplace or hook registration, marker, and version; it does not measure file-content integrity.
-
-If `npm view` returns `404` immediately after a new release, wait a few minutes:
-npm search/dist-tags can propagate before the package metadata endpoint used by
-`npx`. Do not republish the same version while propagation is in progress.
+# Install Uscha
+
+Uscha installs as a machine-level helper for coding agents. The recommended path
+is npm/npx because it works the same on a fresh Codex or Claude Code machine.
+
+The method itself — the paradigm, the five rules, the skills and the library — lives at
+**[uscha.dev](https://uscha.dev)**.
+
+## Quick path
+
+### Codex Desktop
+
+```bash
+npx --yes @andresmassello/uscha@latest version
+npx --yes @andresmassello/uscha@latest install --target codex --dry-run
+npx --yes @andresmassello/uscha@latest install --target codex
+npx --yes @andresmassello/uscha@latest doctor --target codex
+```
+
+Then restart Codex or open a new thread. The installer registers Uscha as a
+personal local plugin under `~/plugins/uscha` and updates
+`~/.agents/plugins/marketplace.json`. It preflights that marketplace before replacing the plugin tree and writes the install marker last.
+
+### Claude Code
+
+```bash
+npx --yes @andresmassello/uscha@latest install --target claude --dry-run
+npx --yes @andresmassello/uscha@latest install --target claude
+npx --yes @andresmassello/uscha@latest doctor --target claude
+```
+
+This installs the `uscha-*` skills and registers a portable Python `PreToolUse` hook under `~/.claude` while preserving unrelated `settings.json` entries. Restart or reload Claude Code after installing.
+
+### Same machine uses both
+
+```bash
+npx --yes @andresmassello/uscha@latest install --target both --dry-run
+npx --yes @andresmassello/uscha@latest install --target both
+npx --yes @andresmassello/uscha@latest doctor --target both
+```
+
+## Prepare a project repo
+
+After the machine install, initialize each project where Uscha should govern the
+workflow:
+
+```bash
+npx --yes @andresmassello/uscha@latest init --repo . --dry-run
+npx --yes @andresmassello/uscha@latest init --repo .
+# Existing differing files are preserved; use --force only to replace them deliberately.
+npx --yes @andresmassello/uscha@latest init --repo . --force
+```
+
+`init` exits nonzero and reports conflicts for differing `uscha.config.json`, `CLAUDE.md`, `CONSTITUTION.md`, or `.gitattributes`; `--dry-run` performs the same conflict check without writing.
+
+`init` also installs the **progress statusline** (kit 1.46.0): it copies
+`.claude/scripts/uscha_{statusline,progress}.py` and merges a `statusLine` + a `Stop` hook into
+`.claude/settings.json` (never clobbering an existing `statusLine`). Add a `label`, `roadmap`
+and `build_priority` to your `repos[]` entry to drive it; with no data it stays hidden.
+
+Project state stays in the project: `uscha.config.json`, `QA-LEDGER.json`,
+`ACCEPTANCE.md`, and approved golden fixtures when used.
+
+## See the dashboard (mirador)
+
+From the root of any project that has a `QA-LEDGER.json`, one command renders the mirador and
+opens it — no python, no paths:
+
+```bash
+npx --yes @andresmassello/uscha@latest mirador           # one glance: render + open
+npx --yes @andresmassello/uscha@latest mirador --watch   # live second-screen view (auto-refresh)
+```
+
+It defaults to the `QA-LEDGER.json` convention in the current directory (pass `--ledger` to
+point elsewhere) and prints the absolute path it wrote. `--watch` re-renders every `--interval`
+seconds (default 30) into one self-reloading tab.
+
+## Requirements
+
+| Requirement | Why |
+|-------------|-----|
+| Node.js + npm | Runs the universal `npx` entrypoint. |
+| Python 3.8+ | Runs the canonical stdlib installer and engine. |
+| Git | Used by the method and by project setup checks. |
+| Codex Desktop and/or Claude Code | The agent runtime you want to install Uscha into. |
+
+No `pip install` is required. The engine is Python stdlib-only.
+
+## Other install options
+
+| Option | Use when | Tradeoff |
+|--------|----------|----------|
+| `npx @andresmassello/uscha@latest ...` | Normal install/update on any machine. | Requires npm registry access. |
+| Git checkout + `python uscha-kit/install-uscha.py ...` | Developing Uscha itself or testing unreleased changes. | You must clone/pull the repo yourself. |
+| `--mode link` from a checkout | This machine develops the kit and installed skills should follow local edits. | Links are great for development, risky for normal users. |
+| Claude Code plugin commands | You specifically want Claude Code's native plugin flow. | Codex still needs the npm/git installer path. |
+| Manual copy | Debugging the installer. | Easy to drift; not recommended for adoption. |
+
+Development checkout example:
+
+```bash
+git clone https://github.com/andresmassello/uscha.git
+cd uscha
+python uscha-kit/install-uscha.py install --target both --mode link --dry-run
+python uscha-kit/install-uscha.py install --target both --mode link
+```
+
+Claude Code plugin option:
+
+```text
+/plugin marketplace add andresmassello/uscha
+/plugin install uscha@uscha
+```
+
+## Update and verify
+
+```bash
+npm view @andresmassello/uscha version
+npx --yes @andresmassello/uscha@latest version
+npx --yes @andresmassello/uscha@latest install --target both
+npx --yes @andresmassello/uscha@latest doctor --target both
+```
+
+`doctor` exits 1 for any unhealthy target in either text or `--json` mode. It checks installed skill presence, manifest/marketplace or hook registration, marker, and version; it does not measure file-content integrity.
+
+If `npm view` returns `404` immediately after a new release, wait a few minutes:
+npm search/dist-tags can propagate before the package metadata endpoint used by
+`npx`. Do not republish the same version while propagation is in progress.

package/uscha-kit/README.md

@@ -1,6 +1,6 @@
 # uscha-kit
 
-**Kit version:** v1.59.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.61.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`,
@@ -62,6 +62,42 @@ and readiness is capped until a human runs `resolve-escalation`, after producing
 ACCEPTANCE the change turned out to deserve. **The override is asymmetric (INV-RIGOR-02):**
 you can always force the full path; nothing can force `ALLOW` over a measured `DENY`.
 
+## Golden coverage (ADR-006) — the veto knows what a golden actually covers
+
+A golden freezes behavior. Changing code a golden exercises is never a trivial change — but
+until the engine knew WHICH source files a golden covers, that veto could not be measured, so
+ADR-004 deferred it rather than ship a gate that pretended. `golden-coverage` builds the
+mapping **by measurement**:
+
+```bash
+python qa_ledger.py golden-coverage --harness tests/golden/harness-x.py --golden tests/golden/x.approved.json
+```
+
+It runs the harness under `coverage.py` and records the source files that actually executed
+into `golden.coverage.json` at the repo root (same convention as `golden.scrub.json`). The
+harnesses drive their subject through a **subprocess**, so instrumentation is injected into
+every python they spawn — measuring only the parent would record nothing and produce an empty
+map, which would read as "this golden covers nothing".
+
+Then, **opt-in**, the fast-path grows a `golden_touched` signal:
+
+```json
+"fast_path": { "forbid_when_golden_touched": true }
+```
+
+Absent or `false` → the veto does not exist and behavior is identical to earlier releases.
+Declared → **fail-closed**: touching a mapped file denies (naming the golden and the file), and
+so does a missing manifest, because "could not measure" never grants the shortcut. A malformed
+manifest exits 2 rather than degrading into a silent "no mapping". Every verdict carries the
+capture commit and tool version in the signal's `source` — provenance, not a freshness gate:
+an aged map's real risk is a false negative, which cannot be detected without re-capturing.
+
+Two honest limits (ADR-006): `coverage.py` is Python-only, so a harness in another language
+cannot produce a map — declaring the veto there yields a permanent `DENY`, and the remedy is
+not to declare it. And **file** granularity over-fires on monolithic files: in a repo whose
+engine is one large module, the veto fires on nearly every change to it. When it errs, it errs
+toward more ceremony, never less.
+
 ## Spec-drift (ADR-005) — the spec maintenance tax, made visible
 
 Specs rot silently: the code moves and `SPEC.md` stays where it was. `spec-drift` detects
@@ -91,6 +127,27 @@ spec has no commit date to compare. The latest run lands in the ledger (`spec_dr
 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.
 
+## Evidence origin (ADR-007) - green, but green at *what*?
+
+Freshness compares file mtimes, so the ledger could say "tests green" without being able to
+say which commit that was true of. Every snapshot now stamps where it came from:
+
+```json
+"origin": { "commit": "5d17cf4...", "dirty": false }
+```
+
+Measured with `git rev-parse HEAD` and `git status --porcelain` in the repo path. **Untracked
+files count as dirty** - an untracked file the suite depends on is exactly the contamination
+worth recording. **No git, no repo -> both `null`**, and `dirty: null` never reads as clean:
+a tree state nobody could measure is not a clean one.
+
+Advisory throughout: `snapshot` prints `origin=<sha8>/<clean|dirty|unknown>`,
+`dashboard --json` carries `evidence_origin` when a snapshot has one, `/uscha-status` says one
+line when the latest evidence was dirty. Readiness, phase and convergence are untouched -
+knowing a tree was dirty does not tell you the evidence is wrong, only that it was not
+produced from a commit alone. The git-worktree clean-room that would answer the stronger
+question is deliberately deferred; ADR-007 records why.
+
 ## 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.59.0
+uscha-kit 1.61.0

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

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

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

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

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

@@ -190,3 +190,21 @@ covered.
 
 Never overwrite an existing approved golden. If a `.received` already exists, regenerate it;
 if a `.approved` exists, it is the human's — leave it untouched and surface the diff.
+
+## Record the coverage map (ADR-006)
+
+After the `.received` is produced and while the harness is still the thing that just ran,
+record WHICH source files it exercised — the mapping that lets the fast-path veto a change
+touching code a golden froze:
+
+```bash
+python qa_ledger.py golden-coverage --harness <harness> --golden <the .approved sibling>
+```
+
+This is **derived measurement, not judgment**: the agent may write `golden.coverage.json`.
+INV-GOLDEN-01 governs the `.approved` bytes, which encode judgment, and nothing here changes
+that — the human still approves the golden itself.
+
+`coverage.py` is a capture-time dependency. Without it the command writes **nothing** and exits
+2: an empty map would read as "this golden covers nothing", which is exactly the lie that would
+let the veto pass. Skipping the map is honest; recording an empty one is not.

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

@@ -61,6 +61,7 @@ import re
 import shutil
 import subprocess
 import sys
+import tempfile
 import unicodedata
 import xml.etree.ElementTree as ET
 from datetime import datetime, timezone
@@ -1857,6 +1858,58 @@ def cmd_init(args):
           f"coverage_threshold={defaults.get('coverage_threshold')})")
 
 
+def _origin_label(origin):
+    """Render an origin for humans. An unmeasurable tree state reads `unknown`, never
+    `clean` -- the whole reason the field distinguishes False from None."""
+    o = origin or {}
+    sha = (o.get("commit") or "")[:8] or "no-commit"
+    dirty = o.get("dirty")
+    state = "unknown" if dirty is None else ("dirty" if dirty else "clean")
+    return "%s/%s" % (sha, state)
+
+
+def _evidence_origin(repo_path):
+    """WHERE the evidence came from: the commit it was measured at, and whether the tree
+    was clean (ADR-007). The engine's freshness check compares file MTIMES, so until now a
+    snapshot could say "tests green" without being able to say green AT WHAT -- provenance
+    true of the tree, not of the commit that will merge.
+
+    Absence is NAMED, never guessed: no git, no repo, unreadable -> both None. `dirty is
+    None` must never read as clean; that distinction is the entire point of recording it.
+    Advisory only -- nothing here scores or blocks.
+
+    Untracked files COUNT as dirty (plain --porcelain): an untracked file the suite depends
+    on is exactly the contamination this records, and treating untracked as invisible is a
+    mistake this engine already paid for once (fast-path, 1.57.0)."""
+    origin = {"commit": None, "dirty": None}
+
+    def _git(*args):
+        # OSError covers BOTH ways this used to take the whole snapshot down: git absent
+        # from PATH (FileNotFoundError) and a repo_path that does not exist or is a file
+        # (NotADirectoryError). Every sibling measurement in _snapshot already tolerates a
+        # missing path; provenance must not be the one field that can crash the command it
+        # only annotates. Same posture as _spike_branch. (Both found by fresh review, both
+        # reproduced: an unconfigured or not-yet-cloned repo path is ordinary, not exotic.)
+        try:
+            return subprocess.run(["git"] + list(args), cwd=repo_path,
+                                  capture_output=True, text=True, encoding="utf-8",
+                                  errors="replace")
+        except OSError:
+            return None
+
+    rev = _git("rev-parse", "HEAD")
+    if rev is not None and rev.returncode == 0 and rev.stdout.strip():
+        origin["commit"] = rev.stdout.strip()
+    # `-- .` scopes the answer to repo_path. Without it, a repo entry pointing at a
+    # SUBDIRECTORY of a larger working tree reports the whole outer repo's state, so an
+    # unrelated edit elsewhere would mark this repo's evidence dirty -- and the ADR would
+    # be claiming a per-path fact the code did not deliver.
+    st = _git("status", "--porcelain", "--", ".")
+    if st is not None and st.returncode == 0:
+        origin["dirty"] = bool(st.stdout.strip())
+    return origin
+
+
 def _snapshot(ledger, name):
     node = _repo_node(ledger, name)
     cfg = _repo_cfg(ledger, name) if name != "integration" else {"path": ".", "type": "maven"}
@@ -1867,6 +1920,7 @@ def _snapshot(ledger, name):
         "coverage": coverage(path, rtype),
         "tests": test_count(path, rtype),
         "loc": count_loc(path, rtype),
+        "origin": _evidence_origin(path),
     }
     node["snapshots"].append(snap)
     return snap
@@ -1886,6 +1940,7 @@ def cmd_snapshot(args):
           f"coverage={cov['pct']}% (found={cov['report_found']}), "
           f"tests={tests['total']} (found={tests['report_found']}), "
           f"freshness={freshness.get('status', 'unknown')}, "
+          f"origin={_origin_label(snap.get('origin'))}, "
           f"prod_loc={loc['prod_loc']}, test_loc={loc['test_loc']}")
     if freshness.get("status") == "stale":
         print(f"  test evidence stale: {freshness.get('reason')}")
@@ -2847,6 +2902,64 @@ def cmd_fastpath_eval(args):
                 sig("protected_paths", hits if hits else 0,
                     "no touched file matches a protected glob", "config globs over " + src,
                     not hits)
+                # ADR-006: the golden-touched veto. OPT-IN -- absent flag, no signal at all
+                # and behavior identical to 1.57.0+. DECLARED -- fail-closed: a missing or
+                # empty mapping DENIES, because "could not measure" never grants a shortcut.
+                if fp.get("forbid_when_golden_touched"):
+                    gcm = _load_golden_coverage(repo_path)   # malformed -> exit 2, never silent
+                    gmap = (gcm or {}).get("goldens") or {}
+                    # Enumerate the goldens that actually EXIST. A manifest knowing only SOME
+                    # of them would otherwise assert "no touched file is covered by a golden"
+                    # about goldens it has never measured -- an ALLOW built on ignorance, which
+                    # is precisely the silent bypass this veto exists to prevent. Found by
+                    # fresh review and reproduced: 2 goldens in the tree, 1 in the map, a diff
+                    # touching the unmapped one's source -> ALLOW. Same glob shape cmd_golden_diff
+                    # already uses to locate goldens; no new mechanism.
+                    _sfx = ".appro" + "ved"
+                    _hits = set(glob.glob(os.path.join(repo_path, "**", "*" + _sfx),
+                                          recursive=True))
+                    _hits |= set(glob.glob(os.path.join(repo_path, "**", "*" + _sfx + ".*"),
+                                           recursive=True))
+                    _tree = set()
+                    for _p in _hits:
+                        if os.path.isfile(_p):
+                            _r = _gc_rel(os.path.abspath(_p), os.path.abspath(repo_path))
+                            if _r:
+                                _tree.add(_r)
+                    _unmapped = sorted(_tree - set(gmap))
+                    if _unmapped:
+                        # covers the manifest-absent case too: with goldens present and no
+                        # manifest, every one of them is unmapped.
+                        sig("golden_touched", _unmapped[:5],
+                            "every golden in the tree carries a measured map",
+                            GOLDEN_COVERAGE_FILE + " (missing or incomplete -- run "
+                            "golden-coverage for each golden)", False)
+                    elif not _tree:
+                        # No golden exists, so none can be touched. This is a MEASUREMENT
+                        # ("nothing to cover"), not an absence of one -- denying forever a
+                        # repo that has no goldens would be ceremony, not rigor.
+                        sig("golden_touched", 0, "no golden in the tree to be covered",
+                            "glob over " + repo_path, True)
+                    else:
+                        covered = {}
+                        _commits, _tools = set(), set()
+                        for _g, _e in gcm["goldens"].items():
+                            for _f in _e.get("files", []):
+                                covered.setdefault(_f, []).append(_g)
+                            if _e.get("captured_at_commit"):
+                                _commits.add(_e["captured_at_commit"][:8])
+                            if _e.get("tool"):
+                                _tools.add(_e["tool"])
+                        ghits = ["%s (golden: %s)" % (f, ", ".join(covered[f]))
+                                 for f in files if f in covered]
+                        # provenance travels with the verdict (ADR-006: no freshness gate,
+                        # but every verdict says which capture it trusted)
+                        prov = "%s @ %s (%s)" % (
+                            GOLDEN_COVERAGE_FILE,
+                            ",".join(sorted(_commits)) if _commits else "no commit recorded",
+                            ", ".join(sorted(_tools)) if _tools else "no tool recorded")
+                        sig("golden_touched", ghits if ghits else 0,
+                            "no touched file is covered by a golden", prov, not ghits)
 
     verdict = "ALLOW" if not deny else "DENY"
     # Escalation means "an ACTIVE fast-path run outgrew its thresholds" -- so it gates on the
@@ -3072,6 +3185,158 @@ def cmd_spec_drift(args):
 
 
 
+# --------------------------------------------------------------------------- #
+# golden-coverage  (ADR-006: the golden<->source mapping, DERIVED BY MEASUREMENT)
+# --------------------------------------------------------------------------- #
+
+GOLDEN_COVERAGE_FILE = "golden.coverage.json"
+
+
+def _load_golden_coverage(root):
+    """Read the measured golden<->source manifest. Strict shape, mirroring
+    _load_scrub_rules: a typo must NOT degrade into "no mapping" in silence, because
+    under a declared veto that silence would GRANT the shortcut it exists to deny.
+    Absent file -> None (the caller decides; with the veto declared, absent is DENY)."""
+    path = os.path.join(root, GOLDEN_COVERAGE_FILE)
+    if not os.path.isfile(path):
+        return None
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            spec = json.load(fh)
+        if not isinstance(spec, dict) or not isinstance(spec.get("goldens"), dict):
+            raise TypeError('expected {"goldens": {"<golden path>": {"files": [...]}}}')
+        for g, entry in spec["goldens"].items():
+            if not isinstance(entry, dict) or not isinstance(entry.get("files"), list):
+                raise TypeError("golden %r has no files list" % g)
+            for f in entry["files"]:
+                if not isinstance(f, str):
+                    raise TypeError("golden %r maps a non-string file" % g)
+        return spec
+    except (json.JSONDecodeError, TypeError, KeyError) as exc:
+        print("[qa_ledger] %s invalid (%s) - the golden mapping is not skipped in "
+              "silence: fix the file or delete it." % (path, exc), file=sys.stderr)
+        sys.exit(2)
+
+
+def _gc_rel(path, root):
+    # realpath BOTH sides before comparing. On Windows a temp dir under a username longer
+    # than 8 chars is reported in 8.3 short form (RUNNER~1) by one side and long form by the
+    # other; relpath then yields "../.." and a file INSIDE the repo is filtered out as
+    # outside it -- silently shrinking the map. Invisible on a machine whose username does
+    # not mangle (which is why local Windows was green and Windows CI was not).
+    try:
+        rel = os.path.relpath(os.path.realpath(path), os.path.realpath(root))
+    except ValueError:      # different drive on Windows -- outside the repo either way
+        return None
+    rel = rel.replace("\\", "/")
+    return None if rel.startswith("../") else rel
+
+
+def cmd_golden_coverage(args):
+    """Record the MEASURED source files a golden's harness exercises (ADR-006).
+
+    The harnesses drive their subject through subprocess, so instrumenting only the parent
+    measures nothing: coverage is injected into EVERY python the harness spawns via a
+    sitecustomize on PYTHONPATH plus COVERAGE_PROCESS_START -- the documented multiprocess
+    technique, and the same PYTHONPATH-injection shape this repo's fault tests already use.
+
+    coverage.py is an optional CAPTURE-time dependency (the engine stays stdlib-only at
+    runtime). Absent, this writes NOTHING and exits 2: an empty map would read as
+    "this golden covers nothing", which is the one lie that would let the veto pass."""
+    try:
+        import coverage
+    except ImportError:
+        print("[qa_ledger] coverage.py is not installed - refusing to write a map that was "
+              "not measured (an empty map reads as 'covers nothing'). pip install coverage",
+              file=sys.stderr)
+        sys.exit(2)
+
+    root = os.path.abspath(args.dir or ".")
+    harness = os.path.abspath(args.harness)
+    if not os.path.isfile(harness):
+        print("[qa_ledger] harness not found: %s" % harness, file=sys.stderr)
+        sys.exit(2)
+
+    tmp = tempfile.mkdtemp(prefix="uscha-gc-")
+    try:
+        data_file = os.path.join(tmp, ".coverage")
+        rc = os.path.join(tmp, "cov.rc")
+        with open(rc, "w", encoding="utf-8") as fh:
+            fh.write("[run]\nparallel = True\ndata_file = %s\n"
+                     % data_file.replace("\\", "/"))
+        with open(os.path.join(tmp, "sitecustomize.py"), "w", encoding="utf-8") as fh:
+            fh.write("import coverage\ncoverage.process_startup()\n")
+
+        env = dict(os.environ)
+        env["COVERAGE_PROCESS_START"] = rc
+        env["PYTHONPATH"] = tmp + os.pathsep + env.get("PYTHONPATH", "")
+        env["PYTHONIOENCODING"] = "utf-8"
+        r = subprocess.run([sys.executable, harness], cwd=root, env=env,
+                           capture_output=True, text=True, encoding="utf-8",
+                           errors="replace")
+        if r.returncode != 0:
+            print("[qa_ledger] the harness failed (exit %d) - no map recorded from a run "
+                  "that did not complete:\n%s" % (r.returncode, (r.stderr or "")[-1500:]),
+                  file=sys.stderr)
+            sys.exit(2)
+
+        cov = coverage.Coverage(data_file=data_file)
+        try:
+            cov.combine()
+            cov.save()
+        except Exception as exc:
+            # Never silent: a PARTIAL combine yields an incomplete-but-non-empty file list,
+            # which slips past the empty-map guard below and records a map that under-reports
+            # what the golden covers. The empty case still exits 2; this one is announced so a
+            # human sees the map may be short (fresh-review finding).
+            print("[qa_ledger] coverage combine reported: %s - the map below may be "
+                  "incomplete; re-run before trusting it." % exc, file=sys.stderr)
+        measured = sorted(cov.get_data().measured_files())
+        harness_rel = _gc_rel(harness, root)
+        files = []
+        for m in measured:
+            rel = _gc_rel(os.path.abspath(m), root)
+            # the harness measures the SUBJECT, not itself; sitecustomize is our scaffolding
+            if not rel or rel == harness_rel or rel.endswith("/sitecustomize.py"):
+                continue
+            files.append(rel)
+        files = sorted(set(files))
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+    if not files:
+        print("[qa_ledger] the run measured no source file inside %s - refusing to record "
+              "an empty map (it would read as 'covers nothing')." % root, file=sys.stderr)
+        sys.exit(2)
+
+    head = subprocess.run(["git", "rev-parse", "HEAD"], cwd=root,
+                          capture_output=True, text=True)
+    commit = head.stdout.strip() if head.returncode == 0 else None
+    golden_rel = _gc_rel(os.path.abspath(args.golden), root) or args.golden
+
+    path = os.path.join(root, GOLDEN_COVERAGE_FILE)
+    manifest = _load_golden_coverage(root) or {"goldens": {}}
+    manifest["goldens"][golden_rel] = {
+        "harness": harness_rel,
+        "files": files,
+        "captured_at": _now(),
+        "captured_at_commit": commit,
+        "tool": "coverage.py " + coverage.__version__,
+    }
+    with open(path, "w", encoding="utf-8", newline="\n") as fh:
+        json.dump(manifest, fh, indent=2, ensure_ascii=False, sort_keys=True)
+        fh.write("\n")
+
+    if args.json:
+        print(json.dumps(manifest["goldens"][golden_rel], indent=2, ensure_ascii=False))
+    else:
+        print("GOLDEN-COVERAGE %s: %d source file(s) measured -> %s"
+              % (golden_rel, len(files), GOLDEN_COVERAGE_FILE))
+        for f in files[:20]:
+            print("  " + f)
+
+
+
 def cmd_escalate(args):
     ledger = _load(args.ledger)
     _repo_node(ledger, args.repo)
@@ -4108,6 +4373,16 @@ def cmd_dashboard(args):
                             for r in {e.get("repo") for e in ledger["fast_path"]}}
     if ledger.get("spec_drift"):
         out["spec_drift"] = ledger["spec_drift"]
+    # evidence_origin: the latest snapshot's origin per repo, and ONLY when one exists --
+    # a ledger predating ADR-007 keeps the exact prior schema (same conditional-key rule
+    # fast_path and spec_drift already follow).
+    _org = {}
+    for _rn, _rnode in ledger["repos"].items():
+        _snaps = _rnode.get("snapshots") or []
+        if _snaps and _snaps[-1].get("origin"):
+            _org[_rn] = _snaps[-1]["origin"]
+    if _org:
+        out["evidence_origin"] = _org
     if getattr(args, "json", False):
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return
@@ -6812,6 +7087,14 @@ def build_parser():
     pfp.add_argument("--json", action="store_true")
     pfp.set_defaults(func=cmd_fastpath_eval)
 
+    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")
+    pgc.add_argument("--golden", required=True, help="the golden this map belongs to")
+    pgc.add_argument("--dir", default=".", help="repo root holding " + GOLDEN_COVERAGE_FILE)
+    pgc.add_argument("--json", action="store_true")
+    pgc.set_defaults(func=cmd_golden_coverage)
+
     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")

package/uscha-kit/skills/uscha-mirador/mirador-watch.ps1

@@ -1,22 +1,22 @@
-# mirador-watch.ps1 -- live second-screen mirador (uscha-kit 1.34.0), Windows.
-# Regenerates mirador.html every N seconds from the current ledger; the page is rendered
-# with a meta-refresh at the same interval, so a browser open on it updates on its own.
-#
-# Usage (run in a spare terminal, from the project root):
-#   powershell -NoProfile -File <kit>\.claude\skills\uscha-mirador\mirador-watch.ps1 [-Interval 30]
-# then open mirador.html in a browser on your second screen. Ctrl-C to stop.
-#
-# Overridable via env: ENGINE, LEDGER, TEMPLATE, OUT, PYTHON.
-param([int]$Interval = 30)
-$here     = Split-Path -Parent $MyInvocation.MyCommand.Path
-$engine   = if ($env:ENGINE)   { $env:ENGINE }   else { Join-Path $here "..\uscha-devloop\qa_ledger.py" }
-$ledger   = if ($env:LEDGER)   { $env:LEDGER }   else { "QA-LEDGER.json" }
-$template = if ($env:TEMPLATE) { $env:TEMPLATE } else { Join-Path $here "mirador.template.html" }
-$out      = if ($env:OUT)      { $env:OUT }      else { "mirador.html" }
-$py       = if ($env:PYTHON)   { $env:PYTHON }   else { "python" }
-Write-Host "mirador-watch: regenerating $out every ${Interval}s (Ctrl-C to stop). Open $out in a browser."
-while ($true) {
-  & $py (Join-Path $here "mirador-render.py") --engine $engine --ledger $ledger --template $template --out $out --refresh $Interval --no-open
-  if ($LASTEXITCODE -ne 0) { Write-Host "mirador-watch: render failed (ledger missing? run uscha-devloop first) -- retrying" }
-  Start-Sleep -Seconds $Interval
-}
+# mirador-watch.ps1 -- live second-screen mirador (uscha-kit 1.34.0), Windows.
+# Regenerates mirador.html every N seconds from the current ledger; the page is rendered
+# with a meta-refresh at the same interval, so a browser open on it updates on its own.
+#
+# Usage (run in a spare terminal, from the project root):
+#   powershell -NoProfile -File <kit>\.claude\skills\uscha-mirador\mirador-watch.ps1 [-Interval 30]
+# then open mirador.html in a browser on your second screen. Ctrl-C to stop.
+#
+# Overridable via env: ENGINE, LEDGER, TEMPLATE, OUT, PYTHON.
+param([int]$Interval = 30)
+$here     = Split-Path -Parent $MyInvocation.MyCommand.Path
+$engine   = if ($env:ENGINE)   { $env:ENGINE }   else { Join-Path $here "..\uscha-devloop\qa_ledger.py" }
+$ledger   = if ($env:LEDGER)   { $env:LEDGER }   else { "QA-LEDGER.json" }
+$template = if ($env:TEMPLATE) { $env:TEMPLATE } else { Join-Path $here "mirador.template.html" }
+$out      = if ($env:OUT)      { $env:OUT }      else { "mirador.html" }
+$py       = if ($env:PYTHON)   { $env:PYTHON }   else { "python" }
+Write-Host "mirador-watch: regenerating $out every ${Interval}s (Ctrl-C to stop). Open $out in a browser."
+while ($true) {
+  & $py (Join-Path $here "mirador-render.py") --engine $engine --ledger $ledger --template $template --out $out --refresh $Interval --no-open
+  if ($LASTEXITCODE -ne 0) { Write-Host "mirador-watch: render failed (ledger missing? run uscha-devloop first) -- retrying" }
+  Start-Sleep -Seconds $Interval
+}

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

@@ -90,6 +90,12 @@ Line guide:
 block with the latest verdict per repo (`fast-path: ALLOW (intent...)` / `ESCALATED`). Absent
 entries → no line at all: silence is honest when no mode was requested.
 
+**Evidence origin (ADR-007):** if the latest snapshot was measured on a DIRTY tree, add ONE
+line: `evidence: measured dirty at <sha8> - not from the commit alone`. Say nothing when the
+tree was clean (the normal case needs no words) and nothing when it is `null` (unmeasurable,
+and inventing a state is worse than silence). This never explains a blocked phase: it scores
+nothing and gates nothing.
+
 **Spec-drift (ADR-005):** if the ledger carries a `spec_drift` run, add ONE line:
 `spec-drift: N stale / M docs (advisory)` — or `spec-drift: no drift measured` when zero are
 stale. Always label it advisory; it never explains a blocked phase. Absent key → no line.

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.59.0",
+  "version": "1.61.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,
@@ -49,7 +49,8 @@
         "**/*.approved",
         "db/**"
       ],
-      "require_asserting_test": true
+      "require_asserting_test": true,
+      "forbid_when_golden_touched": false
     },
     "spec_drift": {
       "max_lag_days": 30