@andresmassello/uscha 1.59.0 → 1.60.1

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.60.1** <!-- 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.60.1",
   "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
@@ -2847,6 +2848,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 +3131,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)
@@ -6812,6 +7023,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-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.60.1",
   "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.60.1",
   "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.60.1 <!-- 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

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.59.0
+uscha-kit 1.60.1

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/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
@@ -2847,6 +2848,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 +3131,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)
@@ -6812,6 +7023,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/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.59.0",
+  "version": "1.60.1",
   "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