@andresmassello/uscha 1.64.0 → 1.66.0

package/README.md

@@ -40,7 +40,7 @@ Requires **Python 3.8+** on the machine (the engine is Python stdlib — no pip
 runtime dependencies). The npm package is a thin router; the canonical installer is
 `uscha-kit/install-uscha.py`.
 
-**Kit v1.64.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.66.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
 [changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG.md)
 (the per-release changelogs live in the repo, not in the npm tarball)
 
@@ -76,7 +76,7 @@ and see which file, which test, and when.
 | `/uscha-mirador` | Bird's-eye HTML dashboard: readiness, trail, acceptance, loops |
 | `/uscha-status` | One-line progress readout, in chat |
 
-**A measurement engine** (`qa_ledger.py`, 34 subcommands, Python stdlib) that ingests
+**A measurement engine** (`qa_ledger.py`, 35 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.64.0",
+  "version": "1.66.0",
   "description": "Spec-driven development for LLM coding agents: 9 skills + a stdlib evidence engine. Facts block, guesses advise; the human approves.",
   "author": {
     "name": "Andres Massello",

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

@@ -488,6 +488,19 @@ count, plateau flag per repo — to `ledger["measured"]` (what the statusline re
 Without it the trail starves: the mirador shows "no history yet" and the statusline
 falls back to counting checkboxes. Recording is append-only facts, never a gate.
 
+Right after readiness, run the spec-maintenance advisory (kit 1.66.0):
+
+```bash
+python3 $QL spec-drift --repo <REPO>
+```
+
+Milliseconds, deterministic, exit 0 always — it never gates, so running it every pass
+adds zero ceremony. What it adds is VISIBILITY: the run lands in the ledger, so the
+mirador card and `/uscha-status` show drift without anyone remembering the command —
+the user this advisory exists for is precisely the one who never types it. If any doc
+reads `SPEC_STALE`, mention it in the close block's `Blocks:` line as advisory context
+(it blocks nothing; it informs the human's next conversation).
+
 **Single-verdict view (kit 1.25.0, anti-ceremony).** By default `readiness` is ONE
 screen: the verdict line, any conditional warning that actually fired (it speaks only
 when it matters), and a `--- gates:` line that COLLAPSES every persisted gate record —

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

@@ -1868,6 +1868,15 @@ def _origin_label(origin):
     return "%s/%s" % (sha, state)
 
 
+def _scope_path(ledger, name):
+    """Repo path for a scope, guarding the SYNTHETIC `integration` scope -- never present
+    in config["repos"], where _repo_cfg exits on unknown names. This crash class shipped
+    once (the clean-room gate, 1.63.0) and nearly shipped twice (spec-drift at pass close,
+    caught by fresh review): two recurrences make it a helper, not a per-site pattern."""
+    cfg = _repo_cfg(ledger, name) if name != "integration" else {"path": "."}
+    return cfg.get("path", ".")
+
+
 def _evidence_origin(repo_path):
     """WHERE the evidence came from: the commit it was measured at, and whether the tree
     was clean (ADR-007). The engine's freshness check compares file MTIMES, so until now a
@@ -3145,7 +3154,7 @@ def cmd_spec_drift(args):
     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", ".")
+    repo_path = _scope_path(ledger, args.repo)
 
     # The spec surface is fixed by ADR-005: the repo SPEC.md plus every ADR.
     spec_files = []
@@ -3749,6 +3758,68 @@ def _curation_state(repo_path):
     return state
 
 
+def cmd_roundtrip(args):
+    """Advisory spec-id coverage (ADR-009 slice 2, v1): which PROMOTED candidates are
+    traceable in the code via an embedded `uscha-spec: <candidate>` marker. Coverage by id,
+    deliberately NOT semantic matching -- that stays out of scope until it can be measured
+    (ADR-011). Advisory end to end: exit 0 always, a report, never a gate."""
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    repo_path = _scope_path(ledger, args.repo)
+    st = _curation_state(repo_path)
+    if st is None:
+        print("ROUNDTRIP %s: no %s/ directory -- feature unused, nothing to trace."
+              % (args.repo, CANDIDATE_DIR))
+        sys.exit(0)
+    promoted = sorted(st["promote_as_is"] + st["promote_with_declared_divergence"])
+    ls = subprocess.run(["git", "ls-files"], cwd=repo_path, capture_output=True,
+                        text=True, encoding="utf-8", errors="replace")
+    tracked = [l.strip() for l in ls.stdout.splitlines()
+               if ls.returncode == 0 and l.strip()
+               and not l.strip().startswith(CANDIDATE_DIR + "/")
+               and os.path.basename(l.strip()) != BEHAVIOR_LEDGER_FILE]
+    found = set()
+    pat = re.compile(r"uscha-spec:\s*([\w.\-]+)")
+    ROUNDTRIP_MAX_BYTES = 2 * 1024 * 1024
+    for f in tracked:
+        full = os.path.join(repo_path, f)
+        try:
+            if os.path.getsize(full) > ROUNDTRIP_MAX_BYTES:
+                continue    # a 2MB+ tracked file is not where a spec-id marker lives; an
+                            # unbounded full-tree read is the T112 lesson, applied here
+            with open(full, encoding="utf-8", errors="replace") as fh:
+                body = fh.read()
+        except OSError:
+            continue
+        for m in pat.finditer(body):
+            mid = m.group(1)
+            found.add(mid if mid.endswith(".md") else mid + ".md")
+    covered = [c for c in promoted if c in found]
+    missing = [c for c in promoted if c not in found]
+    out = {"repo": args.repo, "promoted": len(promoted), "covered": len(covered),
+           "missing": missing, "advisory": True,
+           "coverage_pct": round(100.0 * len(covered) / len(promoted), 1) if promoted else None}
+    # Latest-state record so the mirador/status can surface it without anyone re-running the
+    # command (the spec_drift pattern). A report that evaporates on exit is invisible to
+    # every read surface -- which defeats the point of an advisory (found by auditing which
+    # features actually REACH the user). Advisory data: no step counter, no gate record.
+    ledger["roundtrip"] = dict(out, at=_now())
+    _save(args.ledger, ledger)
+    if args.json:
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        if not promoted:
+            print("ROUNDTRIP %s: no promoted candidates yet -- nothing to trace (advisory)."
+                  % args.repo)
+        else:
+            print("ROUNDTRIP %s: %d/%d promoted candidate(s) traceable by uscha-spec id "
+                  "(advisory)" % (args.repo, len(covered), len(promoted)))
+            for mss in missing:
+                print("  .. %s: no uscha-spec marker found in the code" % mss)
+    sys.exit(0)
+
+
+
 def cmd_curation_check(args):
     """The INV-CURATION-01 gate, measured. Exit 2: malformation or tampering (config-error
     class -- candidates that cannot be validated, a ledger that cannot be trusted). Exit 1:
@@ -3756,7 +3827,7 @@ def cmd_curation_check(args):
     candidate judged, or the feature unused."""
     ledger = _load(args.ledger)
     _repo_node(ledger, args.repo)
-    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+    repo_path = _scope_path(ledger, args.repo)
     st = _curation_state(repo_path)
     if st is None:
         if args.json:
@@ -4840,6 +4911,8 @@ def cmd_dashboard(args):
     if ledger.get(CLEAN_ROOM_KEY):
         out["clean_room"] = {r: [e for e in ledger[CLEAN_ROOM_KEY] if e.get("repo") == r][-1]
                              for r in {e.get("repo") for e in ledger[CLEAN_ROOM_KEY]}}
+    if ledger.get("roundtrip"):
+        out["roundtrip"] = ledger["roundtrip"]
     if getattr(args, "json", False):
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return
@@ -6933,6 +7006,34 @@ def _golden_approved_path(rec):
 
 
 GOLDEN_SCRUB_FILE = "golden.scrub.json"
+GOLDEN_DIVERGENCES_FILE = "golden.divergences.json"
+
+
+def _load_golden_divergences(root):
+    """Expected divergences for `fix` verdicts (ADR-009 slice 2): a golden that MUST differ
+    because its ADR says the behavior was corrected. Shape:
+    {"divergences": {"<fixture basename>": {"adr": "ADR-RD-NNN", "reason": "..."}}}.
+    Strict like the scrub rules: a typo must not degrade into "no declarations" -- that
+    silence would turn every expected divergence back into a blocker, or worse, hide a
+    declared one behind a malformed file. Absent file -> {} (nothing declared)."""
+    path = os.path.join(root, GOLDEN_DIVERGENCES_FILE)
+    if not os.path.isfile(path):
+        return {}
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            spec = json.load(fh)
+        if not isinstance(spec, dict) or not isinstance(spec.get("divergences"), dict):
+            raise TypeError('expected {"divergences": {"<fixture>": {"adr":..., "reason":...}}}')
+        for k, v in spec["divergences"].items():
+            if (not isinstance(v, dict) or not re.match(r"^ADR-\S+$", str(v.get("adr", "")))
+                    or not str(v.get("reason", "")).strip()):
+                raise TypeError("divergence %r needs adr (ADR-...) and a reason" % k)
+        return spec["divergences"]
+    except (json.JSONDecodeError, TypeError, KeyError) as exc:
+        print("[qa_ledger] %s invalid (%s) - declared divergences are not skipped in "
+              "silence: fix the file or delete it." % (path, exc), file=sys.stderr)
+        sys.exit(2)
+
 
 
 def _load_scrub_rules(root):
@@ -7050,6 +7151,9 @@ def cmd_golden_diff(args):
     received = [p for p in sorted(hits) if os.path.isfile(p)]   # skip dirs matched by glob
     rules = _load_scrub_rules(root)
     labels = _load_golden_labels(getattr(args, "labels", None))
+    divergences = _load_golden_divergences(root)
+    expected_diverged = 0
+    consumed_declarations = set()
     scrub_counts = {}
     diverged = []   # (received_path, reason)
     fixtures = []
@@ -7078,21 +7182,60 @@ def cmd_golden_diff(args):
             fixture["result"] = "read_error"
             diverged.append((rec, f"could not read: {exc}"))
             continue
+        decl, decl_key = None, None
+        for cand_key in (os.path.relpath(app, root).replace(os.sep, "/"),
+                         os.path.relpath(rec, root).replace(os.sep, "/"),
+                         os.path.basename(app), os.path.basename(rec)):
+            # relpath first (the _golden_label pattern: nested suites share basenames and a
+            # declaration must not launder an unrelated module\x27s divergence -- fresh-review
+            # finding); basename stays as the flat-layout convenience.
+            if cand_key in divergences:
+                decl, decl_key = divergences[cand_key], cand_key
+                break
+        if decl:
+            consumed_declarations.add(decl_key)   # only what MATCHED: an unexercised twin
+                                                  # key must still show as unconsumed
         if rb == ab:
+            if decl:
+                # a `fix` verdict DECLARED this golden must differ -- identical bytes mean
+                # the corrected behavior never landed. An expected divergence that is not
+                # observed is a red finding, not a quiet pass (ADR-010: fix cases must
+                # diverge exactly as their ADR describes; identical is not that).
+                fixture["result"] = "declared_divergence_not_observed"
+                diverged.append((rec, "declared divergent (%s) but IDENTICAL -- the fix "
+                                      "this declaration describes is not in the output"
+                                      % decl["adr"]))
+                continue
             fixture["result"] = "matched"
             matched += 1
         # el conteo reportado es del lado RECEIVED (la captura fresca) — sumar
         # ambos lados duplicaria cada volatil enmascarado en el reporte.
         elif rules and (_scrub(rb, rules, scrub_counts)
                         == _scrub(ab, rules, {})):
+            if decl:
+                # scrub-equal IS "not observed": once declared volatiles are masked the
+                # outputs are behaviorally identical, so the fix this declaration
+                # describes is absent -- and letting the scrub branch swallow it hid the
+                # case from every signal (fresh-review HIGH: untested interaction).
+                fixture["result"] = "declared_divergence_not_observed"
+                diverged.append((rec, "declared divergent (%s) but scrub-equal -- "
+                                      "identical once volatiles are masked; the declared "
+                                      "fix is not in the output" % decl["adr"]))
+                continue
             # matchea SOLO tras enmascarar volatiles declarados — cuenta como
             # pass pero se reporta APARTE: el masking jamas es invisible.
             fixture["result"] = "matched_scrubbed"
             matched_scrubbed += 1
+        elif decl:
+            # diverges AND a fix verdict declared it would: expected, named, never silent.
+            fixture["result"] = "expected_divergence"
+            fixture["divergence_adr"] = decl["adr"]
+            expected_diverged += 1
         else:
             fixture["result"] = "diverged"
             diverged.append((rec, "diff NO aprobado contra .approved"))
 
+    unconsumed = sorted(k for k in divergences if k not in consumed_declarations)
     passed = len(diverged) == 0
     # zero fixtures is NOT-RUN, never CLEAN: a comparison that had nothing to
     # compare is absent evidence — log it as not-run (absence advises, a present
@@ -7114,6 +7257,8 @@ def cmd_golden_diff(args):
             "scrub_rules": len(rules),
             "scrub_substitutions": scrub_counts,
             "golden_labels": _golden_label_counts(fixtures),
+            "expected_diverged": expected_diverged,
+            "unconsumed_declarations": unconsumed,
             "fixtures": fixtures,
             "diverged": [{"file": f, "reason": r} for f, r in diverged],
         }, indent=2, ensure_ascii=False))
@@ -7551,6 +7696,13 @@ def build_parser():
     pcu.add_argument("--json", action="store_true")
     pcu.set_defaults(func=cmd_curation_check)
 
+    prt = sub.add_parser("roundtrip",
+                         help="advisory: which promoted candidates are traceable in code via uscha-spec ids (ADR-009 slice 2)")
+    prt.add_argument("--ledger", default="QA-LEDGER.json")
+    prt.add_argument("--repo", required=True)
+    prt.add_argument("--json", action="store_true")
+    prt.set_defaults(func=cmd_roundtrip)
+
     pcr = sub.add_parser("cleanroom",
                          help="run a command against a CLEAN checkout of one commit in a throwaway worktree (ADR-008)")
     pcr.add_argument("--ledger", default="QA-LEDGER.json")

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

@@ -100,6 +100,10 @@ nothing and gates nothing.
 `spec-drift: N stale / M docs (advisory)` — or `spec-drift: no drift measured` when zero are
 stale. Always label it advisory; it never explains a blocked phase. Absent key → no line.
 
+**Roundtrip (ADR-009 slice 2):** if the ledger carries a `roundtrip` run, add ONE line:
+`roundtrip: N/M promoted traceable by uscha-spec id (advisory)`. Absent key → no line —
+silence is honest when the loop was never measured.
+
 ## Degradation (honest, specific)
 
 - `measured` missing entirely → print: *"No measurement recorded yet — the trail

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.64.0",
+  "version": "1.66.0",
   "displayName": "Uscha",
-  "description": "Spec-driven development for LLM coding agents: 9 skills (discovery, adr-refine, reverse-discovery, characterize, devloop, sysdoc, rubric, mirador, status) + a stdlib measurement engine (qa_ledger.py, 34 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, 35 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.64.0",
+  "version": "1.66.0",
   "description": "Uscha spec-driven development methodology for coding agents. Includes npm/npx router.",
   "author": {
     "name": "Andres Massello",

package/uscha-kit/README.md

@@ -1,6 +1,6 @@
 # uscha-kit
 
-**Kit version:** v1.64.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.66.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
 
 Spec-driven orchestrator + multi-repo QA for Claude Code, with a deterministic ledger.
 **Nine skills** (`uscha-discovery`, `uscha-adr-refine`, `uscha-devloop`, `uscha-sysdoc`, `uscha-reverse-discovery`,
@@ -197,6 +197,25 @@ any candidate lacks a verdict, `pr-ready` is blocked naming it (INV-CURATION-01)
 quarantine is measured, not promised. No `discovery/` directory -> the feature does not
 exist and nothing changes.
 
+## Oracle divergences + roundtrip (slice 2)
+
+A `fix` verdict means the new system must NOT match the legacy golden - and that divergence
+is **declared**, never tolerated implicitly:
+
+```json
+// golden.divergences.json
+{ "divergences": { "invoice-totals.approved.json": {
+    "adr": "ADR-RD-003", "reason": "IVA now rounds; legacy truncated" } } }
+```
+
+`golden-diff` then reads the pair as `expected_divergence` (named, with its ADR) instead of
+a blocker - and a declared pair that comes back **identical** goes red: the fix the
+declaration describes is not in the output. Malformed declarations exit 2.
+
+`roundtrip --repo <name>` is the advisory closing of the loop, v1: which promoted
+candidates are traceable in the code via an embedded `uscha-spec: <candidate>` marker -
+coverage by id, deliberately not semantic matching, exit 0 always.
+
 ## End-to-end flow
 
 `uscha-discovery` is the front for something new (you only have the idea); `uscha-adr-refine` is the front

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.64.0
+uscha-kit 1.66.0

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

@@ -1 +1 @@
-{"AC-RD-07": true, "AC-RD-01": true, "AC-RD-02": true, "AC-RD-03": true, "AC-RD-06": true, "AC-RD-04": true, "AC-RD-05": true}
+{"AC-RD-07": true, "AC-RD-01": true, "AC-RD-02": true, "AC-RD-03": true, "AC-RD-06": true, "AC-RD-04": true, "AC-RD-05": true, "AC-RD-13": true}

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

@@ -0,0 +1 @@
+{"AC-RD-08": true, "AC-RD-09": true, "AC-RD-10": true, "AC-RD-11": true, "AC-RD-12": true}

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

@@ -488,6 +488,19 @@ count, plateau flag per repo — to `ledger["measured"]` (what the statusline re
 Without it the trail starves: the mirador shows "no history yet" and the statusline
 falls back to counting checkboxes. Recording is append-only facts, never a gate.
 
+Right after readiness, run the spec-maintenance advisory (kit 1.66.0):
+
+```bash
+python3 $QL spec-drift --repo <REPO>
+```
+
+Milliseconds, deterministic, exit 0 always — it never gates, so running it every pass
+adds zero ceremony. What it adds is VISIBILITY: the run lands in the ledger, so the
+mirador card and `/uscha-status` show drift without anyone remembering the command —
+the user this advisory exists for is precisely the one who never types it. If any doc
+reads `SPEC_STALE`, mention it in the close block's `Blocks:` line as advisory context
+(it blocks nothing; it informs the human's next conversation).
+
 **Single-verdict view (kit 1.25.0, anti-ceremony).** By default `readiness` is ONE
 screen: the verdict line, any conditional warning that actually fired (it speaks only
 when it matters), and a `--- gates:` line that COLLAPSES every persisted gate record —

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

@@ -1868,6 +1868,15 @@ def _origin_label(origin):
     return "%s/%s" % (sha, state)
 
 
+def _scope_path(ledger, name):
+    """Repo path for a scope, guarding the SYNTHETIC `integration` scope -- never present
+    in config["repos"], where _repo_cfg exits on unknown names. This crash class shipped
+    once (the clean-room gate, 1.63.0) and nearly shipped twice (spec-drift at pass close,
+    caught by fresh review): two recurrences make it a helper, not a per-site pattern."""
+    cfg = _repo_cfg(ledger, name) if name != "integration" else {"path": "."}
+    return cfg.get("path", ".")
+
+
 def _evidence_origin(repo_path):
     """WHERE the evidence came from: the commit it was measured at, and whether the tree
     was clean (ADR-007). The engine's freshness check compares file MTIMES, so until now a
@@ -3145,7 +3154,7 @@ def cmd_spec_drift(args):
     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", ".")
+    repo_path = _scope_path(ledger, args.repo)
 
     # The spec surface is fixed by ADR-005: the repo SPEC.md plus every ADR.
     spec_files = []
@@ -3749,6 +3758,68 @@ def _curation_state(repo_path):
     return state
 
 
+def cmd_roundtrip(args):
+    """Advisory spec-id coverage (ADR-009 slice 2, v1): which PROMOTED candidates are
+    traceable in the code via an embedded `uscha-spec: <candidate>` marker. Coverage by id,
+    deliberately NOT semantic matching -- that stays out of scope until it can be measured
+    (ADR-011). Advisory end to end: exit 0 always, a report, never a gate."""
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    repo_path = _scope_path(ledger, args.repo)
+    st = _curation_state(repo_path)
+    if st is None:
+        print("ROUNDTRIP %s: no %s/ directory -- feature unused, nothing to trace."
+              % (args.repo, CANDIDATE_DIR))
+        sys.exit(0)
+    promoted = sorted(st["promote_as_is"] + st["promote_with_declared_divergence"])
+    ls = subprocess.run(["git", "ls-files"], cwd=repo_path, capture_output=True,
+                        text=True, encoding="utf-8", errors="replace")
+    tracked = [l.strip() for l in ls.stdout.splitlines()
+               if ls.returncode == 0 and l.strip()
+               and not l.strip().startswith(CANDIDATE_DIR + "/")
+               and os.path.basename(l.strip()) != BEHAVIOR_LEDGER_FILE]
+    found = set()
+    pat = re.compile(r"uscha-spec:\s*([\w.\-]+)")
+    ROUNDTRIP_MAX_BYTES = 2 * 1024 * 1024
+    for f in tracked:
+        full = os.path.join(repo_path, f)
+        try:
+            if os.path.getsize(full) > ROUNDTRIP_MAX_BYTES:
+                continue    # a 2MB+ tracked file is not where a spec-id marker lives; an
+                            # unbounded full-tree read is the T112 lesson, applied here
+            with open(full, encoding="utf-8", errors="replace") as fh:
+                body = fh.read()
+        except OSError:
+            continue
+        for m in pat.finditer(body):
+            mid = m.group(1)
+            found.add(mid if mid.endswith(".md") else mid + ".md")
+    covered = [c for c in promoted if c in found]
+    missing = [c for c in promoted if c not in found]
+    out = {"repo": args.repo, "promoted": len(promoted), "covered": len(covered),
+           "missing": missing, "advisory": True,
+           "coverage_pct": round(100.0 * len(covered) / len(promoted), 1) if promoted else None}
+    # Latest-state record so the mirador/status can surface it without anyone re-running the
+    # command (the spec_drift pattern). A report that evaporates on exit is invisible to
+    # every read surface -- which defeats the point of an advisory (found by auditing which
+    # features actually REACH the user). Advisory data: no step counter, no gate record.
+    ledger["roundtrip"] = dict(out, at=_now())
+    _save(args.ledger, ledger)
+    if args.json:
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        if not promoted:
+            print("ROUNDTRIP %s: no promoted candidates yet -- nothing to trace (advisory)."
+                  % args.repo)
+        else:
+            print("ROUNDTRIP %s: %d/%d promoted candidate(s) traceable by uscha-spec id "
+                  "(advisory)" % (args.repo, len(covered), len(promoted)))
+            for mss in missing:
+                print("  .. %s: no uscha-spec marker found in the code" % mss)
+    sys.exit(0)
+
+
+
 def cmd_curation_check(args):
     """The INV-CURATION-01 gate, measured. Exit 2: malformation or tampering (config-error
     class -- candidates that cannot be validated, a ledger that cannot be trusted). Exit 1:
@@ -3756,7 +3827,7 @@ def cmd_curation_check(args):
     candidate judged, or the feature unused."""
     ledger = _load(args.ledger)
     _repo_node(ledger, args.repo)
-    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+    repo_path = _scope_path(ledger, args.repo)
     st = _curation_state(repo_path)
     if st is None:
         if args.json:
@@ -4840,6 +4911,8 @@ def cmd_dashboard(args):
     if ledger.get(CLEAN_ROOM_KEY):
         out["clean_room"] = {r: [e for e in ledger[CLEAN_ROOM_KEY] if e.get("repo") == r][-1]
                              for r in {e.get("repo") for e in ledger[CLEAN_ROOM_KEY]}}
+    if ledger.get("roundtrip"):
+        out["roundtrip"] = ledger["roundtrip"]
     if getattr(args, "json", False):
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return
@@ -6933,6 +7006,34 @@ def _golden_approved_path(rec):
 
 
 GOLDEN_SCRUB_FILE = "golden.scrub.json"
+GOLDEN_DIVERGENCES_FILE = "golden.divergences.json"
+
+
+def _load_golden_divergences(root):
+    """Expected divergences for `fix` verdicts (ADR-009 slice 2): a golden that MUST differ
+    because its ADR says the behavior was corrected. Shape:
+    {"divergences": {"<fixture basename>": {"adr": "ADR-RD-NNN", "reason": "..."}}}.
+    Strict like the scrub rules: a typo must not degrade into "no declarations" -- that
+    silence would turn every expected divergence back into a blocker, or worse, hide a
+    declared one behind a malformed file. Absent file -> {} (nothing declared)."""
+    path = os.path.join(root, GOLDEN_DIVERGENCES_FILE)
+    if not os.path.isfile(path):
+        return {}
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            spec = json.load(fh)
+        if not isinstance(spec, dict) or not isinstance(spec.get("divergences"), dict):
+            raise TypeError('expected {"divergences": {"<fixture>": {"adr":..., "reason":...}}}')
+        for k, v in spec["divergences"].items():
+            if (not isinstance(v, dict) or not re.match(r"^ADR-\S+$", str(v.get("adr", "")))
+                    or not str(v.get("reason", "")).strip()):
+                raise TypeError("divergence %r needs adr (ADR-...) and a reason" % k)
+        return spec["divergences"]
+    except (json.JSONDecodeError, TypeError, KeyError) as exc:
+        print("[qa_ledger] %s invalid (%s) - declared divergences are not skipped in "
+              "silence: fix the file or delete it." % (path, exc), file=sys.stderr)
+        sys.exit(2)
+
 
 
 def _load_scrub_rules(root):
@@ -7050,6 +7151,9 @@ def cmd_golden_diff(args):
     received = [p for p in sorted(hits) if os.path.isfile(p)]   # skip dirs matched by glob
     rules = _load_scrub_rules(root)
     labels = _load_golden_labels(getattr(args, "labels", None))
+    divergences = _load_golden_divergences(root)
+    expected_diverged = 0
+    consumed_declarations = set()
     scrub_counts = {}
     diverged = []   # (received_path, reason)
     fixtures = []
@@ -7078,21 +7182,60 @@ def cmd_golden_diff(args):
             fixture["result"] = "read_error"
             diverged.append((rec, f"could not read: {exc}"))
             continue
+        decl, decl_key = None, None
+        for cand_key in (os.path.relpath(app, root).replace(os.sep, "/"),
+                         os.path.relpath(rec, root).replace(os.sep, "/"),
+                         os.path.basename(app), os.path.basename(rec)):
+            # relpath first (the _golden_label pattern: nested suites share basenames and a
+            # declaration must not launder an unrelated module\x27s divergence -- fresh-review
+            # finding); basename stays as the flat-layout convenience.
+            if cand_key in divergences:
+                decl, decl_key = divergences[cand_key], cand_key
+                break
+        if decl:
+            consumed_declarations.add(decl_key)   # only what MATCHED: an unexercised twin
+                                                  # key must still show as unconsumed
         if rb == ab:
+            if decl:
+                # a `fix` verdict DECLARED this golden must differ -- identical bytes mean
+                # the corrected behavior never landed. An expected divergence that is not
+                # observed is a red finding, not a quiet pass (ADR-010: fix cases must
+                # diverge exactly as their ADR describes; identical is not that).
+                fixture["result"] = "declared_divergence_not_observed"
+                diverged.append((rec, "declared divergent (%s) but IDENTICAL -- the fix "
+                                      "this declaration describes is not in the output"
+                                      % decl["adr"]))
+                continue
             fixture["result"] = "matched"
             matched += 1
         # el conteo reportado es del lado RECEIVED (la captura fresca) — sumar
         # ambos lados duplicaria cada volatil enmascarado en el reporte.
         elif rules and (_scrub(rb, rules, scrub_counts)
                         == _scrub(ab, rules, {})):
+            if decl:
+                # scrub-equal IS "not observed": once declared volatiles are masked the
+                # outputs are behaviorally identical, so the fix this declaration
+                # describes is absent -- and letting the scrub branch swallow it hid the
+                # case from every signal (fresh-review HIGH: untested interaction).
+                fixture["result"] = "declared_divergence_not_observed"
+                diverged.append((rec, "declared divergent (%s) but scrub-equal -- "
+                                      "identical once volatiles are masked; the declared "
+                                      "fix is not in the output" % decl["adr"]))
+                continue
             # matchea SOLO tras enmascarar volatiles declarados — cuenta como
             # pass pero se reporta APARTE: el masking jamas es invisible.
             fixture["result"] = "matched_scrubbed"
             matched_scrubbed += 1
+        elif decl:
+            # diverges AND a fix verdict declared it would: expected, named, never silent.
+            fixture["result"] = "expected_divergence"
+            fixture["divergence_adr"] = decl["adr"]
+            expected_diverged += 1
         else:
             fixture["result"] = "diverged"
             diverged.append((rec, "diff NO aprobado contra .approved"))
 
+    unconsumed = sorted(k for k in divergences if k not in consumed_declarations)
     passed = len(diverged) == 0
     # zero fixtures is NOT-RUN, never CLEAN: a comparison that had nothing to
     # compare is absent evidence — log it as not-run (absence advises, a present
@@ -7114,6 +7257,8 @@ def cmd_golden_diff(args):
             "scrub_rules": len(rules),
             "scrub_substitutions": scrub_counts,
             "golden_labels": _golden_label_counts(fixtures),
+            "expected_diverged": expected_diverged,
+            "unconsumed_declarations": unconsumed,
             "fixtures": fixtures,
             "diverged": [{"file": f, "reason": r} for f, r in diverged],
         }, indent=2, ensure_ascii=False))
@@ -7551,6 +7696,13 @@ def build_parser():
     pcu.add_argument("--json", action="store_true")
     pcu.set_defaults(func=cmd_curation_check)
 
+    prt = sub.add_parser("roundtrip",
+                         help="advisory: which promoted candidates are traceable in code via uscha-spec ids (ADR-009 slice 2)")
+    prt.add_argument("--ledger", default="QA-LEDGER.json")
+    prt.add_argument("--repo", required=True)
+    prt.add_argument("--json", action="store_true")
+    prt.set_defaults(func=cmd_roundtrip)
+
     pcr = sub.add_parser("cleanroom",
                          help="run a command against a CLEAN checkout of one commit in a throwaway worktree (ADR-008)")
     pcr.add_argument("--ledger", default="QA-LEDGER.json")

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

@@ -100,6 +100,10 @@ nothing and gates nothing.
 `spec-drift: N stale / M docs (advisory)` — or `spec-drift: no drift measured` when zero are
 stale. Always label it advisory; it never explains a blocked phase. Absent key → no line.
 
+**Roundtrip (ADR-009 slice 2):** if the ledger carries a `roundtrip` run, add ONE line:
+`roundtrip: N/M promoted traceable by uscha-spec id (advisory)`. Absent key → no line —
+silence is honest when the loop was never measured.
+
 ## Degradation (honest, specific)
 
 - `measured` missing entirely → print: *"No measurement recorded yet — the trail

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.64.0",
+  "version": "1.66.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,