@andresmassello/uscha 1.91.0 → 1.93.0

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

@@ -642,7 +642,7 @@ _SRC_EXT = {
     ".java", ".kt", ".kts", ".scala", ".groovy", ".py", ".js", ".jsx",
     ".ts", ".tsx", ".mjs", ".cjs", ".go", ".rs", ".cs", ".vb", ".fs",
     ".cpp", ".cc", ".cxx", ".c", ".h", ".hpp", ".swift", ".m", ".mm",
-    ".rb", ".php", ".dart", ".gradle",
+    ".rb", ".php", ".dart", ".gradle", ".hh", ".hxx",
 }
 _SRC_SKIP_DIRS = SKIP_DIRS | {"reports", "Pods", ".vs"}
 
@@ -701,10 +701,135 @@ def _source_newest_mtime(repo_path):
     return newest["mtime_ns"] / 1_000_000_000 if newest else 0.0
 
 
-def _test_evidence_provenance(repo_path, repo_type):
+# kit 1.93.0 (ADR-039): the clock is not the only honest freshness rule. A fresh clone, a
+# `git worktree add`, a merge or a CI checkout re-date every source file without changing a
+# byte of source, and rule (a) then throws away evidence that IS current -- the day INV-T1
+# shipped, the release machine read 0/195 for exactly that reason. Rule (b) asks the question
+# a timestamp cannot: has any SOURCE file changed since the commit the last snapshot was
+# measured at, and is the report still the exact file that was ingested? Either rule
+# suffices; both are measured. No git, no recorded commit, no recorded hash -> (a) alone,
+# byte-identical to 1.92.0.
+def _git_path_list(text):
+    """Paths from `git diff --name-only`: C-quotes stripped, forward slashes. An escape
+    inside a quoted path is left as-is -- that can only fail to MATCH, which withholds
+    freshness rather than granting it (the safe direction, same posture as `_porcelain_paths`)."""
+    out = []
+    for line in (text or "").splitlines():
+        p = line.strip()
+        if len(p) >= 2 and p[0] == '"' and p[-1] == '"':
+            p = p[1:-1]
+        if p:
+            out.append(p.replace("\\", "/"))
+    return out
+
+
+# What rule (b) and the seal treat as "a change that invalidates a test run", BEYOND the source
+# code itself: the build and harness files that decide WHAT the suite runs and HOW. A commit that
+# rewrites `smoke-engine.sh`, a `pom.xml` or a CI workflow changes the meaning of a green report
+# just as surely as editing the code under test, and a seal that tolerated it would be tolerating
+# the one edit a green board cannot survive. Deliberately NOT here, and named in ADR-039 and
+# SPEC 4: `.md`, `.json`, `.xml`, `.txt` -- docs, changelogs, the ledger and the JUnit reports
+# themselves are non-source BY CONSTRUCTION, which is the whole point of the tolerant seal.
+# (`package.json` and `pyproject.toml` are the named exceptions: they carry the test command.)
+_HARNESS_EXT = {".sh", ".bash", ".ps1", ".yml", ".yaml", ".toml", ".sql", ".tf",
+                ".gradle", ".cmake"}
+_HARNESS_NAMES = {"makefile", "pom.xml", "build.gradle", "package.json",
+                  "pyproject.toml", "setup.py", "cargo.toml", "go.mod"}
+
+
+def _src_relevant(paths, repo_type=None):
+    """Only the paths that can invalidate a test run: the engine's own source-extension set --
+    a true SUPERSET of what rule (a) looked at, because provenance narrows the clock rule to
+    `SOURCE_EXT[repo_type]` and that set is unioned in here rather than assumed to be inside
+    `_SRC_EXT` (`.hh`/`.hxx` were in one and not the other until 1.93.0) -- plus the build and
+    harness files above. The same generated/build/report/vendor trees `_newest_source` prunes
+    are pruned here. ONE definition for rule (b) and for the seal (ADR-039): widening it widens
+    both at once, never one."""
+    allowed = _SRC_EXT | SOURCE_EXT.get(repo_type or "", set()) | _HARNESS_EXT
+    out = []
+    for path in paths:
+        parts = path.split("/")
+        if any(d in _SRC_SKIP_DIRS or d.startswith("cmake-build-") for d in parts[:-1]):
+            continue
+        name = parts[-1].lower()
+        if os.path.splitext(name)[1] in allowed or name in _HARNESS_NAMES:
+            out.append(path)
+    return out
+
+
+def _content_state(repo_path, repo_type, last_snapshot):
+    """What rule (b) needs, measured ONCE per repo instead of once per report: the commit the
+    last snapshot was taken at (`origin.commit`, ADR-007), the sha256 that snapshot recorded
+    per report path (ADR-038), and every source-relevant path that changed between that commit
+    and the tree on disk -- the committed diff AND the working tree, because a source edit that
+    is not committed yet is exactly as invalidating as one that is.
+
+    `None` whenever the question cannot be answered: no snapshot, no recorded commit, no
+    recorded hash (a pre-1.92.0 ledger), no git. Absence leaves rule (a) alone; it never
+    grants freshness."""
+    snap = last_snapshot if isinstance(last_snapshot, dict) else {}
+    commit = (snap.get("origin") or {}).get("commit")
+    if not commit:
+        return None
+    # THE BASELINE MUST NOT LAUNDER ITSELF (fixed before 1.93.0 shipped, found in blind review).
+    # `snapshot` records the tree AS IT IS: taken on a repo whose code moved and whose tests were
+    # never re-run, it faithfully writes `freshness: stale` -- and then, at read time, that same
+    # record would say "the report hashes to what I ingested, and nothing changed since MY commit"
+    # (its commit is HEAD, its hash was taken over that very file) and turn its own UNMEASURED
+    # verdict into a GREEN. A snapshot can only anchor evidence it judged CURRENT: a stale
+    # verdict, or a report the record itself marked stale, is no anchor at all.
+    if ((snap.get("tests") or {}).get("freshness") or {}).get("status") == "stale":
+        return None
+    hashes = {r["path"]: r["sha256"]
+              for r in ((snap.get("tests") or {}).get("reports") or [])
+              if isinstance(r, dict) and r.get("path") and r.get("sha256")
+              and r.get("fresh_by") != "stale"}
+    if not hashes:
+        return None
+    diff = _seal_git(repo_path, "-c", "core.quotepath=false", "diff", "--name-only",
+                     commit, "HEAD", "--", ".")
+    st = _seal_git(repo_path, "-c", "core.quotepath=false", "status", "--porcelain",
+                   "-uall", "--", ".")
+    if diff is None or st is None:
+        return None
+    changed = _src_relevant(_git_path_list(diff.stdout) + _porcelain_paths(st.stdout),
+                            repo_type)
+    return {"commit": commit, "hashes": hashes, "src_changed": sorted(set(changed))}
+
+
+def _report_fresh(repo_path, report_path, clock_fresh, content_state):
+    """'clock' | 'content' | None (stale) for ONE report -- the single derivation both the
+    snapshot record (`_test_evidence_provenance`) and the tag ingest (`_ac_tags`) read, so the
+    two surfaces cannot disagree about which report is current.
+
+    The CLOCK verdict is supplied by the caller on purpose: the two callers have always applied
+    it with different tolerances, and both stay byte-identical to 1.92.0 rather than being
+    quietly unified here."""
+    if clock_fresh:
+        return "clock"
+    if not content_state or content_state["src_changed"]:
+        return None
+    # the SAME relpath form the snapshot recorded the report under. No realpath on either
+    # side: both come from the same `repo_path` string, so the 8.3 mismatch of 2026-08-02
+    # cannot arise here, while normalizing one side would stop matching the recorded key.
+    rel = os.path.relpath(report_path, repo_path).replace("\\", "/")
+    recorded = content_state["hashes"].get(rel)
+    if not recorded or _sha256_file(report_path) != recorded:
+        return None
+    return "content"
+
+
+def _test_evidence_provenance(repo_path, repo_type, last_snapshot=None):
     """Explain which JUnit reports back a snapshot and whether they are newer
     than relevant source/test files. No discoverable source is explicitly
-    uncorrelated-but-usable to preserve synthetic/report-only workflows."""
+    uncorrelated-but-usable to preserve synthetic/report-only workflows.
+
+    Since 1.92.0 (ADR-038) each report also carries its CONTENT hash. Path and mtime
+    answer "which file, and was it written after the source"; they cannot answer "is
+    this still the file that was ingested" -- a log swapped or edited after the run
+    keeps its name and can keep its date. The hash is taken over the same files this
+    function already selects and the parser already reads: no new file is opened, and
+    `None` (unreadable) is recorded as absence, never as a match."""
     files = _junit_files_for(repo_path, repo_type)
     reports = []
     for path in files:
@@ -717,6 +842,7 @@ def _test_evidence_provenance(repo_path, repo_type):
             "mtime_ns": mtime_ns,
             "mtime": datetime.fromtimestamp(
                 mtime_ns / 1_000_000_000, timezone.utc).isoformat(),
+            "sha256": _sha256_file(path),
         })
     if not reports:
         status = "not-applicable" if repo_type == "flutter" else "missing"
@@ -737,15 +863,29 @@ def _test_evidence_provenance(repo_path, repo_type):
             "tolerance_ns": _JUNIT_FRESHNESS_TOLERANCE_NS,
         }
 
-    stale_reports = [
-        report for report in reports
-        if newest["mtime_ns"] > report["mtime_ns"] + _JUNIT_FRESHNESS_TOLERANCE_NS
-    ]
+    # ADR-039: the clock verdict first (unchanged, tolerance included), then rule (b) for the
+    # reports the clock rejects. `fresh_by` says WHICH rule answered for each report, so a
+    # board that reads fresh can always be asked why.
+    content_state = _content_state(repo_path, repo_type, last_snapshot)
+    stale_reports = []
+    for report in reports:
+        clock_fresh = (newest["mtime_ns"]
+                       <= report["mtime_ns"] + _JUNIT_FRESHNESS_TOLERANCE_NS)
+        how = _report_fresh(repo_path, os.path.join(repo_path, report["path"]),
+                            clock_fresh, content_state)
+        report["fresh_by"] = how or "stale"
+        if how is None:
+            stale_reports.append(report)
+    by_content = [r["path"] for r in reports if r["fresh_by"] == "content"]
     if stale_reports:
         paths = ", ".join(report["path"] for report in stale_reports)
         reason = (f"source/test {newest['path']} is newer than JUnit report(s) "
                   f"{paths}")
         status = "stale"
+    elif by_content:
+        reason = ("content unchanged since %s: %s"
+                  % (content_state["commit"][:8], ", ".join(by_content)))
+        status = "fresh"
     else:
         reason = "selected JUnit report(s) are current relative to source/test files"
         status = "fresh"
@@ -796,7 +936,7 @@ def _ac_tag_ids(name):
     return ids
 
 
-def _ac_tags(repo_path, repo_type):
+def _ac_tags(repo_path, repo_type, last_snapshot=None):
     """Tags AC-n leidos de los NOMBRES de testcase en los reportes JUnit que el
     engine ya ingiere. Devuelve (tags, stale) donde tags = {'AC-n': {'green': x,
     'red': y}} (o 'AC-FAM-n' para la forma con familia, ADR-036 / kit 1.87.0)
