@andresmassello/uscha 1.56.1 → 1.60.1

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

@@ -59,7 +59,9 @@ import math
 import os
 import re
 import shutil
+import subprocess
 import sys
+import tempfile
 import unicodedata
 import xml.etree.ElementTree as ET
 from datetime import datetime, timezone
@@ -2699,6 +2701,588 @@ def cmd_oscillation(args):
     sys.exit(1 if osc else 0)
 
 
+# --------------------------------------------------------------------------- #
+# fastpath-eval  (ADR-003: fast-path entry by MEASURED signals, never opinion)
+# --------------------------------------------------------------------------- #
+
+def _fp_glob_re(g):
+    """Translate a protected-path glob to a regex. `**` crosses directories, `*`/`?` do not.
+    Case-insensitive on purpose: Windows and macOS filesystems are."""
+    g = g.replace("\\", "/")
+    out, i = [], 0
+    while i < len(g):
+        c = g[i]
+        if c == "*":
+            if g[i:i + 2] == "**":
+                i += 2
+                if i < len(g) and g[i] == "/":
+                    # `**/` = any number of WHOLE directories (incl. zero) -- segment-anchored,
+                    # so `**/migrations/**` does not match `db_migrations/` by substring.
+                    out.append("(?:[^/]*/)*")
+                    i += 1
+                else:
+                    out.append(".*")
+                continue
+            out.append("[^/]*")
+        elif c == "?":
+            out.append("[^/]")
+        elif c in ".^$+{}[]|()":
+            out.append("\\" + c)
+        else:
+            out.append(c)
+        i += 1
+    return re.compile("^(?:%s)$" % "".join(out), re.I)
+
+
+def cmd_fastpath_eval(args):
+    """Measured verdict for the fast-path (ADR-003). ALLOW only when every signal passes;
+    ANY ambiguity -- no config, no git, unresolvable base -- is DENY with the reason named
+    (fail-closed: "could not measure" never grants the shortcut). With --intent the verdict is
+    recorded in the ledger as a first-class entry; without it this is a dry-run. A prior ALLOW
+    followed by a DENY re-eval escalates through the EXISTING escalation machinery, so the
+    derived phase flips to `escalated` and pr-ready is blocked until the human resolves."""
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    fp = ledger["config"].get("defaults", {}).get("fast_path")
+    intent = (args.intent or "").strip()
+    signals, deny = [], []
+
+    def sig(name, value, threshold, source, ok):
+        signals.append({"name": name, "value": value, "threshold": threshold,
+                        "source": source, "at": _now(), "ok": bool(ok)})
+        if not ok:
+            deny.append(name)
+
+    if not isinstance(fp, dict) or fp.get("enabled") is False:
+        sig("configured", False, "defaults.fast_path present and enabled",
+            "config.defaults.fast_path", False)
+    else:
+        repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+        base, base_src = args.base, "--base"
+        if base:
+            probe = subprocess.run(["git", "rev-parse", "--verify", base + "^{commit}"],
+                                   cwd=repo_path, capture_output=True, text=True)
+            if probe.returncode != 0:
+                base = None
+                base_src = "--base (unresolvable)"
+        else:
+            for cand in ("origin/main", "main"):
+                r = subprocess.run(["git", "merge-base", "HEAD", cand], cwd=repo_path,
+                                   capture_output=True, text=True)
+                if r.returncode == 0 and r.stdout.strip():
+                    base, base_src = r.stdout.strip(), "merge-base HEAD %s" % cand
+                    break
+        if not base:
+            sig("base_ref", None, "a resolvable base commit",
+                base_src if base_src != "--base" else "git merge-base HEAD origin/main|main",
+                False)
+        else:
+            num = subprocess.run(["git", "diff", "--numstat", base], cwd=repo_path,
+                                 capture_output=True, text=True, encoding="utf-8",
+                                 errors="replace")
+            if num.returncode != 0:
+                sig("git_diff", None, "a readable diff",
+                    "git diff --numstat %s" % base[:12], False)
+            else:
+                files, loc, binaries = [], 0, []
+                for line in num.stdout.splitlines():
+                    parts = line.split("\t")
+                    if len(parts) != 3:
+                        continue
+                    a, d, path = parts
+                    path = path.strip().replace("\\", "/")
+                    # RENAMES arrive as one descriptor -- `old => new` or `pre{old => new}post`.
+                    # Matching the raw descriptor against the globs let a rename INTO db/ walk
+                    # straight past protected_paths (found by fresh review). Expand it and
+                    # count BOTH sides: renaming a file out of a protected area is as
+                    # gate-worthy as renaming one in.
+                    if " => " in path:
+                        m_ = re.match(r"^(.*)\{(.*) => (.*)\}(.*)$", path)
+                        if m_:
+                            pre, old_, new_, post = m_.groups()
+                            files.append((pre + old_ + post).replace("//", "/"))
+                            files.append((pre + new_ + post).replace("//", "/"))
+                        else:
+                            old_, new_ = path.split(" => ", 1)
+                            files.append(old_)
+                            files.append(new_)
+                    else:
+                        files.append(path)
+                    if a == "-" or d == "-":
+                        # binary diff: LOC is UNMEASURABLE, and an unmeasurable signal must
+                        # deny, not silently count as zero (fail-closed).
+                        binaries.append(path)
+                    loc += (int(a) if a.isdigit() else 0) + (int(d) if d.isdigit() else 0)
+                # UNTRACKED files are invisible to `git diff` -- and a small change is very
+                # often a NEW file. Not counting them would under-measure exactly the case
+                # this gate exists for, so they count as files + added lines (fail-closed).
+                unt = subprocess.run(["git", "ls-files", "--others", "--exclude-standard"],
+                                     cwd=repo_path, capture_output=True, text=True,
+                                     encoding="utf-8", errors="replace")
+                for path in unt.stdout.splitlines():
+                    path = path.strip()
+                    if not path:
+                        continue
+                    files.append(path.replace("\\", "/"))
+                    try:
+                        with open(os.path.join(repo_path, path), "rb") as fh:
+                            loc += fh.read().count(b"\n")
+                    except OSError:
+                        loc += 1  # an unreadable new file still counts as a change
+                src = "git diff --numstat %s (+ untracked)" % base[:12]
+                max_f = int(fp.get("max_files_changed", 3))
+                max_l = int(fp.get("max_loc_delta", 80))
+                sig("max_files_changed", len(files), max_f, src, len(files) <= max_f)
+                sig("max_loc_delta", loc, max_l, src, loc <= max_l)
+                if binaries:
+                    sig("binary_files", binaries[:5], "none (LOC unmeasurable on binary)",
+                        src, False)
+                pats = fp.get("protected_paths",
+                              ["**/migrations/**", "**/*.appro" + "ved", "db/**"])
+                hits = []
+                for f in files:
+                    for g in pats:
+                        if _fp_glob_re(g).match(f):
+                            hits.append("%s (%s)" % (f, g))
+                            break
+                sig("protected_paths", hits if hits else 0,
+                    "no touched file matches a protected glob", "config globs over " + src,
+                    not hits)
+                # 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
+    # LATEST entry for this repo being ALLOW, not on an ALLOW ever having existed. The first
+    # version scanned all history, which misclassified every later unrelated DENY as ESCALATED
+    # forever (found by fresh review, reproduced in ordinary sequential usage).
+    _fp_prior = [e for e in ledger.get("fast_path", []) if e.get("repo") == args.repo]
+    active_allow = bool(_fp_prior) and _fp_prior[-1].get("verdict") == "ALLOW"
+    escalated = bool(intent and active_allow and verdict == "DENY"
+                     and "configured" not in deny)
+    if escalated:
+        verdict = "ESCALATED"
+    out = {"repo": args.repo, "mode": "fast_path", "verdict": verdict,
+           "intent": intent or None, "dry_run": not bool(intent), "signals": signals}
+
+    if intent:
+        ledger.setdefault("fast_path", [])
+        ledger["step_counter"] += 1
+        entry = dict(out)
+        entry.pop("dry_run", None)
+        entry.update({"n": ledger["step_counter"], "at": _now()})
+        ledger["fast_path"].append(entry)
+        ledger["steps"].append({"n": ledger["step_counter"], "at": _now(),
+                                "kind": "fastpath-eval", "repo": args.repo})
+        if escalated:
+            # reuse the EXISTING escalation machinery: derived phase flips to `escalated`,
+            # pr-ready is blocked and readiness capped until the human resolve-escalation --
+            # after producing ADR + ACCEPTANCE, per ADR-003 (not a full discovery).
+            ledger["step_counter"] += 1
+            ledger["escalations"].append({
+                "n": ledger["step_counter"], "at": _now(), "repo": args.repo,
+                "reason": "fast-path thresholds exceeded mid-run: " + ", ".join(deny)
+                          + " -- produce ADR + ACCEPTANCE, then resolve-escalation"})
+            ledger["steps"].append({"n": ledger["step_counter"], "at": _now(),
+                                    "kind": "escalation", "repo": args.repo})
+        _save(args.ledger, ledger)
+
+    if args.json:
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        print("FASTPATH %s: %s%s" % (args.repo, verdict,
+              "" if intent else "  (dry-run: no --intent, nothing recorded)"))
+        for s_ in signals:
+            print("  %s %s: %s / %s  [%s]" % ("ok" if s_["ok"] else "!!",
+                  s_["name"], s_["value"], s_["threshold"], s_["source"]))
+        if escalated:
+            print("  -> ESCALATED: pr-ready is blocked; produce ADR + ACCEPTANCE, "
+                  "then resolve-escalation (a recorded human act)")
+    sys.exit(0 if verdict == "ALLOW" else 1)
+
+
+# --------------------------------------------------------------------------- #
+# spec-drift  (ADR-005: mechanical drift detection, advisory -- NEVER a gate)
+# --------------------------------------------------------------------------- #
+
+def _sd_governs(path):
+    """Parse the `governs:` glob list from a `---` frontmatter block at the top of a
+    markdown file. Returns None when there is no frontmatter or no `governs:` key
+    (UNMAPPED -- absence of a mapping is absence of measurement, not "no drift")."""
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            lines = fh.read().splitlines()
+    except OSError:
+        return None
+    if not lines or lines[0].strip() != "---":
+        return None
+    globs, in_governs = None, False
+    # scan runs to the CLOSING fence, not an arbitrary window -- a governs: key late in a
+    # long frontmatter block must not silently read as UNMAPPED (fresh-review finding).
+    for ln in lines[1:]:
+        s = ln.strip()
+        if s == "---":
+            break
+        if s.startswith("governs:"):
+            rest = s[len("governs:"):].strip()
+            if rest.startswith("[") and rest.endswith("]"):
+                globs = [x.strip().strip("\x27\x22")
+                         for x in rest[1:-1].split(",") if x.strip()]
+                in_governs = False
+            elif rest:
+                # bare scalar (`governs: src/**`) -- a plausible authoring shorthand;
+                # dropping it silently would report a misleading "globs match nothing".
+                globs, in_governs = [rest.strip("\x27\x22")], False
+            else:
+                globs, in_governs = [], True
+            continue
+        if in_governs:
+            if s.startswith("- "):
+                globs.append(s[2:].strip().strip("\x27\x22"))
+            elif s and not ln.startswith((" ", "\t")):
+                in_governs = False
+    return globs
+
+
+def _sd_iso(ct):
+    import datetime as _dt
+    return _dt.datetime.fromtimestamp(ct, _dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _sd_last_commit_ct(repo_path, paths):
+    """Newest commit epoch touching any of `paths` (chunked: command lines have limits).
+    None when no commit touches them (untracked)."""
+    newest = None
+    for i in range(0, len(paths), 200):
+        r = subprocess.run(["git", "log", "-1", "--format=%ct", "--"] + paths[i:i + 200],
+                           cwd=repo_path, capture_output=True, text=True,
+                           encoding="utf-8", errors="replace")
+        out = r.stdout.strip().splitlines()
+        if r.returncode == 0 and out and out[0].strip().isdigit():
+            ct = int(out[0].strip())
+            newest = ct if newest is None else max(newest, ct)
+    return newest
+
+
+def cmd_spec_drift(args):
+    """Advisory drift report (ADR-005): last commit date of each spec doc vs. the newest
+    commit touching the files its `governs:` globs map to. SPEC_STALE when governed code
+    outran the spec by more than max_lag_days; UNMAPPED when there is no (effective)
+    mapping; UNTRACKED when the spec has no commit date to compare. This command NEVER
+    gates: a stale spec is a prompt for a human conversation, not a blocked pipeline.
+    Exit code 0 always."""
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    cfg = ledger["config"].get("defaults", {}).get("spec_drift") or {}
+    lag_days = int(args.max_lag_days if args.max_lag_days is not None
+                   else cfg.get("max_lag_days", 30))
+    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+
+    # The spec surface is fixed by ADR-005: the repo SPEC.md plus every ADR.
+    spec_files = []
+    if os.path.isfile(os.path.join(repo_path, "SPEC.md")):
+        spec_files.append("SPEC.md")
+    adr_dir = os.path.join(repo_path, "docs", "adr")
+    if os.path.isdir(adr_dir):
+        spec_files += sorted("docs/adr/" + f for f in os.listdir(adr_dir)
+                             if f.lower().endswith(".md"))
+
+    tracked = []
+    ls = subprocess.run(["git", "ls-files"], cwd=repo_path, capture_output=True,
+                        text=True, encoding="utf-8", errors="replace")
+    if ls.returncode == 0:
+        tracked = [l.strip().replace("\\", "/") for l in ls.stdout.splitlines() if l.strip()]
+
+    results = []
+    for spec in spec_files:
+        governs = _sd_governs(os.path.join(repo_path, spec))
+        row = {"file": spec, "governs": governs, "max_lag_days": lag_days}
+        if governs is None:
+            row.update({"verdict": "UNMAPPED", "reason": "no governs: frontmatter"})
+            results.append(row)
+            continue
+        matched = []
+        pats = [_fp_glob_re(g) for g in governs]
+        for f in tracked:
+            if f == spec:
+                continue  # a spec governing itself would always read fresh -- excluded
+            if any(p.match(f) for p in pats):
+                matched.append(f)
+        if not matched:
+            # A mapping that matches nothing measures nothing -- same absence, named.
+            row.update({"verdict": "UNMAPPED", "reason": "globs match no tracked files"})
+            results.append(row)
+            continue
+        spec_ct = _sd_last_commit_ct(repo_path, [spec])
+        if spec_ct is None:
+            row.update({"verdict": "UNTRACKED",
+                        "reason": "spec has no commit date to compare"})
+            results.append(row)
+            continue
+        newest = _sd_last_commit_ct(repo_path, matched)
+        lag_s = lag_days * 86400
+        row.update({"governed_files": len(matched),
+                    "spec_committed_at": _sd_iso(spec_ct),
+                    "newest_governed_at": _sd_iso(newest) if newest is not None else None})
+        if newest is not None and newest - spec_ct > lag_s:
+            import datetime as _dt
+            cutoff = _dt.datetime.fromtimestamp(
+                spec_ct + lag_s, _dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%S+0000")
+            newer = set()
+            for i in range(0, len(matched), 200):
+                r = subprocess.run(["git", "log", "--since", cutoff, "--name-only",
+                                    "--format=", "--"] + matched[i:i + 200],
+                                   cwd=repo_path, capture_output=True, text=True,
+                                   encoding="utf-8", errors="replace")
+                if r.returncode == 0:
+                    newer |= {l.strip().replace("\\", "/")
+                              for l in r.stdout.splitlines() if l.strip()}
+            newer &= set(matched)
+            row.update({"verdict": "SPEC_STALE",
+                        "lag_days_actual": round((newest - spec_ct) / 86400.0, 1),
+                        "newer_files": sorted(newer)[:20],
+                        "newer_files_total": len(newer)})
+        else:
+            row["verdict"] = "CLEAN"
+        results.append(row)
+
+    out = {"repo": args.repo, "max_lag_days": lag_days, "results": results,
+           "advisory": True}
+
+    # Latest-state record so the mirador can surface an advisory row. Advisory data,
+    # not a step in the loop: no step_counter, no gate record, no readiness input.
+    ledger["spec_drift"] = {"repo": args.repo, "at": _now(), "max_lag_days": lag_days,
+                            "results": results}
+    _save(args.ledger, ledger)
+
+    if args.json:
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        print("SPEC-DRIFT %s (advisory, lag > %dd):" % (args.repo, lag_days))
+        if not results:
+            print("  no spec documents found (SPEC.md / docs/adr/*.md)")
+        mark = {"SPEC_STALE": "!!", "CLEAN": "ok", "UNMAPPED": "--", "UNTRACKED": "--"}
+        for r_ in results:
+            line = "  %s %s: %s" % (mark.get(r_["verdict"], "??"), r_["file"],
+                                    r_["verdict"])
+            if r_["verdict"] == "SPEC_STALE":
+                line += " -- %d governed file(s) newer, e.g. %s" % (
+                    r_["newer_files_total"], ", ".join(r_["newer_files"][:3]))
+            elif "reason" in r_:
+                line += " (%s)" % r_["reason"]
+            print(line)
+    sys.exit(0)
+
+
+
+# --------------------------------------------------------------------------- #
+# 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)
@@ -3726,6 +4310,15 @@ def cmd_dashboard(args):
         "snapshots": snapshots,
         "evidence": ev,       # receipts (kit 1.50.0): facts with paths + timestamps
     }
+    # fast-path (ADR-003): latest verdict per repo, straight from the ledger. The key exists
+    # ONLY when entries exist: an unconfigured/unused project keeps the exact prior schema
+    # ("absent block = behavior identical" is a measured claim, and an unconditional key was
+    # a schema change that contradicted it -- found by fresh review).
+    if ledger.get("fast_path"):
+        out["fast_path"] = {r: [e for e in ledger["fast_path"] if e.get("repo") == r][-1]
+                            for r in {e.get("repo") for e in ledger["fast_path"]}}
+    if ledger.get("spec_drift"):
+        out["spec_drift"] = ledger["spec_drift"]
     if getattr(args, "json", False):
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return
@@ -3897,6 +4490,24 @@ def cmd_readiness(args):
                             caps["blocker_critical"], "blocker_critical"))
     if any(not e.get("resolved_at") for e in ledger.get("escalations", [])):
         caps_active.append(("unresolved escalation", caps["escalation"], "escalation"))
