@andresmassello/uscha 1.96.0 → 1.98.1

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

@@ -4140,6 +4140,47 @@ CANDIDATE_DELTA_FILE = "CANDIDATE-DELTA.json"    # under discovery/, machine-can
 CANDIDATE_DELTA_TWIN = "CANDIDATE-DELTA.md"      # rendered view, regenerated, never a source
 CANONICAL_FILE = "CANONICAL.json"                # under discovery/: the promoted package
 ISSUES_DEFERRED_FILE = "ISSUES-DEFERRED.md"
+# The shape of the work item `promote` writes for a `fix` verdict, and the shape it recognises
+# again on the next run. The dedupe used to be `o["id"] not in existing` -- a RAW SUBSTRING over
+# the whole file, so it suppressed the work item for any id merely MENTIONED in prose there and,
+# because the ids are a hash prefix, for any id that is a prefix of an already-written one
+# (1.69.0 fresh review, LOW, resolved 1.98.0). The question is not "does this text occur"; it is
+# "does this file already carry the WORK ITEM for this observation", and only the line shape
+# answers it. The word boundaries are what separate OBS-1 from OBS-10, and the `.*` between
+# the checkbox and the id is what lets a HUMAN reword the item -- prefix it with a date, a
+# severity, an owner -- without `promote` appending a second copy of it on the next run.
+_DEFERRED_ITEM_LINE = r"(?m)^[ \t]*[-*][ \t]*\[[ xX]\].*\b%s\b"
+
+
+def _deferred_carries(existing, oid):
+    """True when ISSUES-DEFERRED.md already holds the `- [ ] <oid>` work item for this OBS."""
+    return re.search(_DEFERRED_ITEM_LINE % re.escape(oid), existing) is not None
+
+
+def _config_beside_ledger(config, ledger_path):
+    """Where to LOOK for a config whose default is a bare relative name.
+
+    `--config` defaulted to the literal `uscha.config.json`, which `os.path.isfile` resolves
+    against the CWD. Run `fidelity --ledger /repo/QA-LEDGER.json` from anywhere but /repo and
+    the config beside the ledger was never opened -- so `defaults.fidelity.gate` was silently
+    not declared, and the INV-ADVISORY-01 refusal that reads it never fired. An UNNAMED absence
+    (1.69.0 fresh review, LOW, resolved 1.98.0): the command printed a full vector and exit 0,
+    exactly as it does when there genuinely is no config.
+
+    The cwd still WINS when it holds the file -- an explicit `--config` next to you is what you
+    meant, and no existing invocation changes behaviour. Only when it does not is the ledger's
+    own directory tried. Returns (path, found): callers report `path` so the answer to "which
+    file did you read" is in the output rather than in the reader's head.
+    """
+    if os.path.isfile(config):
+        return config, True
+    if not os.path.isabs(config):
+        beside = os.path.join(os.path.dirname(os.path.abspath(ledger_path)), config)
+        if os.path.isfile(beside):
+            return beside, True
+    return config, False
+
+
 OBS_TYPES = ("behavior", "invariant", "contract", "config", "dependency", "decision_trace")
 EVIDENCE_CLASSES = ("measured", "static", "narrated")
 # ADR-014 / INV-ADVISORY-01: dimensions an LLM judges can only advise. The QUARANTINE is an
@@ -4445,6 +4486,17 @@ def _match_canonical(statement, canon_ids):
     return None
 
 
+def _md_cell(text):
+    """One markdown TABLE cell. A `|` is escaped, and any CR/LF inside the value collapses to
+    a space -- a markdown row ENDS at a newline, so a statement or a provenance ref carrying
+    one used to split its observation across two rows and corrupt every column after it
+    (1.69.0 fresh review, LOW, resolved 1.98.0). The JSON and the OBS id always survived; only
+    this rendered view broke, and it is the artifact the human curates from. A space rather
+    than `<br>`: every other cell is plain text, and a lone HTML tag in one column would be
+    the only markup in the table."""
+    return re.sub(r"[\r\n]+", " ", "%s" % text).replace("|", "\\|")
+
+
 def _render_delta_md(delta, verdicts):
     lines = ["<!-- %s -->" % _DELTA_BANNER, "",
              "# CANDIDATE-DELTA (rendered view)", ""]