@@ -814,14 +954,21 @@ def _ac_tags(repo_path, repo_type):
     tags = {}
     stale = []
     newest_src = _source_newest_mtime(repo_path)
+    # ADR-039 (kit 1.93.0): rule (b) applies HERE too, not only in the snapshot record. A
+    # report the clock rejects but whose content is unchanged since the snapshot commit is
+    # FRESH, and discarding it here while calling it fresh there would be two derivations of
+    # one fact, free to disagree -- the 1.48.1 mirador sin.
+    content_state = _content_state(repo_path, repo_type, last_snapshot)
     for f in _junit_files_for(repo_path, repo_type):
+        clock_fresh = True
         if newest_src > 0.0:
             try:
-                if os.path.getmtime(f) < newest_src:
-                    stale.append(f)
-                    continue
+                clock_fresh = os.path.getmtime(f) >= newest_src
             except OSError:
                 pass
+        if _report_fresh(repo_path, f, clock_fresh, content_state) is None:
+            stale.append(f)
+            continue
         try:
             root = _parse_xml(f).getroot()
         except (ET.ParseError, OSError):
@@ -865,7 +1012,11 @@ def _sum_ac_tags(ledger):
     ac_tags = {}
     stale_reports = []
     for rcfg in (ledger.get("config") or {}).get("repos", []):