+    # AC-FP-06 (ADR-003): an active fast-path run still owes an asserting test. The latest
+    # fast_path entry per repo being ALLOW, with NO measured test execution recorded at or
+    # after it, caps readiness -- reusing the escalation cap value, per the existing cap
+    # mechanics rather than inventing a new one.
+    fp_cfg = ledger["config"].get("defaults", {}).get("fast_path")
+    if isinstance(fp_cfg, dict) and fp_cfg.get("require_asserting_test", True):
+        for _fp_repo in {e.get("repo") for e in ledger.get("fast_path", [])}:
+            entries = [e for e in ledger["fast_path"] if e.get("repo") == _fp_repo]
+            last = entries[-1] if entries else None
+            if not last or last.get("verdict") != "ALLOW":
+                continue
+            node_fp = ledger["repos"].get(_fp_repo, {})
+            tested = any((s.get("tests", {}).get("executed", 0) or 0) > 0
+                         and s.get("at", "") >= last.get("at", "")
+                         for s in node_fp.get("snapshots", []))
+            if not tested:
+                caps_active.append(("fast-path active in %s without a measured asserting test"
+                                    % _fp_repo, caps["escalation"], "escalation"))
     if spec_doubts_open:
         caps_active.append((f"{len(spec_doubts_open)} spec-doubt open",
                             caps["escalation"], "escalation"))
@@ -6403,6 +7014,31 @@ def build_parser():
     pe.add_argument("--reason", required=True)
     pe.set_defaults(func=cmd_escalate)
 
+    pfp = sub.add_parser("fastpath-eval",
+                         help="measured fast-path verdict (ADR-003): ALLOW/DENY from the real diff; --intent records it")
+    pfp.add_argument("--ledger", default="QA-LEDGER.json")
+    pfp.add_argument("--repo", required=True)
+    pfp.add_argument("--base", help="base commit/ref; default merge-base HEAD origin/main (fallback main)")
+    pfp.add_argument("--intent", help="one sentence, what and why; without it the call is a dry-run")
+    pfp.add_argument("--json", action="store_true")
+    pfp.set_defaults(func=cmd_fastpath_eval)
+
+    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")
+    psd.add_argument("--repo", required=True)
+    psd.add_argument("--max-lag-days", type=int, default=None,
+                     help="override defaults.spec_drift.max_lag_days (default 30)")
+    psd.add_argument("--json", action="store_true")
+    psd.set_defaults(func=cmd_spec_drift)
     pre = sub.add_parser("resolve-escalation",
                          help="close open escalations for a repo (recorded event; "
                               "lifts the readiness cap)")