@@ -4460,9 +4512,10 @@ def _render_delta_md(delta, verdicts):
     for o in delta["observations"]:
         v = verdicts.get(o["id"], "(uncurated)")
         files = ", ".join(o["provenance"].get("files") or []) or "-"
-        stmt = o["statement"].replace("|", "\\|")
         lines.append("| %s | %s | %s | %s | %s | %s |"
-                     % (o["id"], o["type"], o["evidence_class"], v, stmt, files))
+                     % tuple(_md_cell(c) for c in (o["id"], o["type"],
+                                                   o["evidence_class"], v,
+                                                   o["statement"], files)))
     lines.append("")
     return "\n".join(lines)
 
@@ -4771,15 +4824,18 @@ def cmd_promote(args):
         if os.path.isfile(dpath):
             with open(dpath, encoding="utf-8-sig", errors="replace") as fh:
                 existing = fh.read()
-        add = [o for o in fixes if o["id"] not in existing]
+        add = [o for o in fixes if not _deferred_carries(existing, o["id"])]
         if add:
             with open(dpath, "a", encoding="utf-8", newline="\n") as fh:
                 if existing and not existing.endswith("\n"):
                     fh.write("\n")
                 for o in add:
+                    # a markdown checklist item ends at a newline just as a table row
+                    # does: a multi-line statement would split the work item in two and
+                    # leave the half _deferred_carries recognises without its text.
                     fh.write("- [ ] %s (curated `fix`): %s -- observed behavior the human "
                              "ruled a defect; NEVER canonical (ADR-013)\n"
-                             % (o["id"], o["statement"]))
+                             % (o["id"], _md_cell(o["statement"])))
             new_fix = [o["id"] for o in add]
     ledger["candidate_delta"] = {"repo": args.repo, "total": len(obs),
                                  "curated": len(obs),
@@ -4817,16 +4873,20 @@ def cmd_fidelity(args):
     node = _repo_node(ledger, args.repo)
     repo_path = _scope_path(ledger, args.repo)
     cfg = {}
-    if os.path.isfile(args.config):
+    # WHERE the config was looked for is part of the answer: a gate declared in a file the
+    # command never opened is a gate that does not exist, and the old cwd-only resolution said
+    # nothing about it (1.69.0 fresh review, resolved 1.98.0).
+    cfg_path, cfg_found = _config_beside_ledger(args.config, args.ledger)
+    if cfg_found:
         try:
-            with open(args.config, encoding="utf-8-sig") as fh:
+            with open(cfg_path, encoding="utf-8-sig") as fh:
                 cfg = json.load(fh)
         except (OSError, ValueError) as exc:
             # a config that cannot be parsed cannot declare gates -- swallowing the error
             # would DISABLE the INV-ADVISORY-01 refusal on a syntax slip (fresh-review
             # HIGH, reproduced). Malformation is exit 2, never a silent degrade.
             print("[qa_ledger] fidelity: %s unreadable: %s -- refusing to guess what it "
-                  "declares." % (args.config, exc), file=sys.stderr)
+                  "declares." % (cfg_path, exc), file=sys.stderr)
             sys.exit(2)
     declared = ((cfg.get("defaults") or {}).get("fidelity") or {}).get("gate") or []
     for dim in (ledger.get("config", {}).get("defaults", {}).get("fidelity")
@@ -4979,6 +5039,7 @@ def cmd_fidelity(args):
     dims["semantic"] = _fid_dim(None, "not wired: an LLM-judged comparison enters as "
                                       "advisory only and can NEVER gate (INV-ADVISORY-01)")
     out = {"repo": args.repo,
+           "config": cfg_path if cfg_found else None,
            **({"path": bound} if bound else {}),
            "dimensions": {k: dict(dims[k], **{"class": FIDELITY_DIMENSIONS[k]})
                           for k in ("traceability", "behavior", "contracts",
@@ -4990,6 +5051,11 @@ def cmd_fidelity(args):
     else:
         print("FIDELITY %s%s (vector -- no blend; each number stands on its own evidence):"
               % (args.repo, " [bounded to %s]" % bound if bound else ""))
+        if cfg_found:
+            print("  config           %s" % cfg_path)
+        else:
+            print("  config           none (looked for %r in the cwd and beside the ledger) "
+                  "-- no fidelity gate declared from a file" % args.config)
         for k, d in out["dimensions"].items():
             val = "UNMEASURED" if d["value"] is None else "%.2f" % d["value"]
             print("  %-17s %-10s [%s] %s" % (k, val, d["class"], d["provenance"]))
@@ -5211,8 +5277,8 @@ def _render_ir_md(graph):
              "|----|------|-----------|--------|"]
     for nd in graph.get("nodes") or []:
         src = "%s:%s" % (nd["source"]["file"], nd["source"]["line"])
-        stmt = (nd.get("statement") or "").replace("|", "\\|")
-        lines.append("| %s | %s | %s | %s |" % (nd["id"], nd["type"], stmt, src))
+        lines.append("| %s | %s | %s | %s |"
+                     % (nd["id"], nd["type"], _md_cell(nd.get("statement") or ""), src))
     lines += ["", "## Edges", "", "| from | type | to |", "|------|------|----|"]
     for e in graph.get("edges") or []:
         lines.append("| %s | %s | %s |" % (e["from"], e["type"], e["to"]))
@@ -5221,8 +5287,11 @@ def _render_ir_md(graph):
                   "| text | source | reason |", "|------|--------|--------|"]
         for u in graph["untyped"]:
             src = "%s:%s" % (u["source"]["file"], u["source"]["line"])
-            txt = (u.get("text") or "").replace("|", "\\|")[:80]
-            lines.append("| %s | %s | %s |" % (txt, src, u.get("reason", "")))
+            # truncate AFTER the cell is flattened: slicing raw text can cut mid-newline
+            # and leave the break inside the 80 characters that reach the row.
+            txt = _md_cell(u.get("text") or "")[:80]
+            lines.append("| %s | %s | %s |"
+                         % (txt, src, _md_cell(u.get("reason", ""))))
     lines.append("")
     return "\n".join(lines)
 
@@ -7251,13 +7320,46 @@ def _derive_facts():
     }
 
 
+# Spelled-out counts are claims too, and the paper writes both forms in one sentence -- "nine
+# agent skills and a dependency-free Python engine with 53 subcommands". A gate that only sees
+# digits reads half of that sentence and calls the file green. 1..99 covers every count this repo
+# derives, with room; above it the number is written in digits everywhere it appears.
+_ONES = ("zero", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine",
+         "ten", "eleven", "twelve", "thirteen", "fourteen", "fifteen", "sixteen",
+         "seventeen", "eighteen", "nineteen")
+_TENS = ("", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty", "ninety")
+
+
+def _spell(n):
+    """1..99 in English words, hyphenated ("fifty-three"); None outside that range."""
+    if not 1 <= n <= 99:
+        return None
+    if n < 20:
+        return _ONES[n]
+    return _TENS[n // 10] + ("-" + _ONES[n % 10] if n % 10 else "")
+
+
+_SPELLED = dict((_spell(n), n) for n in range(1, 100))
+# longest alternative first: an alternation offering "six" before "sixty-three" matches the prefix
+_NUM_ALT = "|".join(sorted(_SPELLED, key=len, reverse=True))
+# the leading \b so that "someone skills" cannot be read as the claim "one skills"
+_COUNT = r"\b(\d+|" + _NUM_ALT + r")\s+"
+
+
+def _unspell(token):
+    """The integer a spelled-out count names, or None when the token is not one."""
+    return _SPELLED.get(token.lower())
+
+
 _CLAIM_PATTERNS = (
     # (fact key path, regex over one line, needs-context substring or None)
     ("version", r"v(\d+\.\d+\.\d+)", "kit"),
     ("version", r"uscha-kit\s+v?(\d+\.\d+\.\d+)", None),
-    ("subcommands.count", r"(\d+)\s+sub-?comm?ands", None),
+    ("subcommands.count", _COUNT + r"sub-?comm?ands", None),
     ("subcommands.count", r"(\d+)\s+subcomandos", None),
-    ("skills.count", r"(\d+)\s+skills", None),
+    # "agent skills" is the kit's own noun phrase and the paper's; nothing wider is let in,
+    # because a WRITER that guessed at "two other skills" would corrupt the sentence it fixed.
+    ("skills.count", _COUNT + r"(?:agent\s+)?skills", None),
 )
 
 
@@ -7268,6 +7370,110 @@ def _fact_value(facts, dotted):
     return str(cur)
 
 
+def _claim_norm(token):
+    """The comparable form of a claimed token: a spelled-out count normalises to its digits, so
+    "nine skills" and "9 skills" are one claim compared against one fact."""
+    n = _unspell(token)
+    return token if n is None else str(n)
+
+
+def _claim_rewrite(token, actual):
+    """The replacement for one claimed token, in the AUTHOR's notation: a spelled-out claim is
+    rewritten spelled out and keeps its leading capital, a numeric one numerically. Rewriting
+    "nine skills" as "10 skills" would fix the fact and break the sentence."""
+    if _unspell(token) is None:
+        return actual
+    word = _spell(int(actual)) if actual.isdigit() else None
+    if word is None:
+        return actual
+    return word[0].upper() + word[1:] if token[:1].isupper() else word
+
+
+def _iter_claims(line):
+    """Every recognised claim on ONE line, as (fact key, start, end, token).
+
+    ONE recogniser, two consumers: `--check` reports what this yields and `--write` rewrites
+    exactly what this yields. A writer that re-implemented the patterns could disagree with the
+    checker, and the disagreement would surface as a release that refuses after fixing itself.
+
+    HTML comment spans are SKIPPED rather than deleted -- a comment is not a published claim
+    (the first live run flagged a section marker reading "2 Skills"), and `--write` needs offsets
+    into the ORIGINAL line. Overlapping matches collapse: the two version patterns can name the
+    same digits, and rewriting one span twice would corrupt the line."""
+    spans = [m.span() for m in re.finditer(r"<!--.*?-->", line)]
+    low = line.lower()
+    found = []
+    for key, pat, ctx in _CLAIM_PATTERNS:
+        if ctx and ctx not in low:
+            continue
+        for m in re.finditer(pat, line, re.I):
+            if any(a <= m.start() < b for a, b in spans):
+                continue
+            found.append((m.start(1), m.end(1), key, m.group(1)))
+    out, taken = [], []
+    for start, end, key, token in sorted(found):
+        if any(start < e and s < end for s, e in taken):
+            continue
+        taken.append((start, end))
+        out.append((key, start, end, token))
+    return out
+
+
+def _write_claims(facts, paths):
+    """Rewrite every recognised STALE claim in `paths` to the derived fact, byte for byte
+    otherwise. Line endings are preserved PER FILE (newline="" on both ends): the gated set mixes
+    LF sources with CRLF-checked-out HTML, and normalising them would turn a one-token fix into a
+    whole-file diff nobody can review.
+
+    What it deliberately does NOT touch: anything the patterns do not recognise. A missing
+    subcommand table row, a count spelled outside 1..99, a claim phrased in prose -- those stay
+    for the human, and the --check that follows still fails on them."""
+    changed, total, problems = 0, 0, 0
+    for path in paths:
+        try:
+            with open(path, encoding="utf-8", newline="") as fh:
+                body = fh.read()
+        except OSError as exc:
+            print("  !! %s: unreadable: %s" % (path, exc))
+            problems += 1
+            continue
+        except UnicodeDecodeError as exc:
+            # `--check` reads this file with errors="replace" and still reports its claims, so
+            # nothing is hidden. `--write` must NOT read it that way: writing a replaced byte
+            # back would destroy data to fix a version number, and a writer that corrupts a file
+            # to correct a claim is worse than the claim. Named, skipped, and the --check that
+            # follows still fails on whatever is stale in it.
+            print("  !! %s: not valid UTF-8 (%s) -- left untouched; --check still reads it"
+                  % (path, exc))
+            problems += 1
+            continue
+        lines = body.split("\n")
+        n = 0
+        for i, line in enumerate(lines):
+            claims = _iter_claims(line)
+            if not claims:
+                continue
+            # right to left: an earlier rewrite must not move the offsets of a later one
+            for key, start, end, token in sorted(claims, key=lambda c: c[1], reverse=True):
+                actual = _fact_value(facts, key)
+                if _claim_norm(token) == actual:
+                    continue
+                line = line[:start] + _claim_rewrite(token, actual) + line[end:]
+                n += 1
+            lines[i] = line
+        if not n:
+            continue
+        with open(path, "w", encoding="utf-8", newline="") as fh:
+            fh.write("\n".join(lines))
+        print("%s: %d claim(s) rewritten" % (path, n))
+        changed += 1
+        total += n
+    print("FACTS --write: %d claim(s) rewritten in %d of %d file(s)%s"
+          % (total, changed, len(paths),
+             "" if not problems else "; %d file(s) could not be read" % problems))
+    return problems
+
+
 def cmd_facts(args):
     """Generate SYSTEM-FACTS.json, or --check published claims against the derived facts.
 
@@ -7276,6 +7482,24 @@ def cmd_facts(args):
     about factual drift. A claim that CI does not compare against a derived fact will
     drift; this makes the comparison mechanical and the drift a named red."""
     facts = _derive_facts()
+    if args.write is not None:
+        # Until 1.97.0 there was no writer, so every bump was ~25 hand edits across ~13 files and
+        # the release script could only refuse and hand them back. `--write` rewrites the claims
+        # the SAME recogniser finds, then runs the SAME --check: a writer that reported its own
+        # success would be exactly the self-graded evidence this engine exists to refuse.
+        if args.check is not None:
+            # Before 1.97.0 this combination silently dropped --check's files: --write set
+            # args.check to ITS list. Two file sets given, one measured, no word about it.
+            print("[qa_ledger] facts: --check and --write are alternatives, not a pair -- "
+                  "--write already re-checks exactly the files it wrote.", file=sys.stderr)
+            sys.exit(2)
+        if not args.write:
+            print("[qa_ledger] facts: --write needs at least one file.", file=sys.stderr)
+            sys.exit(2)
+        if _write_claims(facts, args.write):
+            # an unreadable file is an UNMEASURED claim set, and unmeasured is not green
+            sys.exit(2)
+        args.check = list(args.write)
     if args.check:
         problems = []
         # 1) the committed facts file must match a fresh derivation (stale facts are drift)
@@ -7301,21 +7525,17 @@ def cmd_facts(args):
             table_names = []
             table_start = 0
             for n, line in enumerate(lines, 1):
-                # an HTML comment is not a published claim -- the first live run flagged a
-                # section marker (a comment reading "2 Skills") as a drifted count
-                line = re.sub(r"<!--.*?-->", "", line)
-                low = line.lower()
-                for key, pat, ctx in _CLAIM_PATTERNS:
-                    if ctx and ctx not in low:
-                        continue
-                    for m in re.finditer(pat, line, re.I):
-                        claimed = m.group(1)
-                        actual = _fact_value(facts, key)
-                        if claimed != actual:
-                            problems.append((path, n, key, claimed, actual))
+                # the claims come from the SHARED recogniser (`_iter_claims`), which skips HTML
+                # comment spans -- a comment is not a published claim
+                for key, _s, _e, claimed in _iter_claims(line):
+                    actual = _fact_value(facts, key)
+                    if _claim_norm(claimed) != actual:
+                        problems.append((path, n, key, claimed, actual))
                 # the parser-surface table (Subcommand/Subcomando header, one `<td class="t">`
                 # row per subcommand) is a claim too, just not a numeric one -- a row can go
                 # missing while the count beside it stays correct (the `top` row did, once).
+                # This half reads the comment-STRIPPED line: a commented-out row is not a row.
+                line = re.sub(r"<!--.*?-->", "", line)
                 if not in_table:
                     if re.search(r"<th>Sub ?comm?ando?s?</th>", line, re.I):
                         in_table, table_names, table_start = True, [], n
@@ -11038,18 +11258,33 @@ def _lc_valid_date(s):
         return False
 _LC_KEY = re.compile(r"^lifecycle\s*:\s*(.*)$")
 _LC_GOLIVE_FM = re.compile(r"^go[-_ ]?live\s*:\s*(.+?)\s*$", re.I)
-_LC_GOLIVE_LINE = re.compile(r"^\s*\*\*\s*go[-_ ]?live\s*:?\s*\*\*\s*:?\s*"
+# the body form. A list marker or a blockquote prefix in front of the bold label is still the
+# same declaration -- a SPEC that writes it as a bullet used to read as "no go-live declared"
+# (1.98.1, field report). The prefix is markdown-CORRECT, not merely permissive: at most three
+# leading spaces and never a tab, because four spaces or a tab opens an INDENTED CODE BLOCK --
+# an example, not a declaration -- and a list marker must be FOLLOWED by whitespace, so the
+# glued `-**Go-live:**` is not a list item. Fenced blocks are skipped by the caller for the
+# same reason. The trailing \b keeps the date a WHOLE token: it must be followed by a
+# non-digit or the end of the line, so a longer number can never be truncated into a date,
+# while ordinary prose after it ("(delivery 1). ...") is allowed.
+_LC_GOLIVE_LINE = re.compile(r"^ {0,3}(?:> ?)*(?:(?:[-*+]|\d+[.)])\s+)?"
+                             r"\*\*\s*go[-_ ]?live\s*:?\s*\*\*\s*:?\s*"
                              r"(\d{4}-\d{2}-\d{2})\b", re.I)
 _LC_FIELDS = ("component", "version", "eol", "source", "checked")
 
 
 def _lc_frontmatter(lines):
     """The lines INSIDE a leading `---` frontmatter block, or None when there is none.
+    Leading blank lines and a BOM are skipped before the fence is looked for: a file whose
+    text reached us with anything glued in front still opens its block at the top (1.98.1).
     An unterminated fence is not data: a half-written block reads as absent."""
-    if not lines or lines[0].strip() != "---":
+    i = 0
+    while i < len(lines) and not lines[i].lstrip("\ufeff").strip():
+        i += 1
+    if i >= len(lines) or lines[i].lstrip("\ufeff").strip() != "---":
         return None
     body = []
-    for ln in lines[1:]:
+    for ln in lines[i + 1:]:
         if ln.strip() == "---":
             return body
         body.append(ln)
@@ -11101,7 +11336,8 @@ def _lc_parse(lines):
 
 def _lc_go_live(text):
     """The declared go-live of a SPEC: frontmatter `go_live: YYYY-MM-DD`, or a
-    `**Go-live:** YYYY-MM-DD` line anywhere in the body. None = not declared."""
+    `**Go-live:** YYYY-MM-DD` line anywhere in the body OUTSIDE a fenced block.
+    None = not declared."""
     lines = [ln.rstrip("\r") for ln in (text or "").split("\n")]
     fm = _lc_frontmatter(lines)
     if fm:
@@ -11113,7 +11349,14 @@ def _lc_go_live(text):
                 v = m.group(1).strip().strip("\x27\x22")
                 if _lc_valid_date(v):
                     return v
+    in_fence = False
     for ln in lines:
+        st = ln.strip()
+        if st.startswith("```") or st.startswith("~~~"):
+            in_fence = not in_fence
+            continue
+        if in_fence:      # a SPEC that QUOTES the form is showing it, not declaring a date --
+            continue      # and the quoted line comes FIRST (the fence idiom of _spec_check_text)
         m = _LC_GOLIVE_LINE.match(ln)
         if m and _lc_valid_date(m.group(1)):
             return m.group(1)
@@ -11225,7 +11468,12 @@ def _lifecycle_for(root, adr_dir=None, spec_text=None, fallback=True):
         if os.path.isfile(sp):
             try:
                 with open(sp, "r", encoding="utf-8", errors="replace") as fh:
-                    spec_text = (spec_text or "") + "\n" + fh.read()
+                    body = fh.read()
+                # join only when there is something to join TO. Gluing a newline in front of
+                # the file pushed its `---` off line 0, so the frontmatter went invisible and
+                # `readiness` read "no go-live declared" on a SPEC that `spec-check` measured
+                # (1.98.1, field report).
+                spec_text = (spec_text + "\n" + body) if spec_text else body
             except OSError:
                 pass
     return _lifecycle_report(adr_dir or os.path.join(root, "docs", "adr"), spec_text)
@@ -12288,6 +12536,10 @@ def build_parser():
     pfa.add_argument("--out", default="SYSTEM-FACTS.json")
     pfa.add_argument("--check", nargs="*", default=None,
                      help="files whose claims must match the derived facts; exit 1 on drift")
+    pfa.add_argument("--write", nargs="*", default=None,
+                     help="files whose recognised claims are REWRITTEN to the derived facts "
+                          "(spelled-out claims stay spelled out), then re-checked: exit 1 if "
+                          "anything still disagrees")
     pfa.set_defaults(func=cmd_facts)
 
     prt = sub.add_parser("roundtrip",
@@ -12345,7 +12597,9 @@ def build_parser():
     pfv.add_argument("--ledger", default="QA-LEDGER.json")
     pfv.add_argument("--repo", required=True)
     pfv.add_argument("--config", default="uscha.config.json",
-                     help="checked for defaults.fidelity.gate -- advisory there is a refusal")
+                     help="checked for defaults.fidelity.gate -- advisory there is a "
+                          "refusal. A relative name is resolved against the cwd first, "
+                          "then beside --ledger; the path actually read is reported")
     pfv.add_argument("--ir", action="store_true",
                      help="answer curation_closure as a path query over the IR graph "
                           "(ADR-015); reproduces v0 from the derived index")

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

@@ -18,6 +18,7 @@ The human brings the idea, the constraints and the reference material. **You bri
 shape.** Your job is to interrogate until there is a shared system shape, and to write
 the documents as you go — not to ask the human to design the system for you.
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -85,6 +86,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Non-negotiable principles
 

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

@@ -17,6 +17,7 @@ allowed-tools: Read, Write, Glob, Grep, Bash
 Paints the REAL state of the project at a glance. It does not narrate or estimate: it
 wires the JSON the engine emits into the template. Read-only.
 
+<!-- uscha:orientation-block:begin -->
 ## Orientation markers (non-negotiable)
 
 The operator must never have to ask "where am I?" or "what happens now?".
@@ -40,6 +41,7 @@ Run:  <the exact command or skill to invoke>
 including any `Flow:` line in this file. If nothing is actionable, say that plainly rather
 than inventing a step. Keep the CONTENT in the conversation's language and the labels
 (`Next`, `Run`) verbatim — the smoke suite checks for them.
+<!-- uscha:orientation-block:end -->
 
 ## Contract
 

package/uscha-kit/.claude/skills/uscha-reverse-discovery/SKILL.md

@@ -23,6 +23,7 @@ first, always — and what cannot be fact yet becomes an OBSERVATION in quaranti
 evidence-classed, content-addressed, and promoted to the contract only by a per-observation
 human verdict (ADR-013).**
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -92,6 +93,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## The one non-negotiable: quarantine, not judgment (ADR-009)
 

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

@@ -21,6 +21,7 @@ contract + `qa_ledger.py rubric-ingest` (stdlib, runs anywhere). ANY runner can
 the grader — this skill just wraps the neutral prompt so Claude Code users get it
 in one command. Never add Claude-specific behavior to the contract.
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -88,6 +89,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Protocol
 

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

@@ -19,6 +19,7 @@ skill (**pull** — one screen when the human asks), and the **mirador** (bird's
 HTML). This skill exists because some surfaces never show a statusline; the answer
 is the same data, printed in chat when requested.
 
+<!-- uscha:orientation-block:begin -->
 ## Orientation markers (non-negotiable)
 
 The operator must never have to ask "where am I?" or "what happens now?".
@@ -42,6 +43,7 @@ Run:  <the exact command or skill to invoke>
 including any `Flow:` line in this file. If nothing is actionable, say that plainly rather
 than inventing a step. Keep the CONTENT in the conversation's language and the labels
 (`Next`, `Run`) verbatim — the smoke suite checks for them.
+<!-- uscha:orientation-block:end -->
 
 ## Contract
 

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

@@ -21,6 +21,7 @@ switch between at any time:
 - **Technical track** — architecture, modules, data flow, contracts, QA results,
   coverage, known deferred issues.
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -88,6 +89,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Inputs
 

package/uscha-kit/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.96.0",
+  "version": "1.98.1",
   "displayName": "Uscha",
   "description": "Spec-driven development for LLM coding agents: 9 skills (discovery, adr-refine, reverse-discovery, characterize, devloop, sysdoc, rubric, mirador, status) + a stdlib measurement engine (qa_ledger.py, 53 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {

package/uscha-kit/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "1.96.0",
+  "version": "1.98.1",
   "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.96.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.98.1 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
 
 Spec-driven orchestrator + multi-repo QA for Claude Code, with a deterministic ledger.
 **Nine skills** (`uscha-discovery`, `uscha-adr-refine`, `uscha-devloop`, `uscha-sysdoc`, `uscha-reverse-discovery`,

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.96.0
+uscha-kit 1.98.1

package/uscha-kit/skills/uscha-adr-refine/SKILL.md

@@ -18,6 +18,7 @@ You convert a rough idea into a development-ready specification. You do this in
 phases. **You are NOT a generator. You are an interrogator that distills.** The value
 is in the questions, not in agreeing.
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -85,6 +86,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Non-negotiable principles
 

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

@@ -18,6 +18,7 @@ return, you encode the same partial understanding that loses logic silently. **Y
 what the code DOES, mechanically, by running it — never what it should do.** You may write
 the capture harness; you may NOT create, rename, or edit any `.approved` file.
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -85,6 +86,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Inputs