-        rtags, rstale = _ac_tags(rcfg.get("path", "."), rcfg.get("type", "maven"))
+        # the LAST snapshot of this repo is what rule (b) compares against (ADR-039): the
+        # commit the evidence was measured at and the hash each report carried at ingest.
+        snaps = ((ledger.get("repos") or {}).get(rcfg.get("name")) or {}).get("snapshots") or []
+        rtags, rstale = _ac_tags(rcfg.get("path", "."), rcfg.get("type", "maven"),
+                                 snaps[-1] if snaps else None)
         for cid, v in rtags.items():
             d = ac_tags.setdefault(cid, {"green": 0, "red": 0, "cases": []})
             d["green"] += v["green"]
@@ -936,7 +1087,7 @@ def junit_test_count(repo_path, extra_files=None):
             "passed": executed - failures - errors, "report_found": bool(files)}
 
 
-def test_count(repo_path, repo_type):
+def test_count(repo_path, repo_type, last_snapshot=None):
     if repo_type == "ant":
         result = ant_test_count(repo_path)
     elif repo_type == "maven":
@@ -955,7 +1106,7 @@ def test_count(repo_path, repo_type):
         result = junit_test_count(repo_path)
     else:
         result = flutter_test_count(repo_path)
-    reports, freshness = _test_evidence_provenance(repo_path, repo_type)
+    reports, freshness = _test_evidence_provenance(repo_path, repo_type, last_snapshot)
     result["reports"] = reports
     result["freshness"] = freshness
     return result
@@ -1981,10 +2132,14 @@ def _snapshot(ledger, name):
     cfg = _repo_cfg(ledger, name) if name != "integration" else {"path": ".", "type": "maven"}
     path = cfg["path"]
     rtype = cfg["type"]
+    # the PREVIOUS snapshot, read before this one is appended: rule (b) asks whether the
+    # reports are still the files THAT run ingested, at a commit with no source change since
+    # (ADR-039). Comparing a snapshot against itself would be circular.
+    prev = (node.get("snapshots") or [])[-1:] or [None]
     snap = {
         "at": _now(),
         "coverage": coverage(path, rtype),
-        "tests": test_count(path, rtype),
+        "tests": test_count(path, rtype, prev[0]),
         "loc": count_loc(path, rtype),
         "origin": _evidence_origin(path),
     }
@@ -8639,6 +8794,248 @@ def _top_spec_diff(ledger):
             "source": "spec-drift"}
 
 
+SEAL_NO_GIT = "no git work tree — seal UNMEASURED"
+SEAL_NO_COMMIT = "git repo without commits — seal UNMEASURED"
+
+
+def _seal_git(repo_path, *argv):
+    """One git read for the seal, or None. Same OSError posture as `_evidence_origin`:
+    git absent, or a repo path that does not exist, is an ordinary state of the world and
+    must degrade to UNMEASURED, never take down the command it only annotates."""
+    try:
+        r = subprocess.run(["git"] + list(argv), cwd=repo_path, capture_output=True,
+                           text=True, encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    return r if r.returncode == 0 else None
+
+
+def _seal_rel(work_tree, path):
+    """`path` as git names it: relative to the work tree root, forward slashes, or None
+    when it falls outside the tree.
+
+    BOTH sides go through `realpath` first. On Windows one API answers with an 8.3 short
+    name (`RUNNER~1`) and another with the long one, and `relpath` between the two yields
+    `..\\..` for a file plainly inside the tree — the CI-only failure paid for on
+    2026-08-02. A None here can only WITHHOLD an exemption, so the seal fails closed."""
+    try:
+        rel = os.path.relpath(os.path.realpath(path), os.path.realpath(work_tree))
+    except (OSError, ValueError):
+        return None
+    rel = rel.replace("\\", "/")
+    return None if rel == ".." or rel.startswith("../") else rel
+
+
+def _porcelain_paths(text):
+    """Every path named by `git status --porcelain -uall`, rename destinations included.
+
+    A path with special characters comes back C-quoted; the quotes are stripped and any
+    escape inside is left as-is. That can only fail to MATCH an exemption, which leaves the
+    seal broken — the safe direction: an unrecognized change is dirt, never a pass."""
+    out = []
+    for line in (text or "").splitlines():
+        if len(line) < 4:
+            continue
+        for part in line[3:].split(" -> "):
+            part = part.strip()
+            if len(part) >= 2 and part[0] == '"' and part[-1] == '"':
+                part = part[1:-1]
+            if part:
+                out.append(part.replace("\\", "/"))
+    return out
+
+
+def _sealed_state(ledger, ledger_path):
+    """INV-T1 (ADR-038): is the recorded evidence bound to the code state on disk RIGHT NOW?
+
+    Derived at read time, never written: nothing here creates a file, and re-deriving it is
+    the only way it can be trusted — a stored verdict is a claim about a tree that has moved
+    on since. Three questions, all answerable from what the ledger already carries:
+
+      1. is the TRACKED REPO'S SUBTREE clean -- `git status ... -- .` inside the configured
+         repo path, the same per-path scoping `_evidence_origin` uses (ADR-007), so a
+         monorepo sibling's edit is not this repo's dirt -- ignoring the ledger itself and
+         the report files the last snapshot names (those two are the seal's own footprint,
+         exactly as the reference `sh` package exempts `EVIDENCIA.md` and the logs it hashes);
+      2. has the CODE moved since the commit that snapshot was taken at (`origin.commit`,
+         ADR-007)? Amended in 1.93.0 (ADR-039): HEAD may differ from that commit by files
+         outside `_SRC_EXT` and outside the named report set -- docs, changelogs, the ledger
+         that carries this very snapshot -- and the seal then holds and carries a `note`
+         naming what moved (capped at five paths). A source-relevant difference is still a
+         break, named by its first path;
+      3. does every report the snapshot names still exist and still hash to what was
+         recorded at ingest (`sha256`, added in 1.92.0).
+
+    Three verdicts, never two: `True` sealed, `False` a MEASURED break (the reasons say
+    which), `None` UNMEASURED — no git work tree, or a snapshot old enough to predate the
+    content hash. A measured break outranks an unmeasured check (fail-closed); an unmeasured
+    check never reads as a pass (INV-TOP-05). The repo is the FIRST configured one, the same
+    choice `_top_spec_pin` and `_top_repos` make, and it is named in the `repo` member so
+    every reason below is read against it.
+
+    The block carries NO timestamp of its own. It is recomputed on every read, so a
+    "checked at" would be a second wall clock inside a payload whose only other one is
+    `generated_at` -- and two consecutive `top --json` runs must differ in nothing else
+    (AC-T-24 measures exactly that, and caught this before it shipped)."""
+    out = {"ok": None, "reasons": [], "commit": None, "repo": None, "note": None}
+    repos = (ledger.get("config", {}) or {}).get("repos") or []
+    if not repos:
+        out["reasons"].append("no repo configured — seal UNMEASURED")
+        return out
+    name = repos[0].get("name")
+    path = repos[0].get("path", ".")
+    rtype = repos[0].get("type")
+    out["repo"] = _top_clean(name) if name else None
+
+    top = _seal_git(path, "rev-parse", "--show-toplevel")
+    if top is None or not top.stdout.strip():
+        out["reasons"].append(SEAL_NO_GIT)
+        return out
+    head = _seal_git(path, "rev-parse", "HEAD")
+    if head is None or not head.stdout.strip():
+        # a git tree with no commit yet: `rev-parse HEAD` fails on an unborn branch. It is a
+        # DIFFERENT absence from "not a work tree" and the reason says so -- the verdict is
+        # the same UNMEASURED, but a reason that misnames the cause sends the reader to the
+        # wrong fix.
+        out["reasons"].append(SEAL_NO_COMMIT)
+        return out
+    head_sha = head.stdout.strip()
+    work_tree = top.stdout.strip()
+    out["commit"] = head_sha
+
+    snaps = ((ledger.get("repos") or {}).get(name) or {}).get("snapshots") or []
+    if not snaps:
+        # UNMEASURED, not broken. The reference `sh` package calls a missing EVIDENCIA.md a
+        # rejection, and that is right for a file whose only job is to be the seal -- but a
+        # snapshot is the INGEST record, and with none recorded there is nothing to compare
+        # the tree against: not "the evidence is stale", not "the evidence was altered",
+        # simply no anchor. Calling that a break would also make the seal non-deterministic
+        # for a board whose evidence is read live from reports (the `top` fixtures are
+        # exactly that), and INV-TOP-05 already fixes the posture: absence renders as
+        # absence. The teeth stay where they bite -- `check-terminado` exits 2, so a hook or
+        # a human gating on exit 0 still refuses. The LIMIT this leaves is stated out loud in
+        # SPEC §4: a board at 100% with no snapshot at all carries no seal marker.
+        out["reasons"].append("no snapshot recorded yet")
+        return out
+    snap = snaps[-1]
+
+    failures, unmeasured = [], []
+    reports = [r for r in ((snap.get("tests") or {}).get("reports") or [])
+               if isinstance(r, dict) and r.get("path")]
+    exempt = set()
+    for candidate in [ledger_path] + [os.path.join(path, r["path"]) for r in reports]:
+        rel = _seal_rel(work_tree, candidate)
+        if rel:
+            exempt.add(rel)
+
+    snap_commit = (snap.get("origin") or {}).get("commit")
+    if not snap_commit:
+        unmeasured.append("snapshot recorded no commit — seal UNMEASURED")
+    elif snap_commit != head_sha:
+        # AMENDED in 1.93.0 (ADR-039): `HEAD == commit` was too strict in the one repo that
+        # applies the method to itself -- the ledger lives INSIDE the commit that carries it,
+        # so the release commit is always one ahead of the snapshot it publishes and the board
+        # read `stale seal` forever on the machine that released. What the seal actually
+        # promises is that the CODE has not moved, so a HEAD that differs only by files outside
+        # `_SRC_EXT` and outside the named report set (docs, changelogs, the ledger itself) is
+        # sealed WITH A NOTE that says exactly what moved. Anything source-relevant is still a
+        # break, and it names the first offending path instead of two opaque hashes.
+        diff = _seal_git(path, "-c", "core.quotepath=false", "diff", "--name-only",
+                         snap_commit, head_sha, "--", ".")
+        if diff is None:
+            # the commit is unreachable (shallow clone, rewritten history): we cannot SEE what
+            # changed, so the strict verdict stands. Fail-closed, as before.
+            failures.append("stale seal: snapshot at %s, HEAD is %s"
+                            % (snap_commit[:8], head_sha[:8]))
+        else:
+            moved = sorted(set(_git_path_list(diff.stdout)))
+            # the REPORTS are deliberately NOT re-added here (blind review, before 1.93.0
+            # shipped). The release ritual is: commit the code, run the suite, `snapshot` at that
+            # commit, then commit the ledger AND the JUnit it names -- so the report is always in
+            # the X..X+1 diff and a seal that counted it could never close on the machine that
+            # released. Nothing is given away: the hash check below proves the file on disk is
+            # byte-for-byte the one that was ingested, which is a stronger statement than "this
+            # path did not appear in a diff".
+            relevant = sorted(set(_src_relevant(moved, rtype)))
+            if relevant:
+                failures.append("stale seal: source changed since snapshot %s: %s"
+                                % (snap_commit[:8], relevant[0]))
+            elif moved:
+                shown = ", ".join(moved[:5])
+                if len(moved) > 5:
+                    shown += " (+%d)" % (len(moved) - 5)
+                out["note"] = ("HEAD %s differs from snapshot %s by non-source files only: %s"
+                               % (head_sha[:8], snap_commit[:8], shown))
+            else:
+                out["note"] = ("HEAD %s differs from snapshot %s: no file changed in the "
+                               "repo subtree" % (head_sha[:8], snap_commit[:8]))
+    # `core.quotepath=false`: without it git C-quotes any non-ASCII path, so a report named
+    # `junit-acción.xml` would appear in the reason as `junit-acción.xml` -- a reason
+    # nobody can act on, and an exemption that cannot match. Set on the command, never in the
+    # user's config: the engine reads git, it does not configure it.
+    st = _seal_git(path, "-c", "core.quotepath=false",
+                   "status", "--porcelain", "-uall", "--", ".")
+    if st is None:
+        unmeasured.append("repo subtree state unreadable — seal UNMEASURED")
+    else:
+        dirty = sorted(set(_porcelain_paths(st.stdout)) - exempt)
+        if dirty:
+            failures.append("repo subtree dirty: changes no snapshot covers (%s)" % dirty[0])
+
+    for r in reports:
+        rel, full = r["path"], os.path.join(path, r["path"])
+        if not os.path.isfile(full):
+            failures.append("evidence missing: %s" % rel)
+        elif not r.get("sha256"):
+            unmeasured.append("evidence hash unmeasured: %s — no hash recorded at ingest "
+                              "(older snapshot, or the file was unreadable)" % rel)
+        elif _sha256_file(full) != r["sha256"]:
+            failures.append("evidence altered after ingest: %s" % rel)
+
+    out["reasons"] = failures + unmeasured
+    out["ok"] = False if failures else (None if unmeasured else True)
+    return out
+
+
+def cmd_check_terminado(args):
+    """The enforcement side of INV-T1: the SAME `_sealed_state` derivation `top --json`
+    publishes, with an exit code a hook or a human can act on. It measures the tree and
+    prints; it writes nothing and it decides nothing else.
+
+    0 = sealed · 1 = a measured break · 2 = UNMEASURED (no git work tree, no configured
+    repo, a snapshot with no recorded hash -- or no readable ledger at all). 2 is the
+    reference script's error class: "I could not answer" is not "yes".
+
+    A missing or corrupt ledger is UNMEASURED, not a break: `_load` exits 1 by design, and 1
+    here means "I checked and the seal is broken". Reporting "not sealed" for a file the
+    command never managed to read would be a verdict on evidence nobody looked at -- the
+    exact failure this command exists to catch."""
+    try:
+        ledger = _load(args.ledger)
+    except SystemExit as exc:
+        message = exc.code if isinstance(exc.code, str) else None
+        print(message or "[qa_ledger] check-terminado: ledger '%s' unreadable" % args.ledger)
+        print("[qa_ledger] check-terminado: UNMEASURED — no readable ledger, no seal.")
+        sys.exit(2)
+    sealed = _sealed_state(ledger, args.ledger)
+    ok = sealed.get("ok")
+    if getattr(args, "json", False):
+        print(json.dumps(sealed, indent=2, ensure_ascii=False))
+    else:
+        verdict = "SEALED" if ok is True else ("UNSEALED" if ok is False else "UNMEASURED")
+        where = " at %s" % sealed["commit"][:8] if sealed.get("commit") else ""
+        print("[qa_ledger] check-terminado: %s%s (repo %s)"
+              % (verdict, where, sealed.get("repo") or "?"))
+        if sealed.get("note"):
+            print("  - %s" % sealed["note"])
+        for reason in sealed.get("reasons") or []:
+            print("  - %s" % reason)
+        if ok is not True:
+            print("  TERMINADO is not enabled: re-run the evidence and `snapshot` "
+                  "on the current state.")
+    sys.exit(0 if ok is True else (1 if ok is False else 2))
+
+
 def cmd_top(args):
     """`uscha top` — the WHOLE projection of the ledger as one read-only JSON (ADR-032).
 
@@ -8744,6 +9141,15 @@ def cmd_top(args):
     done, fail, quar = _n("MEASURED_PASS"), _n("MEASURED_FAIL"), _n("QUARANTINE")
     unmeasured = _n("UNMEASURED") + _n("TRACED")
     pct = _top_pct(done, total)
+    # INV-TOP-06 (ADR-038): DONE never publishes 100% while the seal is MEASURED broken --
+    # every criterion green against evidence that no longer belongs to this code state is
+    # the same lie INV-TOP-01 forbids one row earlier. The cap lives HERE, beside the
+    # rounding cap, so no renderer is the place it happens. An UNMEASURED seal (`ok is
+    # None` -- no git) does NOT cap: absence of measurement is not evidence of a break, and
+    # capping on it would put an unearned 99 on every non-git tree.
+    sealed = _sealed_state(ledger, args.ledger)
+    if sealed.get("ok") is False and pct >= 100:
+        pct = 99
     measured = done + fail
     out = {
         "schema": TOP_SCHEMA,
@@ -8760,7 +9166,10 @@ def cmd_top(args):
         "events_tail": _top_events(ledger),
         "counts": {"measured_pass": done, "measured_fail": fail, "quarantine": quar,
                    "unmeasured": _n("UNMEASURED"), "traced": 0, "tagged": 0, "total": total},
-        "terminado": {"done": done, "total": total, "pct": pct, "unmeasured": unmeasured},
+        # `sealed` is DERIVED at read time from the ledger plus the tree (ADR-038); it is
+        # never stored, so it cannot go stale the way the claim it guards can.
+        "terminado": {"done": done, "total": total, "pct": pct, "unmeasured": unmeasured,
+                      "sealed": sealed},
         "debtors": {"machine": fail, "you": quar, "untagged": unmeasured},
         "honesty": {"measured": measured, "total": total,
                     "pct": _top_pct(measured, total)},
@@ -11952,6 +12361,14 @@ def build_parser():
     ptop.add_argument("--json", action="store_true")
     ptop.set_defaults(func=cmd_top)
 
+    pct = sub.add_parser("check-terminado",
+                         help="INV-T1 (ADR-038): is TERMINADO sealed to the code state on "
+                              "disk? Same derivation `top --json` publishes. Exit 0 sealed, "
+                              "1 broken, 2 UNMEASURED")
+    add_ledger(pct)
+    pct.add_argument("--json", action="store_true")
+    pct.set_defaults(func=cmd_check_terminado)
+
     pb = sub.add_parser("rebuild",
                         help="rebuild test: is the SPEC complete enough to "
                              "regenerate the system? (completeness, not correctness)")

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

@@ -131,6 +131,17 @@ ACTIONS = {
     "TAGGED": "machine: run the case",
 }
 
+# INV-TOP-06 (ADR-038): what a row that is green ON PAPER is actually waiting on when the
+# seal is broken. Presentation, like ACTIONS above: the engine says WHAT broke (the reason),
+# this says what the reader does about it, and the mapping is by reason prefix so a new
+# reason class degrades to the generic line instead of to silence.
+SEAL_ACTIONS = (
+    ("stale seal", "seal: snapshot at HEAD"),
+    ("repo subtree dirty", "seal: commit or discard, then snapshot"),
+    ("evidence altered", "seal: re-run the suite, then snapshot"),
+    ("evidence missing", "seal: re-run the suite, then snapshot"),
+)
+
 
 # --------------------------------------------------------------------------- #
 # pure rendering                                                              #
@@ -216,7 +227,15 @@ def _pct_line(terminado):
     """INV-TOP-01: the DONE bar carries an explicit `N unmeasured` suffix whenever anything
     is unmeasured, and the engine has already capped the percentage below 100 while any
     obligation sits outside MEASURED_PASS -- the renderer republishes that fact, it never
-    recomputes it (AC-T-01, AC-T-04, AC-T-23)."""
+    recomputes it (AC-T-01, AC-T-04, AC-T-23).
+
+    INV-TOP-06 (ADR-038) rides on the same line: when the engine's seal is MEASURED broken
+    (`terminado.sealed.ok is False`) the bar says so and names the first reason -- and the
+    percentage beside it is already capped below 100, in the engine, for the same reason the
+    unmeasured cap is (single derivation, AC-T-24). An UNMEASURED seal (`ok is null`: no git
+    work tree, the state of every frozen fixture) adds NOTHING here: the seal is shown only
+    when it is measured, and decorating a header with the absence of a measurement would
+    turn INV-TOP-05's `—` into noise on every board."""
     done = terminado.get("done")
     total = terminado.get("total")
     pct = terminado.get("pct")
@@ -224,9 +243,37 @@ def _pct_line(terminado):
     line = "DONE %s/%s (%s%%)" % (_num(done), _num(total), _num(pct))
     if unm:
         line += " %s %d unmeasured" % (MID, unm)
+    # the state is a FILE a human can hand us (`--state`), so `sealed` is guarded by TYPE and
+    # not merely by truthiness: a string there would answer `.get` with an AttributeError, and a
+    # `reasons` that is a string is iterable -- the frame would name its first CHARACTER as the
+    # reason. Same guards `_top_spec_diff` applies on the engine side, for the same reason.
+    seal = terminado.get("sealed")
+    seal = seal if isinstance(seal, dict) else {}
+    if seal.get("ok") is False:
+        raw = seal.get("reasons")
+        reasons = [r for r in raw if isinstance(r, str) and r] if isinstance(raw, list) else []
+        line += " %s unsealed (%s)" % (MID, _safe(reasons[0]) if reasons
+                                       else "no reason recorded")
     return line
 
 
+def _seal_action(sealed):
+    """The ACTION cell of a row that is green on paper while the seal is broken. Empty
+    whenever the seal is not MEASURED broken -- an unmeasured seal changes no row, and a
+    `sealed` of the wrong TYPE reads as no seal at all rather than raising mid-frame."""
+    seal = sealed if isinstance(sealed, dict) else {}
+    if seal.get("ok") is not False:
+        return ""
+    raw = seal.get("reasons")
+    for reason in (raw if isinstance(raw, list) else []):
+        if not isinstance(reason, str):
+            continue
+        for prefix, action in SEAL_ACTIONS:
+            if reason.startswith(prefix):
+                return action
+    return "seal: re-snapshot the current state"
+
+
 def _burnup_line(burnup, cols):
     """The score trend, labelled as a score trend. v0.1 has no obligation-count history
     (ADR-035/2), so calling this a burn-up of closed obligations would be a lie the label
@@ -264,15 +311,21 @@ def _cases_text(ob):
     return "%s/%s" % (_num(ob.get("cases_pass")), total)
 
 
-def _row(ob, selected):
+def _row(ob, selected, seal_action=""):
     # the three left columns are cut and padded in COLUMNS: an id or state carrying wide
     # characters used to eat its neighbour's field and walk every column after it.
     gutter = "> " if selected else "  "
+    action = ACTIONS.get(ob.get("state"), DASH)
+    # INV-TOP-06: only the rows that CLAIM to be done change, and only while the seal is
+    # measured broken. A failing or unmeasured row already names its own debtor; telling it
+    # about the seal too would bury the thing it is actually waiting for.
+    if seal_action and ob.get("state") == "MEASURED_PASS":
+        action = seal_action
     return "%s%s%s%s%7s%5s  %s" % (
         gutter, _pad(_cut(_safe(ob.get("id") or "?"), 8), 8),
         _pad(_cut(_safe(ob.get("gate") or DASH), 8), 9),
         _pad(_cut(_safe(ob.get("state") or "?"), 14), 15), _cases_text(ob),
-        _num(ob.get("age_hours")), ACTIONS.get(ob.get("state"), DASH))
+        _num(ob.get("age_hours")), action)
 
 
 def _safe(text):
@@ -382,8 +435,9 @@ def _render_board(state, size, sel, plain, status=""):
     top = max(0, top)
 
     table = []
+    seal_action = _seal_action(terminado.get("sealed"))
     for i, ob in enumerate(obligations[top:top + body], start=top):
-        line = _fit(_row(ob, i == sel), cols)
+        line = _fit(_row(ob, i == sel, seal_action), cols)
         table.append(line if plain else _colorize(line, ob.get("state")))
     hidden = len(obligations) - len(table)
     if hidden > 0: