@andresmassello/uscha 2.0.0 → 2.2.0

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

@@ -36,6 +36,9 @@ Usage (see `--help` on each subcommand):
                            [--ruff reports/ruff.json --mypy reports/mypy.txt]
   qa_ledger.py log-gate    --repo backend-api --iteration 1 --kind golden-diff \
                            --verdict pass|fail|not-run [--count N] [--note "..."]
+  qa_ledger.py corpus-run  --repo backend-api --corpus corpus.jsonl \
+                           --command "python -m parser" [--threshold 99] [--ac AC-FIELD-01]
+  qa_ledger.py smoke-ingest --repo backend-api --report reports/smoke.json [--json]
   qa_ledger.py flag-blocker --repo backend-api --kind constitution --note "INV-XX breached" \
                            [--resolve]
   qa_ledger.py production-finding --repo backend-api --severity HIGH --title "..." --evidence "..."
@@ -44,11 +47,13 @@ Usage (see `--help` on each subcommand):
   qa_ledger.py rebuild --mode baseline --config uscha.config.json [--out REBUILD-BASELINE.json]
   qa_ledger.py rebuild --mode compare  --baseline REBUILD-BASELINE.json [--json]
   qa_ledger.py simplicity-check --diff changes.diff [--config uscha.config.json] [--json]
-  qa_ledger.py simplicity-check --from-git --base main
+  qa_ledger.py simplicity-check --from-git --base main            (advisory: exit 0)
+  qa_ledger.py simplicity-check --from-git --base main --max-lines-added 400 --gate
   qa_ledger.py pit-check --report target/pit-reports/*/mutations.xml [--min-score 60] [--json]
   qa_ledger.py gate-check --from-git --base main [--strict] [--json]
   qa_ledger.py spec-check --spec SPEC.md [--spec ACCEPTANCE.md] [--strict] [--json]
   qa_ledger.py golden-diff [--dir .] [--labels golden-labels.json] [--json]
+  qa_ledger.py operability --repo backend-api [--json]   (ADR-048: exit 0 always)
 """
 
 import argparse
@@ -1883,14 +1888,55 @@ GOLDEN_REQUIRED_CEILING = 49  # ADR-002: no approved golden -> NOT READY (does n
 RISK_PROFILES = {
     "A": {"qa_tools_order": ["code-review"]},
     "B": {"qa_tools_order": ["code-review", "improve"]},
-    "C": {"qa_tools_order": ["code-review", "judgment-day", "improve"]},
+    "C": {"qa_tools_order": ["code-review", "judgment-day", "improve"],
+          "operability.gate": True},
     "D": {"qa_tools_order": ["code-review", "judgment-day", "improve"],
-          "coverage_threshold": 70, "golden_required": True},
+          "coverage_threshold": 70, "golden_required": True,
+          "operability.gate": True},
     "E": {"qa_tools_order": ["code-review", "judgment-day", "improve"],
-          "coverage_threshold": 80, "golden_required": True},
+          "coverage_threshold": 80, "golden_required": True,
+          "operability.gate": True},
 }
 
 
+def _knob_get(mapping, key):
+    """Read a knob out of a defaults-shaped mapping by its (possibly DOTTED) name ->
+    (found, value). Dotted since 2.2.0 (ADR-048): the first profile-owned knob that lives one
+    level down is `defaults.operability.gate`, in the same block shape the config already uses
+    for `simplicity.gate` and `waste.gate`. A non-dict on the way down is NOT a hit --
+    `operability: true` declares nothing this ladder can read, and guessing what it meant is
+    exactly how a preset goes silently inert (the defect ADR-001 was amended for)."""
+    cur = mapping
+    for part in key.split("."):
+        if not isinstance(cur, dict) or part not in cur:
+            return False, None
+        cur = cur[part]
+    return True, cur
+
+
+def _knob_set(mapping, key, value):
+    """Write a (possibly dotted) knob, creating the intermediate objects. Intermediates are
+    COPIED on the way down: callers hand this shallow copies of `defaults`, and mutating a
+    nested dict in place would reach back into the config the caller promised not to touch.
+    Returns False -- writing nothing -- when something that is not an object already sits on
+    the path: an explicit declaration always wins, even a malformed one, and naming a
+    malformed one is `_validate_init_config`'s job, not this function's."""
+    parts = key.split(".")
+    cur = mapping
+    for part in parts[:-1]:
+        nxt = cur.get(part)
+        if nxt is None:
+            nxt = {}
+        elif isinstance(nxt, dict):
+            nxt = dict(nxt)
+        else:
+            return False
+        cur[part] = nxt
+        cur = nxt
+    cur[parts[-1]] = value
+    return True
+
+
 def _apply_risk_profile(defaults):
     """Expand defaults['risk_profile'] into concrete knobs UNDER any explicit value (explicit
     wins per key). Records the profile-provided keys in defaults['_risk_profile_keys'] so a cap
@@ -1904,8 +1950,9 @@ def _apply_risk_profile(defaults):
                          + ", ".join(sorted(RISK_PROFILES)))
     provided = []
     for key, value in RISK_PROFILES[profile].items():
-        if key not in defaults:  # an explicit declaration always wins
-            defaults[key] = list(value) if isinstance(value, list) else value
+        if _knob_get(defaults, key)[0]:  # an explicit declaration always wins
+            continue
+        if _knob_set(defaults, key, list(value) if isinstance(value, list) else value):
             provided.append(key)
     defaults["_risk_profile_keys"] = provided
     return defaults
@@ -1930,6 +1977,11 @@ ENGINE_DEFAULTS = {
     "qa_tools_order": None,
     "coverage_threshold": 60,
     "golden_required": False,
+    # ADR-048. The engine's own posture on operability is ADVISORY: `operability` measures and
+    # records on every profile, but only C/D/E turn the record into a gate. A kit that gated
+    # release + reset + RUNBOOK on every project would be the kit's opinion wearing an exit
+    # code -- the same thing ADR-043 refused for the simplicity budget.
+    "operability.gate": False,
 }
 ENGINE_DEFAULT_NOTES = {
     "qa_tools_order": "not declared - convergence uses a window of --tools-per-cycle "
@@ -1940,17 +1992,35 @@ ENGINE_DEFAULT_NOTES = {
 def _resolved_defaults(cfg):
     """(resolved defaults, origin per profile-owned key) for a RAW config -- the effective
     settings `doctor` reports. Origin is `override` (declared in defaults), `profile <X>`, or
-    `default`. Read-only: never mutates cfg and never writes anything back."""
+    `default`. Read-only: never mutates cfg and never writes anything back.
+
+    Works over a RAW config (what `doctor` reads) and over the FROZEN one inside a ledger
+    alike: `init` expands the profile before freezing, so on the frozen copy a profile-supplied
+    knob is already sitting in `defaults` and would otherwise read as a human `override`.
+    `_risk_profile_keys` -- written by `_apply_risk_profile` for exactly this reason, and
+    already read this way by the golden cap -- is what tells the two apart (ADR-048).
+
+    It tells them apart only while the value still IS the profile's, and that is the case the
+    fresh review found: a human who edits the FROZEN copy leaves a declaration the profile
+    never made, `_risk_profile_keys` still names the key, and `operability.gate: false` under
+    profile E reported `origin profile E` -- crediting the preset with the opposite of what it
+    supplies. The DECLARATION is therefore read first: a raw value that disagrees with what the
+    profile would have written is an `override`, whoever typed it and whenever."""
     raw = cfg.get("defaults") if isinstance(cfg, dict) else None
     raw = dict(raw) if isinstance(raw, dict) else {}
-    declared = set(raw)
     profile = raw.get("risk_profile")
+    from_profile = set(raw.get("_risk_profile_keys") or [])
     expanded = _apply_risk_profile(dict(raw))
     resolved, origin = {}, {}
     for key, fallback in ENGINE_DEFAULTS.items():
-        resolved[key] = expanded[key] if key in expanded else fallback
-        if key in declared:
+        found, value = _knob_get(expanded, key)
+        resolved[key] = value if found else fallback
+        raw_found, raw_value = _knob_get(raw, key)
+        profile_value = RISK_PROFILES.get(profile, {}).get(key) if profile else None
+        if raw_found and not (key in from_profile and raw_value == profile_value):
             origin[key] = "override"
+        elif key in from_profile and profile:
+            origin[key] = "profile %s" % profile
         elif profile and key in RISK_PROFILES.get(profile, {}):
             origin[key] = "profile %s" % profile
         else:
@@ -2107,7 +2177,96 @@ def _validate_log_step_counts(args):
         raise SystemExit("[qa_ledger] gated-reported cannot exceed reported")
 
 
+def _add_repo_to_config_file(path, entry, frozen_names):
+    """Mirror the new repo into uscha.config.json when that file IS the source the ledger was
+    frozen from -- same repo names, in the same order. A file that has DRIFTED from the frozen
+    config is somebody else's edit, and it is left alone with the divergence named: silently
+    rewriting a config that no longer matches the ledger would be resolving a conflict the human
+    has not seen. Returns the sentence to print, never raises: the ledger is the source of truth
+    and its write already happened."""
+    if not os.path.isfile(path):
+        return "%s not found -- the ledger's frozen config is the only copy that changed" % path
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            cfg = json.load(fh)
+        names = [r.get("name") for r in cfg.get("repos", [])]
+    except (OSError, ValueError, AttributeError, TypeError) as exc:
+        return "%s left untouched (unreadable: %s)" % (path, exc)
+    if names != frozen_names:
+        return ("%s left untouched: its repos %s differ from the ledger's frozen %s, so it is "
+                "not the source this ledger was built from" % (path, names, frozen_names))
+    cfg["repos"].append(dict(entry))
+    tmp = path + ".tmp"
+    try:
+        with open(tmp, "w", encoding="utf-8") as fh:
+            json.dump(cfg, fh, indent=2, ensure_ascii=False)
+            fh.write("\n")
+        os.replace(tmp, path)
+    except OSError as exc:
+        return "%s left untouched (not writable: %s)" % (path, exc)
+    return "%s updated too (it is the source this ledger was frozen from)" % path
+
+
+def _init_add_repo(args):
+    """Append ONE repo to an EXISTING ledger without resetting it (2.2.0 field fix).
+
+    Until now the only door was re-running `init --config`, which builds a NEW ledger: the step
+    counter, every repo's iterations and every snapshot went back to zero, so adding a second
+    service to a live loop cost the evidence of the first. Editing QA-LEDGER.json by hand is not
+    the workaround either -- `_load` verifies the sha256 that `_save` writes, so a hand edit
+    turns the file into a refusal. That refusal is correct and stays: it is what makes 'measured
+    beats narrated' worth anything. What was missing was a supported door, and this is it.
+
+    What this deliberately does NOT do: touch any existing repo's steps, snapshots or
+    iterations, and re-freeze `defaults`. The config a project started under stays the config it
+    ran under -- only the repo list grows. `_save` re-seals the checksum over the result.
+
+    The new repo starts with NO evidence, and readiness says so rather than hiding it: it enters
+    `facts.static_unmeasured_repos`, and every aggregate that averages over repos reads LOWER
+    until its first snapshot or gate lands. That is an unmeasured repo, never a regression --
+    nothing already measured changed, and `by_repo` proves it entry by entry. Excluding it from
+    the average instead would be the opposite mistake: an aggregate produced by silence."""
+    name = args.add_repo
+    if not _has_text(args.path) or not _has_text(args.type):
+        raise SystemExit("[qa_ledger] init --add-repo needs --path and --type: the engine never "
+                         "guesses where a repo lives or how it is built")
+    if name == "integration":
+        raise SystemExit("[qa_ledger] repo name 'integration' is reserved")
+    ledger = _load(args.out)
+    cfg = ledger.get("config") or {}
+    frozen_names = [r.get("name") for r in cfg.get("repos", [])]
+    if name in frozen_names or name in ledger.get("repos", {}):
+        raise SystemExit(
+            "[qa_ledger] repo '%s' already exists in %s -- nothing was written. Adding it twice "
+            "would either duplicate the config entry or reset that repo's steps, which is the "
+            "very loss this flag exists to prevent." % (name, args.out))
+    entry = {"name": name, "type": args.type, "path": args.path}
+    if _has_text(args.test_command):
+        entry["test_command"] = args.test_command
+    cfg.setdefault("repos", []).append(entry)
+    ledger["config"] = cfg
+    # the same node shape `init` writes, so nothing downstream can tell an appended repo from
+    # one that was there since the first run.
+    ledger["repos"][name] = {"type": args.type, "path": args.path,
+                             "snapshots": [], "iterations": []}
+    _save(args.out, ledger)
+    cfg_path = args.config or os.path.join(
+        os.path.dirname(os.path.abspath(args.out)), "uscha.config.json")
+    print("[qa_ledger] %s: repo '%s' added (%s at %s) -- %d repos, every existing repo's steps "
+          "untouched, checksum re-sealed"
+          % (args.out, name, args.type, args.path, len(ledger["repos"])))
+    print("[qa_ledger] %s" % _add_repo_to_config_file(cfg_path, entry, frozen_names))
+    print("[qa_ledger] '%s' starts with NO evidence: it reads as UNMEASURED (readiness lists it "
+          "under facts.static_unmeasured_repos) and every repo average reads lower until its "
+          "first snapshot or gate lands. That is an unmeasured repo, not a regression." % name)
+
+
 def cmd_init(args):
+    if getattr(args, "add_repo", None):
+        return _init_add_repo(args)
+    if not _has_text(getattr(args, "config", None)):
+        raise SystemExit("[qa_ledger] init needs --config to create a ledger, or --add-repo "
+                         "NAME (with --path and --type) to append one repo to an existing one")
     cfg = _load(args.config, what="config", flag="--config")
     _validate_init_config(cfg)
     defaults = cfg.get("defaults", {})
@@ -2497,7 +2656,16 @@ def _gate_rollup(ledger):
         for tool, rec in _latest_static_by_tool(rnode).items():
             gates.append({"repo": rname, "tool": tool,
                           "blocking": rec.get("gated_reported", 0) > 0,
+                          # ADR-043: an advisory record is non-blocking BY CONSTRUCTION, which
+                          # is not the same fact as a gate that ran and came back clean. It
+                          # travels so no consumer has to guess which of the two it is looking
+                          # at -- the false-clean is the failure mode, not the absence.
+                          "advisory": bool(rec.get("advisory")),
                           "gated": rec.get("gated_reported", 0),
+                          # WHERE it was measured (2.2.0, log-gate --ref): a CI verdict without
+                          # its run is a claim, and the rollup is where a reader looks first.
+                          # Absent on every record that carries none -- never invented.
+                          **({"ref": rec["ref"]} if rec.get("ref") else {}),
                           "note": rec.get("note")})
     return sorted(gates, key=lambda g: (g["repo"], g["tool"]))
 
@@ -2724,11 +2892,18 @@ def cmd_spec_change_request(args):
           (row["id"], args.repo, args.source, args.requested_change))
 
 
-def _append_gate_record(ledger, node, repo, tool, iteration, failing, count, note):
+def _append_gate_record(ledger, node, repo, tool, iteration, failing, count, note,
+                        advisory=False, ref=None):
     """Append a static-gate-shaped record for a FACT gate so the EXISTING plumbing
     sees it: _gate_open_and_sev feeds the BLOCKER/CRITICAL readiness cap (<=65) and
     _converged refuses while the latest record for the tool is failing. A later
-    clean record for the same tool clears it (latest-per-tool wins)."""
+    clean record for the same tool clears it (latest-per-tool wins).
+
+    advisory=True (kit 2.1.0, ADR-043) records a MEASUREMENT that is not a gate: the record
+    carries zero gated findings, so it can neither cap readiness nor block convergence, and it
+    is stamped so no surface can render it as a clean gate either. That distinction is the whole
+    point -- a check running advisory is not the same fact as a check running green, and a
+    ledger that cannot tell them apart is the false-clean this flag exists to refuse."""
     ledger["step_counter"] += 1
     n = max(1, count) if failing else 0
     rec = {
@@ -2740,24 +2915,70 @@ def _append_gate_record(ledger, node, repo, tool, iteration, failing, count, not
         "tests_passed": None, "files_changed": 0,
         "fingerprint": None, "finding_ids": None, "note": note,
     }
+    if advisory:
+        rec["advisory"] = True
+    if ref:
+        # WHERE the verdict was measured (2.2.0). A CI verdict typed by hand is a claim; the
+        # run id or URL beside it is the receipt, and the ledger is the only place it survives
+        # the conversation that produced it.
+        rec["ref"] = ref
     node["iterations"].append(rec)
     ledger["steps"].append({"n": rec["n"], "at": rec["at"], "kind": "static-gate",
                             "repo": repo, "tool": tool, "iteration": iteration})
     return rec
 
 
+# The only --kind values log-gate accepts with --verdict advisory (ADR-043): the checks whose
+# default mode IS advisory. Every other kind is a FACT gate and records pass/fail/not-run only.
+#
+# `corpus` (2.2.0, ADR-046) is admitted because `corpus-run` ITSELF runs advisory whenever no
+# threshold is declared -- the percentage is measured against no adopted budget, so it gates
+# nothing. Refusing the verdict on this door while the check emits it on the other would give
+# one fact two incompatible records: the parity door could only spell an unbudgeted run as
+# `pass`, which is the false clean ADR-043 exists to refuse. Admitting it costs nothing that
+# matters: with a threshold declared, `corpus` is a FACT gate like any other.
+#
+# `operability` (ADR-048) joins them because its posture is PROFILE-DEPENDENT: on A, B or no
+# profile the four checks are measured and recorded advisory, and only `defaults.operability.gate`
+# (which C, D and E own) turns the same measurement into a gate. It is a FACT either way -- a
+# workflow file exists or it does not -- so admitting it here widens WHEN it gates, never WHAT
+# counts as evidence, which is the line INV-ADVISORY-01 draws.
+ADVISORY_CAPABLE_KINDS = ("simplicity", "waste", "corpus", "operability")
+
+
 def cmd_log_gate(args):
-    """Persist a FACT-gate verdict (golden-diff / gate-check / pit-check / simplicity / regression)
-    into the ledger, so 'facts may block' is enforced by the engine, not by goodwill.
-      fail    -> BLOCKER record: trips the <=65 readiness cap AND blocks convergence.
-      pass    -> clean record for the same tool: credits the fix, convergence sees clean.
-      not-run -> a steps event ONLY, never an iterations record: absence is not
-                 evidence — it neither reads as clean nor fakes a red (last state stands).
+    """Persist a FACT-gate verdict (golden-diff / gate-check / pit-check / simplicity /
+    regression / ci / smoke) into the ledger, so 'facts may block' is enforced by the engine, not by
+    goodwill.
+      fail     -> BLOCKER record: trips the <=65 readiness cap AND blocks convergence.
+      pass     -> clean record for the same tool: credits the fix, convergence sees clean.
+      advisory -> a MEASURED, non-gating record (kit 2.1.0, ADR-043): zero gated findings, so
+                  it can never cap readiness nor block convergence, and stamped `advisory` so
+                  no surface counts it as an `ok` gate. Use it for a check the project has not
+                  declared as a gate -- `simplicity-check` in its default advisory mode above
+                  all. The alternative (persisting an advisory as `pass`) is the false clean
+                  this verdict exists to refuse: a reader cannot tell "the gate was green"
+                  from "there was no gate", and the second is what actually happened.
+      not-run  -> a steps event ONLY, never an iterations record: absence is not
+                  evidence — it neither reads as clean nor fakes a red (last state stands).
+
+    The engine cannot observe which mode a SEPARATE `simplicity-check` process ran in, so this
+    is a named verdict rather than a refusal: refusing would only be enforceable on trust,
+    while a third verdict is enforceable on the ledger. The caller declares the mode; every
+    reader downstream then sees it as a fact instead of inferring it.
     """
     # INV-ADVISORY-01 note (ADR-014): --kind is a CLOSED vocabulary (argparse choices), so
     # an advisory-class dimension (e.g. "semantic") cannot be registered as a gate through
     # this door at all -- the refusal is structural. The smoke suite measures that the
     # vocabulary stays closed; widening it to admit an advisory kind is a red build.
+    #
+    # `ci` and `smoke` (2.2.0) are the additions since ADR-014, and both are FACTS: a pipeline
+    # either went green on a commit or it did not, and the engine can be TOLD that fact with
+    # the run id or URL beside it (--ref); a smoke check either answered or it did not
+    # (ADR-047), which is why neither may run advisory. They are admitted here because they
+    # are measurable, not because they are useful -- an LLM judgment does not become a gate by
+    # being important. Adding a FACT kind is DECLARED in the CONSTITUTION template, which is
+    # where the closed vocabulary is stated to the project rather than only to this parser.
     ledger = _load(args.ledger)
     node = _repo_node(ledger, args.repo)
     tool = f"gate:{args.kind}"
@@ -2774,12 +2995,575 @@ def cmd_log_gate(args):
               f"(no evidence — last logged state stands, absence is never green)")
         return
     failing = args.verdict == "fail"
+    advisory = args.verdict == "advisory"
+    if advisory and args.kind not in ADVISORY_CAPABLE_KINDS:
+        # ADR-043 widens --verdict for the checks that RUN advisory by default. A FACT gate
+        # (deleted tests, a lowered threshold, a golden drift) recorded as advisory would be
+        # a mandatory gate cleared by goodwill -- the exact thing this ledger exists to refuse.
+        print(f"[qa_ledger] log-gate: --verdict advisory is not accepted for --kind {args.kind}: "
+              f"only {', '.join(ADVISORY_CAPABLE_KINDS)} run in an advisory mode; a FACT gate "
+              f"records pass, fail or not-run", file=sys.stderr)
+        sys.exit(2)
     rec = _append_gate_record(ledger, node, args.repo, tool, args.iteration,
-                              failing, args.count, args.note)
+                              failing, args.count, args.note, advisory=advisory,
+                              ref=getattr(args, "ref", None))
     _save(args.ledger, ledger)
-    state = f"FAIL (BLOCKER x{rec['gated_reported']})" if failing else "PASS (clean)"
-    print(f"[qa_ledger] {args.repo}/{tool}: {state} logged — "
-          f"{'caps readiness <=65 and blocks convergence' if failing else 'clears the gate for convergence'}")
+    if advisory:
+        state, effect = "ADVISORY (measured, not gating)", (
+            "reported everywhere as advisory, never as ok; caps nothing, blocks nothing")
+    elif failing:
+        state, effect = (f"FAIL (BLOCKER x{rec['gated_reported']})",
+                         "caps readiness <=65 and blocks convergence")
+    else:
+        state, effect = "PASS (clean)", "clears the gate for convergence"
+    print(f"[qa_ledger] {args.repo}/{tool}: {state} logged — {effect}"
+          + (f" [ref {rec['ref']}]" if rec.get("ref") else ""))
+
+
+# --------------------------------------------------------------------------- #
+# corpus-run (kit 2.2.0, ADR-046): FIELD TRUTH for greenfield work.
+#
+# `characterize`/`golden-diff` answer the brownfield question -- "does the new code still do
+# what the OLD code did?" -- and they have no answer at all for a system that never had an old
+# code. In a greenfield project every test payload was INVENTED by the agent that wrote the
+# code, so a suite can be green over inputs the world never produces. The field report this
+# subcommand comes from is exactly that shape: a parser passed every test its author wrote and
+# was wrong; running the REAL corpus moved it from 96.96 % to 99.645 %.
+#
+# So the corpus is the missing evidence class: real inputs with their real expected outputs,
+# run through the real command, scored as a percentage the ledger persists like any other FACT.
+# It is deterministic (stable case order, per-case timeout) and it refuses rather than guessing:
+# a corpus that is missing, empty or malformed is exit 2 naming the line, never a silent 0 %.
+#
+# The 2.1.0 posture holds (ADR-043): a gate needs an ADOPTED budget. With no threshold declared
+# anywhere the run is ADVISORY -- the percentage is measured and persisted, and it gates nothing.
+# The WEIGHT of field truth in the readiness score is deliberately NOT here: adding a `field`
+# dimension moves every existing project's number, and that is its own ADR.
+# --------------------------------------------------------------------------- #
+CORPUS_DEFAULT_TIMEOUT = 30
+CORPUS_DEFAULT_MAX_MISSES = 5
+
+
+def _corpus_refuse(msg):
+    """Every corpus refusal is exit 2 and NAMES what it could not read. The failure mode this
+    exists to prevent is a corpus the runner could not parse being scored as 0 % -- an
+    unmeasurable input reported as a measured catastrophe (or, with the arithmetic the other
+    way, as a clean 100 % over zero cases)."""
+    print("[qa_ledger] corpus-run: " + msg, file=sys.stderr)
+    sys.exit(2)
+
+
+def _corpus_cases(path):
+    """Read a JSONL corpus into an ORDERED list of cases: file order IS run order, so two runs
+    over the same file report the same misses in the same places. One JSON object per line,
+    `input` and `expected` required, `id` optional (a positional id is derived when absent)."""
+    if not os.path.isfile(path):
+        _corpus_refuse("corpus not found: %s -- a corpus that is not there is UNMEASURED, "
+                       "never a measured 0 %%" % path)
+    try:
+        with open(path, encoding="utf-8") as fh:
+            raw = fh.read().splitlines()
+    except OSError as exc:
+        _corpus_refuse("corpus unreadable: %s" % exc)
+    cases = []
+    for n, line in enumerate(raw, 1):
+        if not line.strip():
+            continue
+        try:
+            row = json.loads(line)
+        except ValueError as exc:
+            _corpus_refuse("%s line %d is not valid JSON (%s) -- a malformed corpus is "
+                           "refused, never scored" % (path, n, exc))
+        if not isinstance(row, dict):
+            _corpus_refuse("%s line %d is a %s, not a JSON object with `input` and `expected`"
+                           % (path, n, type(row).__name__))
+        missing = [k for k in ("input", "expected") if k not in row]
+        if missing:
+            _corpus_refuse("%s line %d has no %s key" % (path, n, " and no ".join(missing)))
+        cases.append({"id": str(row["id"]) if row.get("id") is not None
+                      else "case-%03d" % (len(cases) + 1),
+                      "input": row["input"], "expected": row["expected"]})
+    if not cases:
+        _corpus_refuse("%s holds 0 cases -- an empty corpus is refused: 0/0 is not 100 %%, "
+                       "and it is not 0 %% either" % path)
+    return cases
+
+
+def _corpus_text(value):
+    """A JSON scalar string travels as itself; anything else travels as its JSON encoding.
+    sort_keys so an object payload is byte-stable across runs."""
+    return value if isinstance(value, str) else json.dumps(value, ensure_ascii=False,
+                                                           sort_keys=True)
+
+
+def _corpus_match(actual, expected):
+    """Trimmed string compare first, then JSON-equal when BOTH sides parse as JSON -- so a
+    command that reorders an object's keys or prints 1.0 for 1 is not a false miss, while a
+    command that prints prose is compared as prose."""
+    exp, act = _corpus_text(expected).strip(), actual.strip()
+    if act == exp:
+        return True
+    try:
+        return json.loads(act) == json.loads(exp)
+    except ValueError:
+        return False
+
+
+def _corpus_case(command, case, timeout):
+    """Run ONE case: the input on stdin, the trimmed stdout compared to `expected`.
+    Returns (hit, reason, actual). A non-zero exit is a miss (the command did not answer);
+    a case that outruns the timeout is a miss NAMED `timeout`, never an ambiguous hang."""
+    try:
+        p = subprocess.run(command, shell=True, input=_corpus_text(case["input"]),
+                           stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
+                           encoding="utf-8", errors="replace", timeout=timeout)
+    except subprocess.TimeoutExpired:
+        return False, "timeout", ""
+    except OSError as exc:
+        return False, "command failed to start: %s" % exc, ""
+    actual = (p.stdout or "").strip()
+    if p.returncode != 0:
+        return False, "exit %d" % p.returncode, actual
+    if _corpus_match(actual, case["expected"]):
+        return True, None, actual
+    return False, "mismatch", actual
+
+
+def _corpus_num(value):
+    """90.0 reads back as 90 and 99.5 as 99.5 -- the declared budget renders as the human
+    typed it, in the ledger and on every surface that reads the record."""
+    if value is None:
+        return None
+    return int(value) if float(value).is_integer() else float(value)
+
+
+def _corpus_clip(text, n=120):
+    text = str(text).replace("\n", "\\n")
+    return text if len(text) <= n else text[:n] + "..."
+
+
+def cmd_corpus_run(args):
+    """Run a REAL-INPUT corpus against a command and persist the result as `gate:corpus`.
+
+    The threshold is the project's, never the kit's: --threshold, else
+    repos[R].corpus_threshold, else defaults.corpus_threshold. With none of the three the run
+    is ADVISORY -- measured, persisted, and gating nothing (ADR-043: a gate needs an adopted
+    budget). With one, `pass` is a clean gate and `fail` is a BLOCKER through the SAME record
+    shape gate-check uses: readiness capped <=65, convergence blocked, and a later green run
+    clears it (latest-per-tool wins).
+
+    --ac stamps criterion ids on the record. A criterion whose only evidence is a corpus record
+    closes MEASURED iff that record passed -- the same rule a green JUnit testcase already
+    obeys, and for the same reason: red or unbudgeted evidence closes nothing."""
+    ledger = _load(args.ledger)
+    node = _repo_node(ledger, args.repo)
+    tool = "gate:corpus"
+    _validate_iteration(node, tool, args.iteration)
+    cfg = next((r for r in ledger["config"].get("repos", [])
+                if r.get("name") == args.repo), {})
+    defaults = ledger["config"].get("defaults", {})
+
+    corpus_path = args.corpus or cfg.get("corpus")
+    if not corpus_path:
+        _corpus_refuse("no corpus: pass --corpus PATH or declare repos[%s].corpus in the "
+                       "config. Where the real inputs live is the project's fact, not a "
+                       "default this engine may invent." % args.repo)
+    cases = _corpus_cases(corpus_path)
+
+    threshold, source = args.threshold, "--threshold"
+    if threshold is None:
+        threshold, source = cfg.get("corpus_threshold"), "repos[%s].corpus_threshold" % args.repo
+    if threshold is None:
+        threshold, source = defaults.get("corpus_threshold"), "defaults.corpus_threshold"
+    if threshold is None:
+        source = None
+    threshold = _corpus_num(threshold)
+
+    acs = []
+    for raw in (args.ac or []):
+        cid, _end = _ac_id_of(raw.strip())
+        if cid is None:
+            _corpus_refuse("--ac %r is not a criterion id ('AC-01' or 'AC-FIELD-01')" % raw)
+        if cid not in acs:
+            acs.append(cid)
+
+    hits, misses = 0, []
+    for case in cases:
+        ok, reason, actual = _corpus_case(args.command, case, args.timeout)
+        if ok:
+            hits += 1
+        else:
+            misses.append({"id": case["id"], "reason": reason,
+                           "expected": _corpus_clip(_corpus_text(case["expected"])),
+                           "actual": _corpus_clip(actual)})
+    total = len(cases)
+    pct = round(100.0 * hits / total, 1)
+
+    advisory = source is None
+    failing = (not advisory) and pct < threshold
+    if advisory:
+        note = "corpus %s: %d/%d (%s %%), no threshold declared" % (
+            os.path.basename(corpus_path), hits, total, pct)
+    else:
+        note = "corpus %s: %d/%d (%s %%) %s %s %%" % (
+            os.path.basename(corpus_path), hits, total, pct,
+            "<" if failing else ">=", threshold)
+    rec = _append_gate_record(ledger, node, args.repo, tool, args.iteration,
+                              failing, len(misses), note, advisory=advisory)
+    # the MEASUREMENT travels on the record, not only its verdict: readiness reads the
+    # percentage back for the field line, and a reader six months later can see WHAT was
+    # measured against WHICH budget instead of a bare pass.
+    rec["corpus"] = {"path": corpus_path.replace("\\", "/"), "hits": hits, "total": total,
+                     "percent": pct, "threshold": threshold, "threshold_source": source,
+                     "timeout_s": args.timeout,
+                     "misses": misses[:max(0, args.max_misses)]}
+    if acs:
+        rec["ac"] = acs
+    _save(args.ledger, ledger)
+
+    state = ("ADVISORY (measured, not gating)" if advisory
+             else "FAIL" if failing else "PASS")
+    out = {"repo": args.repo, "tool": tool, "verdict": state.split()[0].lower(),
+           "advisory": advisory, "corpus": rec["corpus"], "ac": acs, "note": note}
+    if args.json:
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        if advisory:
+            budget = ("no threshold declared — the percentage is recorded and nothing gates "
+                      "(a gate needs an adopted budget, ADR-043)")
+        else:
+            budget = "threshold %s %% from %s" % (threshold, source)
+        print("[qa_ledger] %s/%s: %s %s %% (%d/%d) — %s"
+              % (args.repo, tool, state, pct, hits, total, budget))
+        for m in rec["corpus"]["misses"]:
+            print("  miss %s (%s): expected %r, got %r"
+                  % (m["id"], m["reason"], m["expected"], m["actual"]))
+        if len(misses) > len(rec["corpus"]["misses"]):
+            print("  ... +%d more miss(es) not listed (--max-misses)"
+                  % (len(misses) - len(rec["corpus"]["misses"])))
+        if failing:
+            print("  caps readiness <=65 and blocks convergence until a green run")
+    sys.exit(1 if failing else 0)
+
+
+def _corpus_records(ledger):
+    """The LATEST corpus record per repo -- the same latest-per-tool rule the gate rollup and
+    convergence already use, so the three cannot disagree about which run is current. A record
+    logged through the `log-gate --kind corpus` parity door carries no `corpus` block and is
+    deliberately not here: it gates (it is a gate record like any other), but it has no run to
+    read back, and rendering it anyway printed the honest-looking nonsense
+    `corpus None % (None/None) >= None % PASS`. Same exclusion, same reason, as
+    `_smoke_records`."""
+    out = {}
+    for rname, rnode in ledger.get("repos", {}).items():
+        rec = _latest_static_by_tool(rnode).get("gate:corpus")
+        if rec is not None and rec.get("corpus"):
+            out[rname] = rec
+    return out
+
+
+def _corpus_ac_verdicts(ledger):
+    """(closed, vetoed) criterion ids from the latest corpus record of every repo (ADR-046).
+
+    A corpus record CLOSES an AC iff it PASSED. An **advisory** run measured a percentage
+    against no adopted budget: it is not a green gate (ADR-043 refuses to let it read as one)
+    and it is not red evidence either, so it neither closes nor vetoes. A **failing** run is
+    evidence AGAINST, which ADR-046 said from the start -- and the engine used to merely skip
+    it, so a green testcase went on closing a criterion the field had just refuted. It now
+    VETOES the ids it carries, the same rule a red JUnit testcase and a failed tagged smoke
+    check already obey, and for the same reason: the cheapest way to fake a closed criterion is
+    to put a green beside a red."""
+    closed, vetoed = set(), set()
+    for rec in _corpus_records(ledger).values():
+        if rec.get("advisory"):
+            continue
+        if (rec.get("gated_reported") or 0) > 0:
+            vetoed.update(rec.get("ac") or [])
+        else:
+            closed.update(rec.get("ac") or [])
+    return closed - vetoed, vetoed
+
+
+def _corpus_field(ledger):
+    """Per-repo FIELD readout -- ONE derivation, read by both the readiness text and its JSON.
+    CONDITIONAL like lifecycle and agent-origin: a repo that neither declares a corpus nor ever
+    ran one is absent from it, so a project without field truth prints and emits exactly what
+    it printed and emitted before this existed. No weight, no cap, no gate of its own -- a
+    failing corpus already blocks through its `gate:corpus` record, and the `field` DIMENSION
+    (its own ADR) is deliberately not here."""
+    recs = _corpus_records(ledger)
+    out = {}
+    for rname in ledger.get("repos", {}):
+        cfg = next((r for r in ledger.get("config", {}).get("repos", [])
+                    if r.get("name") == rname), {})
+        rec, declared = recs.get(rname), cfg.get("corpus")
+        if rec is None and not declared:
+            continue
+        if rec is None:
+            out[rname] = {"state": "UNMEASURED", "corpus": declared, "percent": None,
+                          "hits": None, "total": None, "threshold": None,
+                          "reason": "a corpus is declared and was never run"}
+            continue
+        c = rec.get("corpus") or {}
+        out[rname] = {"state": ("ADVISORY" if rec.get("advisory")
+                                else "FAIL" if (rec.get("gated_reported") or 0) > 0
+                                else "PASS"),
+                      "corpus": c.get("path", declared),
+                      "percent": c.get("percent"), "hits": c.get("hits"),
+                      "total": c.get("total"), "threshold": c.get("threshold"),
+                      "threshold_source": c.get("threshold_source"),
+                      "ac": rec.get("ac") or []}
+    return out
+
+
+def _corpus_field_line(rname, f):
+    """The one-line rendering of a repo's field state. Text lives beside the derivation so the
+    JSON and the human readout can never drift apart."""
+    if f["state"] == "UNMEASURED":
+        return ("--- field %s: corpus UNMEASURED — %s (%s)"
+                % (rname, f["reason"], f["corpus"]))
+    head = "--- field %s: corpus %s %% (%s/%s)" % (rname, f["percent"], f["hits"], f["total"])
+    if f["state"] == "ADVISORY":
+        return head + " — no threshold declared, ADVISORY (measured, not gating)"
+    return "%s %s %s %% %s" % (head, "<" if f["state"] == "FAIL" else ">=",
+                               f["threshold"], f["state"])
+
+
+# --------------------------------------------------------------------------- #
+# smoke-ingest (kit 2.2.0, ADR-047): the SMOKE RUN as measured evidence.
+#
+# The ledger already ingests the evidence a machine produces on its own -- JUnit, coverage,
+# linters, a static gate's XML, a CI verdict. The smoke list was the hole: "the jar served
+# /admin", "the simulator answered 200 in 6 ms" arrived as a sub-agent's NARRATION, believed
+# because it was written confidently. The field report this subcommand comes from is exactly
+# that shape: every simulator run returned an empty list because the database had no rows, and
+# a smoke narrated as "verified" would have hidden it behind a sentence.
+#
+# So the smoke run stops being prose and becomes a REPORT the project's own tool writes --
+# {"checks": [{"name", "ok", "status"?, "latency_ms"?, "evidence"?}, ...]} -- and the engine
+# ingests it like any other fact. `smoke` is a FACT kind and is never advisory: a smoke check is
+# binary. It either answered or it did not; there is no "measured against no adopted budget"
+# reading of `ok`, which is why `corpus` may run advisory and this may not.
+#
+# Evidence is EXECUTED, not narrated -- and a report the engine cannot read is refused (exit 2)
+# rather than scored, for the same reason a malformed corpus is: an unreadable smoke reported as
+# "0 checks ok" would be an unmeasurable run rendered as a measured catastrophe, and an EMPTY
+# `checks` list read as a clean gate would be the false clean in the other direction.
+# --------------------------------------------------------------------------- #
+# How many checks (and failed names) travel on the record. A receipt cites evidence, it is not
+# a dump -- the same cap `_ac_tags` puts on its testcase receipts, for the same reason.
+SMOKE_MAX_PERSISTED = 20
+
+
+def _smoke_refuse(msg):
+    """Every smoke-ingest refusal is exit 2 and NAMES the offending check or field. The report
+    is written by the PROJECT's own tool, so what this guards against is a contract the project
+    got subtly wrong -- and a wrong contract that scored anyway would be worse than one that
+    refused, because the number would look like a measurement."""
+    print("[qa_ledger] smoke-ingest: " + msg, file=sys.stderr)
+    sys.exit(2)
+
+
+def _smoke_checks(path):
+    """Read a smoke report into an ORDERED list of checks. The contract is deliberately the
+    smallest thing a shell script can emit:
+
+        {"checks": [{"name": "...", "ok": true|false,
+                     "status": <int|string, optional>,
+                     "latency_ms": <number, optional>,
+                     "evidence": "<string, optional>"}]}
+
+    `name` and a BOOLEAN `ok` are the whole mandatory surface. `ok: "true"` and `ok: 1` are
+    refused: a string and a number are not verdicts, and a contract that coerces is a contract
+    that cannot say what it measured. The optional fields are validated when PRESENT and never
+    invented when absent -- a check with no `latency_ms` measured no latency, which is a
+    different fact from a latency of 0."""
+    if not os.path.isfile(path):
+        _smoke_refuse("report not found: %s -- a smoke run that left no report is UNMEASURED, "
+                      "never a clean gate" % path)
+    try:
+        with open(path, encoding="utf-8") as fh:
+            doc = json.load(fh)
+    except OSError as exc:
+        _smoke_refuse("report unreadable: %s" % exc)
+    except ValueError as exc:
+        _smoke_refuse("%s is not valid JSON (%s) -- a malformed report is refused, never "
+                      "scored" % (path, exc))
+    if not isinstance(doc, dict):
+        _smoke_refuse("%s is a %s, not a JSON object carrying a `checks` list"
+                      % (path, type(doc).__name__))
+    if "checks" not in doc:
+        _smoke_refuse('%s has no `checks` key -- the contract is {"checks": [{"name": ..., '
+                      '"ok": true|false}, ...]}' % path)
+    raw = doc["checks"]
+    if not isinstance(raw, list):
+        _smoke_refuse("%s: `checks` is a %s, not a list" % (path, type(raw).__name__))
+    if not raw:
+        _smoke_refuse("%s holds 0 checks -- an EMPTY smoke is not evidence: it is a run that "
+                      "verified nothing, and it does not read as a clean gate" % path)
+    checks = []
+    for i, row in enumerate(raw):
+        where = "check %d" % (i + 1)
+        if not isinstance(row, dict):
+            _smoke_refuse("%s: %s is a %s, not an object" % (path, where, type(row).__name__))
+        name = row.get("name")
+        if not isinstance(name, str) or not name.strip():
+            _smoke_refuse("%s: %s has no `name` -- a check nobody can name is a check nobody "
+                          "can act on" % (path, where))
+        where = "%s (%s)" % (where, name.strip())
+        if not isinstance(row.get("ok"), bool):
+            _smoke_refuse("%s: %s has no boolean `ok` (got %r) -- a smoke check is a binary "
+                          "fact, and a string, a number or a missing key is not a verdict"
+                          % (path, where, row.get("ok")))
+        status = row.get("status")
+        if status is not None and (isinstance(status, bool)
+                                   or not isinstance(status, (int, str))):
+            _smoke_refuse("%s: %s has a `status` that is neither an integer nor a string (%r)"
+                          % (path, where, status))
+        lat = row.get("latency_ms")
+        if lat is not None and (isinstance(lat, bool) or not isinstance(lat, (int, float))):
+            _smoke_refuse("%s: %s has a `latency_ms` that is not a number (%r)"
+                          % (path, where, lat))
+        ev = row.get("evidence")
+        if ev is not None and not isinstance(ev, str):
+            _smoke_refuse("%s: %s has an `evidence` that is not a string (%r)"
+                          % (path, where, ev))
+        checks.append({"name": name.strip(), "ok": row["ok"], "status": status,
+                       "latency_ms": lat, "evidence": ev})
+    return checks
+
+
+def _smoke_ac_of(checks, want_ok):
+    """Criterion ids tagged on check NAMES, in the SAME grammar a JUnit testcase name uses
+    (`_ac_tag_ids`, ADR-036): a check named "AC-28 the admin page serves" tags AC-28. One
+    extractor, so a name cannot close a criterion in the suite and fail to close it here."""
+    ids = []
+    for c in checks:
+        if bool(c["ok"]) != want_ok:
+            continue
+        for cid in _ac_tag_ids(c["name"]):
+            if cid not in ids:
+                ids.append(cid)
+    return sorted(ids, key=_top_ac_key)
+
+
+def cmd_smoke_ingest(args):
+    """Ingest a smoke report as `gate:smoke` -- the smoke run MEASURED instead of narrated.
+
+    A failed check is a BLOCKER through the SAME record shape `gate-check` and `corpus-run`
+    write: readiness capped <=65, convergence blocked, and a later clean report clears it
+    (latest-per-tool wins). `smoke` is a FACT kind and is NOT advisory-capable: `ok` is binary,
+    so there is no budget it could be measured against and no honest advisory reading of it.
+
+    A check whose NAME carries an AC tag closes that criterion MEASURED iff the check is `ok`
+    AND the report as a whole passed -- and a FAILED tagged check is red evidence that vetoes,
+    exactly like a red JUnit testcase. Fail-closed in both directions: a green check inside a
+    failing smoke closes nothing, because the run it belongs to did not hold."""
+    ledger = _load(args.ledger)
+    node = _repo_node(ledger, args.repo)
+    tool = "gate:smoke"
+    _validate_iteration(node, tool, args.iteration)
+    checks = _smoke_checks(args.report)
+
+    n_ok = sum(1 for c in checks if c["ok"])
+    failed = [c for c in checks if not c["ok"]]
+    failing = bool(failed)
+    failed_names = [c["name"] for c in failed]
+    note = "smoke %s: %d/%d checks ok%s" % (
+        os.path.basename(args.report), n_ok, len(checks),
+        (", %d failed (%s)" % (len(failed), ", ".join(failed_names[:SMOKE_MAX_PERSISTED])))
+        if failed else "")
+    rec = _append_gate_record(ledger, node, args.repo, tool, args.iteration,
+                              failing, len(failed), note)
+    # the MEASUREMENT travels on the record, not only its verdict: a reader six months later
+    # sees WHICH checks ran, what each answered and how long it took -- the facts the narration
+    # used to carry and lose.
+    rec["smoke"] = {
+        "report": args.report.replace("\\", "/"), "ok": n_ok, "failed": len(failed),
+        "checks": [{"name": c["name"], "ok": c["ok"], "status": c["status"],
+                    "latency_ms": c["latency_ms"]} for c in checks[:SMOKE_MAX_PERSISTED]],
+        "failed_names": failed_names[:SMOKE_MAX_PERSISTED],
+        # computed over EVERY check, never over the truncated receipt above: the cap is a
+        # display budget, and a criterion's fate must not depend on where the list was cut.
+        "ac": _smoke_ac_of(checks, True),
+        "ac_red": _smoke_ac_of(checks, False),
+    }
+    _save(args.ledger, ledger)
+
+    out = {"repo": args.repo, "tool": tool, "verdict": "fail" if failing else "pass",
+           "smoke": rec["smoke"], "note": note}
+    if args.json:
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        print("[qa_ledger] %s/%s: %s — %d/%d checks ok"
+              % (args.repo, tool, "FAIL" if failing else "PASS", n_ok, len(checks)))
+        for c in checks[:SMOKE_MAX_PERSISTED]:
+            bits = [b for b in ("status %s" % c["status"] if c["status"] is not None else None,
+                                "%s ms" % c["latency_ms"] if c["latency_ms"] is not None
+                                else None) if b]
+            print("  %s %s%s" % ("ok  " if c["ok"] else "FAIL", c["name"],
+                                 (" (%s)" % ", ".join(bits)) if bits else ""))
+        if len(checks) > SMOKE_MAX_PERSISTED:
+            print("  ... +%d more check(s) not listed or persisted"
+                  % (len(checks) - SMOKE_MAX_PERSISTED))
+        if failing:
+            print("  caps readiness <=65 and blocks convergence until a clean smoke")
+    sys.exit(1 if failing else 0)
+
+
+def _smoke_records(ledger):
+    """The LATEST smoke record per repo -- the same latest-per-tool rule the gate rollup and
+    convergence already use, so the three cannot disagree about which run is current. A record
+    logged through the `log-gate` parity door carries no `smoke` block and is deliberately not
+    here: it gates (it is a gate record like any other), but it has no checks to read back."""
+    out = {}
+    for rname, rnode in ledger.get("repos", {}).items():
+        rec = _latest_static_by_tool(rnode).get("gate:smoke")
+        if rec is not None and rec.get("smoke"):
+            out[rname] = rec
+    return out
+
+
+def _smoke_ac_verdicts(ledger):
+    """(closed, vetoed) criterion ids from the latest smoke record of every repo (ADR-047).
+
+    A tagged check closes MEASURED iff it is `ok` AND its report's gate PASSED: a green check
+    inside a failing smoke is a green light on a run that did not hold, and the ledger refuses
+    to read it as one. A FAILED tagged check is red evidence and vetoes wherever it appears --
+    the same rule as a red JUnit testcase, and it outranks every green."""
+    closed, vetoed = set(), set()
+    for rec in _smoke_records(ledger).values():
+        s = rec.get("smoke") or {}
+        vetoed.update(s.get("ac_red") or [])
+        if not (rec.get("gated_reported") or 0):
+            closed.update(s.get("ac") or [])
+    return closed - vetoed, vetoed
+
+
+def _smoke_report(ledger):
+    """Per-repo SMOKE readout -- ONE derivation, read by both the readiness text and its JSON.
+    CONDITIONAL like lifecycle, agent-origin and field: a repo that never ingested a smoke
+    report is absent from it, so a project that never ran one prints and emits exactly what it
+    printed and emitted before this existed."""
+    out = {}
+    for rname, rec in _smoke_records(ledger).items():
+        s = rec["smoke"]
+        out[rname] = {"state": "FAIL" if (rec.get("gated_reported") or 0) else "PASS",
+                      "report": s.get("report"), "ok": s.get("ok"),
+                      "failed": s.get("failed"),
+                      "total": (s.get("ok") or 0) + (s.get("failed") or 0),
+                      "failed_names": s.get("failed_names") or [],
+                      "ac": s.get("ac") or [], "ac_red": s.get("ac_red") or []}
+    return out
+
+
+def _smoke_line(rname, s):
+    """The one-line rendering of a repo's smoke state. Text lives beside the derivation so the
+    JSON and the human readout can never drift apart."""
+    head = "--- smoke %s: %d/%d checks ok" % (rname, s["ok"], s["total"])
+    if s["failed"]:
+        head += ", %d failed (%s)" % (s["failed"], ", ".join(s["failed_names"]))
+    return "%s %s" % (head, s["state"])
 
 
 def cmd_flag_blocker(args):
@@ -2966,6 +3750,16 @@ def _derive_phase(ledger, name, node, k, qa_order):
                               if len(_dl["uncurated"]) > 3 else "")
                            + " -- INV-CURATION-01: sin juicio no hay promocion")
             conv = False
+    # operability gate (ADR-048). NAMING only: a failing record is already a BLOCKER through
+    # _gate_open_and_sev and already vetoes convergence through _converged, so nothing new is
+    # gated here. What is added is WHICH check is missing -- "static-gate gated=1
+    # (gate:operability:1)" tells a human the gate is red without telling them whether to write
+    # a workflow or a RUNBOOK, and phase --require pr-ready is where that answer is needed.
+    _op = _latest_static_by_tool(node).get("gate:operability")
+    if _op and (_op.get("gated_reported") or 0) > 0:
+        reasons.append("operability: %s -- release, reset and the RUNBOOK are part of done, "
+                       "not of the last week (ADR-048)"
+                       % (_op.get("note") or "checks missing"))
     _cr = _cr_cfg(ledger)
     if _cr and _cr.get("mode") == "final":
         _head = None
@@ -3455,15 +4249,35 @@ def cmd_spec_drift(args):
     lag_days = int(args.max_lag_days if args.max_lag_days is not None
                    else cfg.get("max_lag_days", 30))
     repo_path = _scope_path(ledger, args.repo)
+    root_path = os.path.dirname(os.path.abspath(args.ledger)) or "."
 
     # The spec surface is fixed by ADR-005: the repo SPEC.md plus every ADR.
-    spec_files = []
-    if os.path.isfile(os.path.join(repo_path, "SPEC.md")):
-        spec_files.append("SPEC.md")
-    adr_dir = os.path.join(repo_path, "docs", "adr")
-    if os.path.isdir(adr_dir):
-        spec_files += sorted("docs/adr/" + f for f in os.listdir(adr_dir)
-                             if f.lower().endswith(".md"))
+    def _specs_at(base):
+        found = []
+        if os.path.isfile(os.path.join(base, "SPEC.md")):
+            found.append("SPEC.md")
+        adr_dir = os.path.join(base, "docs", "adr")
+        if os.path.isdir(adr_dir):
+            found += sorted("docs/adr/" + f for f in os.listdir(adr_dir)
+                            if f.lower().endswith(".md"))
+        return found
+
+    # 2.2.0 field fix: a MONOREPO keeps ONE SPEC.md and one docs/adr/ at the root, next to
+    # uscha.config.json, while repos[R].path points at a subdirectory -- and this command read
+    # only that subdirectory, so `spec-drift --repo backend-api` answered "no spec documents"
+    # about a project whose spec was one level up. A spec found at the root is the MONOREPO's
+    # spec and governs every repo. The repo's own path still WINS when it has one (a repo that
+    # carries its own SPEC is describing itself); the config root -- taken as the ledger's
+    # directory, which is where `init --config uscha.config.json` is run -- is the fallback.
+    # The answer NAMES which of the two it read: "no drift" and "read the wrong tree" produced
+    # the same silence, and that is what made the field report take a week to notice.
+    base_path, spec_source = repo_path, "repo"
+    spec_files = _specs_at(repo_path)
+    if not spec_files and os.path.realpath(root_path) != os.path.realpath(repo_path):
+        root_specs = _specs_at(root_path)
+        if root_specs:
+            base_path, spec_source, spec_files = root_path, "root", root_specs
+    repo_path = base_path
 
     tracked = []
     ls = subprocess.run(["git", "ls-files"], cwd=repo_path, capture_output=True,
@@ -3535,20 +4349,26 @@ def cmd_spec_drift(args):
         results.append(row)
 
     out = {"repo": args.repo, "max_lag_days": lag_days, "results": results,
-           "advisory": True}
+           "advisory": True, "spec_source": spec_source if spec_files else None,
+           "spec_base": repo_path}
 
     # Latest-state record so the mirador can surface an advisory row. Advisory data,
     # not a step in the loop: no step_counter, no gate record, no readiness input.
     ledger["spec_drift"] = {"repo": args.repo, "at": _now(), "max_lag_days": lag_days,
-                            "results": results}
+                            "results": results,
+                            "spec_source": spec_source if spec_files else None}
     _save(args.ledger, ledger)
 
     if args.json:
         print(json.dumps(out, indent=2, ensure_ascii=False))
     else:
         print("SPEC-DRIFT %s (advisory, lag > %dd):" % (args.repo, lag_days))
+        if spec_source == "root" and spec_files:
+            print("  specs read from the CONFIG ROOT (%s): the monorepo's SPEC governs "
+                  "every repo" % repo_path)
         if not results:
-            print("  no spec documents found (SPEC.md / docs/adr/*.md)")
+            print("  no spec documents found (SPEC.md / docs/adr/*.md) in the repo path "
+                  "nor at the config root")
         mark = {"SPEC_STALE": "!!", "CLEAN": "ok", "UNMAPPED": "--", "UNTRACKED": "--",
                 "NO-CODE": "ok"}
         for r_ in results:
@@ -3563,6 +4383,330 @@ def cmd_spec_drift(args):
     sys.exit(0)
 
 
+# --------------------------------------------------------------------------- #
+# operability  (ADR-048: release, reset and the RUNBOOK are MEASURED, not narrated)
+# --------------------------------------------------------------------------- #
+# The field finding, twice in a row: release-by-CI, the reset/seed script and the RUNBOOK
+# arrived in the last week of two projects. The devloop NAMED them in phase 8 prose and
+# nothing measured them, so "we'll do it at the end" survived every gate the kit has -- the
+# same shape as every other narrated dimension this engine has replaced with a fact.
+#
+# What this command reads is FILES IN THE TREE, never prose and never a claim: a workflow that
+# runs the repo's own test command, a workflow that publishes something, a RUNBOOK with the
+# four headings an operator needs at 3am, and a seed/reset command the config declares whose
+# script is actually on disk. It cannot read whether the RUNBOOK is GOOD -- that is a human
+# judgment and it is not pretended here. It can read that the file exists and that the
+# sections are named, which is the difference between a project that thought about rollback
+# and one that has not yet.
+#
+# It never executes anything (ADR-008: the engine is not an executor of config-supplied
+# shell) and its own exit code is always 0. Whether the verdict GATES is the project's
+# declaration -- `defaults.operability.gate`, owned by risk profiles C, D and E.
+OPERABILITY_CHECKS = ("ci", "release", "runbook", "seed")
+
+# GitHub Actions is the only CI this reads. Another system is NAMED as unknown rather than
+# failed: the engine cannot open a pipeline it does not understand, and a red invented for a
+# pipeline nobody read would be exactly the manufactured verdict the kit refuses elsewhere.
+OPERABILITY_CI_DIR = (".github", "workflows")
+OPERABILITY_OTHER_CI = (
+    ".gitlab-ci.yml", ".travis.yml", "azure-pipelines.yml", "bitbucket-pipelines.yml",
+    "Jenkinsfile", ".circleci", ".drone.yml", ".teamcity",
+)
+# The publish recognisers, listed rather than guessed: a workflow step that creates or
+# attaches a release asset. Short and documented on purpose -- a regex over "release" would
+# match a branch name, a job title and a comment, and a gate that matches prose is a gate that
+# certifies prose.
+OPERABILITY_RELEASE_MARKERS = (
+    "softprops/action-gh-release",
+    "actions/upload-release-asset",
+    "gh release create",
+    "gh release upload",
+    "gh release",
+    "npm publish",
+    "twine upload",
+)
+# A test-ish subcommand, for the case where the workflow does not repeat the configured
+# command verbatim (a Makefile target, an extra flag, a matrix variable in the middle).
+OPERABILITY_TEST_WORDS = ("test", "tests", "pytest", "nextest", "jest", "check", "verify")
+# The four headings an operator needs, matched case-insensitively in EN and ES. What is
+# matched is the HEADING, not the body: the engine can see that rollback was thought about,
+# never that the procedure is correct.
+OPERABILITY_RUNBOOK_SECTIONS = (
+    ("start", r"arranque|start|boot"),
+    ("config", r"config"),
+    ("rollback", r"rollback|reversi"),
+    ("smoke", r"smoke|humo"),
+)
+OPERABILITY_RUNBOOK_PATHS = ("docs/RUNBOOK.md", "RUNBOOK.md")
+OPERABILITY_SCRIPT_EXT = (".sh", ".py", ".ps1", ".bat", ".sql", ".js", ".ts", ".rb")
+
+
+def _op_bases(ledger, repo, ledger_path):
+    """(repo path, config root) with realpath on BOTH sides -- the Windows 8.3 lesson, and the
+    monorepo lesson spec-drift paid for in 2.2.0: the workflows and the RUNBOOK of a monorepo
+    live at the config root while repos[R].path points at a subdirectory. The repo's own tree
+    WINS when it has the artifact; the root is the fallback, and the answer NAMES which one it
+    read, because "no CI" and "read the wrong tree" produced the same silence."""
+    repo_path = _scope_path(ledger, repo)
+    root_path = os.path.dirname(os.path.abspath(ledger_path)) or "."
+    bases = [(repo_path, "repo")]
+    if os.path.realpath(root_path) != os.path.realpath(repo_path):
+        bases.append((root_path, "root"))
+    return bases
+
+
+def _op_workflows(bases):
+    """(list of (relative name, text), base, where) for the first base that HAS a GitHub
+    Actions directory, else ([], None, None)."""
+    for base, where in bases:
+        wdir = os.path.join(base, *OPERABILITY_CI_DIR)
+        if not os.path.isdir(wdir):
+            continue
+        files = []
+        for name in sorted(os.listdir(wdir)):
+            if not name.lower().endswith((".yml", ".yaml")):
+                continue
+            try:
+                with open(os.path.join(wdir, name), encoding="utf-8",
+                          errors="replace") as fh:
+                    files.append((name, fh.read()))
+            except OSError:
+                continue
+        if files:
+            return files, base, where
+    return [], None, None
+
+
+def _op_other_ci(bases):
+    """The first non-Actions CI marker found, as `name (where)`, or None."""
+    for base, where in bases:
+        for name in OPERABILITY_OTHER_CI:
+            if os.path.exists(os.path.join(base, name)):
+                return "%s (%s)" % (name, where)
+    return None
+
+
+def _op_test_command(ledger, repo):
+    """The repo's CONFIGURED test command: repos[R].test_command, else the per-type
+    defaults.test_command_<type>. Read, never run."""
+    cfg = ledger.get("config") or {}
+    defaults = cfg.get("defaults") or {}
+    entry = {}
+    for r in cfg.get("repos", []):
+        if r.get("name") == repo:
+            entry = r
+            break
+    if _has_text(entry.get("test_command")):
+        return entry["test_command"].strip()
+    rtype = entry.get("type") or (ledger.get("repos", {}).get(repo) or {}).get("type")
+    value = defaults.get("test_command_%s" % rtype) if rtype else None
+    return value.strip() if _has_text(value) else None
+
+
+def _op_ci(workflows, command):
+    """(status, detail). `ok` when a workflow step runs the configured command -- verbatim, or
+    its first token beside a test-ish subcommand on the same line. The detail SAYS what
+    matched, so the human can disagree with the match instead of with a boolean."""
+    if not command:
+        return "missing", "no test command configured for this repo (nothing to look for)"
+    head = command.split()[0]
+    tail = os.path.basename(head)
+    for name, body in workflows:
+        for line in body.splitlines():
+            stripped = line.strip()
+            if command in line:
+                return "ok", '%s runs "%s"' % (name, command)
+            if head not in line and tail not in line:
+                continue
+            words = re.split(r"[^A-Za-z0-9_.-]+", stripped.lower())
+            if any(w in OPERABILITY_TEST_WORDS for w in words):
+                shown = re.sub(r"^-\s*", "", stripped)
+                shown = re.sub(r"^run:\s*", "", shown)
+                return "ok", '%s runs "%s"' % (name, shown[:70])
+    return "missing", ("no workflow step runs the configured test command (%s)"
+                       % command)
+
+
+def _op_release(workflows):
+    for name, body in workflows:
+        for marker in OPERABILITY_RELEASE_MARKERS:
+            if marker in body:
+                return "ok", '%s runs "%s"' % (name, marker)
+    return "missing", ("no workflow publishes or attaches a release asset (looked for: %s)"
+                       % ", ".join(OPERABILITY_RELEASE_MARKERS))
+
+
+def _op_runbook(bases, declared):
+    """(status, detail, path). `declared` is defaults.operability.runbook when the project set
+    one; otherwise docs/RUNBOOK.md then RUNBOOK.md, repo tree before config root."""
+    candidates = [declared] if _has_text(declared) else list(OPERABILITY_RUNBOOK_PATHS)
+    for base, where in bases:
+        for rel in candidates:
+            path = os.path.join(base, rel.replace("/", os.sep))
+            if not os.path.isfile(path):
+                continue
+            try:
+                with open(path, encoding="utf-8", errors="replace") as fh:
+                    body = fh.read()
+            except OSError as exc:
+                return "missing", "%s unreadable: %s" % (rel, exc), rel
+            heads = [row.lstrip("#").strip().lower()
+                     for row in body.splitlines() if row.lstrip().startswith("#")]
+            blob = "\n".join(heads)
+            absent = [label for label, pattern in OPERABILITY_RUNBOOK_SECTIONS
+                      if not re.search(pattern, blob, re.I)]
+            if absent:
+                return ("missing", "missing sections (%s) in %s [%s]"
+                        % (", ".join(absent), rel, where), rel)
+            return "ok", "%s [%s], all four sections named" % (rel, where), rel
+    return ("missing", "no RUNBOOK found (looked for %s)" % ", ".join(candidates), None)
+
+
+def _op_seed(ledger, repo, bases, defaults_op):
+    """(status, detail). The seed/reset command is DECLARED, never sniffed: an engine that
+    guessed which script resets the database would be guessing about the most destructive
+    command in the project."""
+    entry = {}
+    for r in (ledger.get("config") or {}).get("repos", []):
+        if r.get("name") == repo:
+            entry = r
+            break
+    repo_op = entry.get("operability") if isinstance(entry.get("operability"), dict) else {}
+    command = repo_op.get("seed_command")
+    if not _has_text(command):
+        command = defaults_op.get("seed_command")
+    if not _has_text(command):
+        return "missing", ("no seed/reset command declared "
+                           "(repos[R].operability.seed_command or "
+                           "defaults.operability.seed_command)")
+    command = command.strip()
+    script = None
+    for token in re.split(r"\s+", command):
+        bare = token.strip("\"'")
+        if "/" in bare or "\\" in bare or bare.lower().endswith(OPERABILITY_SCRIPT_EXT):
+            script = bare
+            break
+    if script is None:
+        # A command with no path in it (`make seed`, `npm run reset`) names a target this
+        # engine cannot resolve without running something. Declared is what is measurable.
+        return "ok", 'declared: "%s" (no script path to verify)' % command
+    for base, _where in bases:
+        if os.path.exists(os.path.join(base, script.replace("/", os.sep))):
+            return "ok", 'declared: "%s"' % command
+    return "missing", "script not found: %s" % script
+
+
+def _operability_report(ledger, repo, ledger_path):
+    """The four FACTS, with the base each was read from. Pure measurement: no persistence,
+    no exit code, no gate decision -- the caller owns all three."""
+    defaults = (ledger.get("config") or {}).get("defaults") or {}
+    op_cfg = defaults.get("operability") if isinstance(defaults.get("operability"), dict) else {}
+    bases = _op_bases(ledger, repo, ledger_path)
+    workflows, wf_base, wf_where = _op_workflows(bases)
+    checks = {}
+    if workflows:
+        ci_status, ci_detail = _op_ci(workflows, _op_test_command(ledger, repo))
+        rel_status, rel_detail = _op_release(workflows)
+        ci_source = "%s [%s]" % ("/".join(OPERABILITY_CI_DIR), wf_where)
+    else:
+        other = _op_other_ci(bases)
+        ci_source = None
+        if other:
+            ci_status = rel_status = "unknown"
+            ci_detail = rel_detail = ("unknown ci system: %s -- this reads GitHub Actions "
+                                      "only, so it neither certifies nor condemns it" % other)
+        else:
+            ci_status = rel_status = "missing"
+            ci_detail = rel_detail = ("no %s in the repo tree nor at the config root"
+                                      % "/".join(OPERABILITY_CI_DIR))
+    checks["ci"] = {"status": ci_status, "detail": ci_detail}
+    checks["release"] = {"status": rel_status, "detail": rel_detail}
+    rb_status, rb_detail, rb_path = _op_runbook(bases, op_cfg.get("runbook"))
+    checks["runbook"] = {"status": rb_status, "detail": rb_detail, "path": rb_path}
+    sd_status, sd_detail = _op_seed(ledger, repo, bases, op_cfg)
+    checks["seed"] = {"status": sd_status, "detail": sd_detail}
+    return {"repo": repo, "checks": checks, "ci_source": ci_source,
+            "bases": [{"path": b, "where": w} for b, w in bases]}
+
+
+def _operability_verdict(report, gate):
+    """(verdict, summary note). Three states, because there are three facts:
+      - every check `ok`                     -> pass (a gate that ran clean)
+      - any check `missing`                  -> fail under a declared gate, advisory without
+      - none missing, some `unknown`         -> advisory even under a declared gate
+    The third is the one worth spelling out: a pipeline this engine cannot read is UNMEASURED,
+    and recording UNMEASURED as `pass` would hand a declared gate a green nobody measured --
+    the false clean ADR-043 exists to refuse, arriving through a different door."""
+    statuses = [report["checks"][k]["status"] for k in OPERABILITY_CHECKS]
+    note = " · ".join("%s %s" % (k, report["checks"][k]["status"])
+                      for k in OPERABILITY_CHECKS)
+    if not gate:
+        return "advisory", note
+    if "missing" in statuses:
+        return "fail", note
+    if "unknown" in statuses:
+        return "advisory", note
+    return "pass", note
+
+
+def cmd_operability(args):
+    """Measure the operability of a repo: CI, release, RUNBOOK, seed (ADR-048).
+
+    Exit code is ALWAYS 0 for the check itself -- the gate decision belongs to the profile,
+    and it is enforced where every other FACT gate is enforced: the persisted record caps
+    readiness <=65 and blocks convergence when it is a `fail`."""
+    ledger = _load(args.ledger)
+    node = _repo_node(ledger, args.repo)
+    resolved, origin = _resolved_defaults(ledger.get("config") or {})
+    gate = bool(resolved.get("operability.gate"))
+    report = _operability_report(ledger, args.repo, args.ledger)
+    verdict, note = _operability_verdict(report, gate)
+    missing = [k for k in OPERABILITY_CHECKS
+               if report["checks"][k]["status"] == "missing"]
+    report.update({"gate": gate, "gate_origin": origin.get("operability.gate"),
+                   "verdict": verdict, "note": note, "missing": missing})
+
+    rec = _append_gate_record(ledger, node, args.repo, "gate:operability", args.iteration,
+                              verdict == "fail", len(missing) or 1, note,
+                              advisory=(verdict == "advisory"))
+    _save(args.ledger, ledger)
+    report["step"] = rec["n"]
+
+    if args.json:
+        print(json.dumps(report, indent=2, ensure_ascii=False))
+        sys.exit(0)
+    # "not declared" and "declared false" are DIFFERENT facts: the first is a project that
+    # never mentioned the knob, the second a human who turned the gate off on purpose. Saying
+    # "not declared" for both erased the decision (fresh review, 2.2.0).
+    gate_origin = origin.get("operability.gate")
+    gate_shown = ("declared" if gate
+                  else "declared false" if gate_origin == "override" else "not declared")
+    print("OPERABILITY %s (gate: %s, origin %s)" % (args.repo, gate_shown, gate_origin))
+    if report["ci_source"]:
+        print("  read: %s" % report["ci_source"])
+    for key in OPERABILITY_CHECKS:
+        c = report["checks"][key]
+        mark = {"ok": "ok", "missing": "!!", "unknown": "--"}.get(c["status"], "??")
+        detail = c["detail"]
+        print("  %s %s: %s%s" % (mark, key, c["status"],
+                                 (" (%s)" % detail) if detail else ""))
+    present = sum(1 for k in OPERABILITY_CHECKS
+                  if report["checks"][k]["status"] == "ok")
+    if verdict == "fail":
+        print("  -- %d of %d present -- FAIL: caps readiness <=65 and blocks convergence "
+              "until %s exist(s)" % (present, len(OPERABILITY_CHECKS), ", ".join(missing)))
+    elif verdict == "pass":
+        print("  -- %d of %d present -- PASS: the declared operability gate ran clean"
+              % (present, len(OPERABILITY_CHECKS)))
+    else:
+        print("  -- %d of %d present -- ADVISORY (measured, not gating): caps nothing, "
+              "blocks nothing%s" % (present, len(OPERABILITY_CHECKS),
+                                    ("; declare defaults.operability.gate: true (or a risk "
+                                     "profile C/D/E) to make it a gate" if not gate else
+                                     "; a check this engine cannot read is UNMEASURED, "
+                                     "never a green")))
+    sys.exit(0)
+
 
 # --------------------------------------------------------------------------- #
 # golden-coverage  (ADR-006: the golden<->source mapping, DERIVED BY MEASUREMENT)
@@ -7319,27 +8463,147 @@ def _render_lang_md(r, has_js=False):
 # --------------------------------------------------------------------------- #
 
 FACTS_FILE = "SYSTEM-FACTS.json"
+# The NAMESPACED name `install-uscha.py` writes the kit's version under, beside the installed
+# skills (2.2.0). It is not `VERSION`: that bare name is shared with whatever else the agent's
+# skills directory holds, and an installer that writes it owns a file it did not create.
+KIT_VERSION_COPY = ".uscha-kit-VERSION"
+
+
+def _kit_root():
+    """The kit directory this engine belongs to, or None.
+
+    By MARKER, not by fixed depth: the canonical engine sits 4 levels deep
+    (.claude/skills/uscha-devloop/) and the Codex twin 3 (skills/uscha-devloop/). A fixed
+    dirname walk made the twin silently derive the OUTER repo root -- version None,
+    0 skills, no error (fresh-review HIGH, reproduced by running both copies).
+
+    The marker is a VERSION file AND a skills tree beside it (2.2.0). VERSION alone stopped
+    being sufficient the moment `install-uscha.py` began dropping one beside the installed
+    skills so `doctor` could date them: that root carries a version and no kit, and answering
+    it here would make `facts` derive `0 skills` from a directory that never held any --
+    a manufactured fact, which is worse than the honest refusal this returns instead.
+    An engine that only needs the VERSION asks _engine_kit_version().
+
+    The walk starts at the engine's REALPATH: a `--mode link` install puts a link to the kit's
+    skill directory under the agent's skills root, and an abspath walk-up from there climbs the
+    agent's tree instead of the checkout the link points into (fresh review, 2.2.0). Same lesson
+    the Windows 8.3 gotcha teaches: resolve before you compare, resolve before you walk."""
+    cur = os.path.dirname(os.path.realpath(__file__))
+    for _ in range(6):
+        if (os.path.isfile(os.path.join(cur, "VERSION"))
+                and (os.path.isdir(os.path.join(cur, ".claude", "skills"))
+                     or os.path.isdir(os.path.join(cur, "skills")))):
+            return cur
+        nxt = os.path.dirname(cur)
+        if nxt == cur:
+            break
+        cur = nxt
+    return None
 
 
-def _derive_facts():
-    """Facts derived from the ARTIFACTS themselves, never from prose and never from greps
-    over documentation: the subcommand list comes from introspecting the REAL parser, the
-    skill list from the REAL kit tree, the version from the kit VERSION file. No timestamp
-    on purpose: regeneration over an unchanged repo must be byte-identical (AC-SF-01)."""
-    here = os.path.abspath(__file__)
-    # kit root by MARKER, not by fixed depth: the canonical engine sits 4 levels deep
-    # (.claude/skills/uscha-devloop/) and the Codex twin 3 (skills/uscha-devloop/). A fixed
-    # dirname walk made the twin silently derive the OUTER repo root -- version None,
-    # 0 skills, no error (fresh-review HIGH, reproduced by running both copies).
-    kit, cur = None, os.path.dirname(here)
+def _engine_kit_version():
+    """(version, where) for the kit THIS engine came from, or (None, [dirs it looked in]).
+
+    Which kit an installed skill came from is a different question from which kit tree this
+    engine sits in, and an INSTALLED engine has no kit tree at all: `install-uscha.py` copies
+    the kit's version beside the installed skills precisely so the question stays answerable
+    there -- from a checkout this walk lands on the kit root like _kit_root() does, and from an
+    install it lands on the install root.
+
+    THREE sources, in this order at every level (2.2.0, fresh review):
+
+    1. `.uscha-kit-VERSION` -- the NAMESPACED copy the installer writes. The copy used to be
+       called `VERSION`, a bare shared name dropped into directories the kit does not own
+       (`~/.claude/skills/`, `~/.cursor/skills/`): whatever else lived under that name was
+       overwritten by an install and deleted by an uninstall. The kit owns its prefix and
+       nothing else.
+    2. `VERSION` -- the KIT ROOT's own file, which is the checkout case and is never written by
+       an install any more. A foreign file under that name is read, not written: reading is what
+       this walk is for, and a wrong version is reported as a version, never as damage.
+    3. `uscha-install.json`'s `version` -- the install marker, already on the walk, so an
+       install whose copy was removed by hand still answers instead of going UNMEASURED.
+
+    The walk starts at the engine's REALPATH: under `--mode link` the installed skill directory
+    is a link into the kit checkout, and an abspath walk-up climbs the agent's tree rather than
+    the kit's -- so a link install could not resolve its own kit without the copy.
+
+    Never guesses: with no version anywhere it returns the directories it READ, so the report
+    can say where it looked instead of only that it failed."""
+    cur = os.path.dirname(os.path.realpath(__file__))
+    looked = []
     for _ in range(6):
-        if os.path.isfile(os.path.join(cur, "VERSION")):
-            kit = cur
-            break
+        looked.append(cur)
+        for name in (KIT_VERSION_COPY, "VERSION"):
+            try:
+                with open(os.path.join(cur, name), encoding="utf-8") as fh:
+                    return fh.read().strip().split()[-1], cur
+            except (OSError, IndexError):
+                pass
+        try:
+            with open(os.path.join(cur, "uscha-install.json"), encoding="utf-8") as fh:
+                declared = (json.load(fh) or {}).get("version")
+            if isinstance(declared, str) and declared.strip():
+                return declared.strip().split()[-1], cur
+        except (OSError, ValueError, AttributeError):
+            pass
         nxt = os.path.dirname(cur)
         if nxt == cur:
             break
         cur = nxt
+    return None, looked
+
+
+BENCH_DOC = "DIAMOND-BENCH.md"
+# One generated table row per archetype: `| crud-store | PASS | M1 12/12, ... |`. Anchored at the
+# line start and on the closing pipe so the per-entry prose below the table ("### guard -- PARTIAL")
+# cannot be counted twice.
+_BENCH_ROW = re.compile(r"^\|\s*([A-Za-z0-9][\w.-]*)\s*\|\s*(PASS|PARTIAL|FAIL|PENDING)\s*\|")
+
+
+def _derive_bench(kit):
+    """The Diamond Bench headline, COUNTED out of the bench's own generated report, or None.
+
+    `DIAMOND-BENCH.md` is written by `qa_ledger.py bench` over the committed fixture and carries
+    the "do not hand-edit" banner: every row in it is a measured run. Re-running the bench here
+    would be the honest derivation and is not affordable -- a full pass is ~650 child processes,
+    and `facts` runs on every suite, every deploy and twice per release. So the fact is counted
+    from the RECORDED verdicts, per archetype, never from the summary sentence beside them and
+    never from a number typed into a document.
+
+    The report lives at the REPO root, one level above the kit: an installed kit has no bench,
+    which is why this returns None instead of guessing. `--check` then reports any claim about it
+    as UNMEASURED rather than letting it pass unexamined."""
+    if not kit:
+        return None
+    for cand in (os.path.join(os.path.dirname(kit), BENCH_DOC),
+                 os.path.join(kit, BENCH_DOC)):
+        if not os.path.isfile(cand):
+            continue
+        try:
+            with open(cand, encoding="utf-8-sig") as fh:
+                body = fh.read()
+        except OSError:
+            continue
+        verdicts = []
+        for line in body.split("\n"):
+            m = _BENCH_ROW.match(line.strip())
+            if m:
+                verdicts.append(m.group(2))
+        if not verdicts:
+            continue
+        return {"entries": len(verdicts), "pass": verdicts.count("PASS"),
+                "partial": verdicts.count("PARTIAL"), "fail": verdicts.count("FAIL"),
+                "pending": verdicts.count("PENDING")}
+    return None
+
+
+def _derive_facts():
+    """Facts derived from the ARTIFACTS themselves, never from prose and never from greps
+    over documentation: the subcommand list comes from introspecting the REAL parser, the
+    skill list from the REAL kit tree, the version from the kit VERSION file, the Diamond
+    headline from the bench's own generated report. No timestamp on purpose: regeneration
+    over an unchanged repo must be byte-identical (AC-SF-01)."""
+    kit = _kit_root()
     if kit is None:
         print("[qa_ledger] facts: no VERSION file found walking up from the engine -- "
               "facts that cannot locate their own kit are not facts.", file=sys.stderr)
@@ -7356,14 +8620,24 @@ def _derive_facts():
             skills = sorted(d for d in os.listdir(sdir)
                             if os.path.isfile(os.path.join(sdir, d, "SKILL.md")))
             break
+    bench = _derive_bench(kit)
     return {
         "version": version,
         "subcommands": {"count": len(subs), "list": subs},
         "skills": {"count": len(skills), "list": skills},
+        # null, never a zero: an installed kit ships no bench report, and "0 PASS" would be a
+        # measured-looking answer to a question this tree cannot answer.
+        "diamond": bench,
         "_derivation": {
             "version": "uscha-kit/VERSION",
             "subcommands": "argparse introspection of build_parser()",
             "skills": "SKILL.md inventory under uscha-kit/.claude/skills/",
+            "diamond": ("verdict rows of DIAMOND-BENCH.md, the report `bench` generates over "
+                        "uscha-kit/tests/fixtures/diamond-bench (regenerate it with: qa_ledger.py "
+                        "bench --dir uscha-kit/tests/fixtures/diamond-bench --out "
+                        "DIAMOND-BENCH.md)" if bench else
+                        "UNMEASURED: no DIAMOND-BENCH.md beside the kit -- claims about the "
+                        "bench headline are reported as undecidable, never as green"),
             "omitted": "stack matrix and REAL/VISION registry: no mechanical "
                        "source exists yet -- omitted, not guessed (ADR-012)",
         },
@@ -7393,7 +8667,18 @@ _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+"
+_NUM = r"\b(\d+|" + _NUM_ALT + r")"
+# HTML splits a claim across elements: the homepage's stat tile reads
+# `<div class="v">8<small>/12</small></div><div class="k">archetypes regenerate</div>`, so the
+# count and the noun that gives it meaning are separated by markup rather than by a space. The
+# gap is therefore whitespace OR tags; `[^<>]` stops one tag from swallowing the rest of the
+# line, and the repetition is bounded so the gap can never run from one sentence into the next.
+_GAP = r"(?:\s|<[^<>]{0,80}>){0,8}"
+_ARCH = r"(?:archetypes?|arquetipos?)"
+# a claimed count that is NOT the one being rewritten (the other half of a verdict pair)
+_ANYNUM = r"(?:\d+|" + _NUM_ALT + r")"
+# what separates `8 PASS` from `4 PARTIAL`: a comma, a middle dot, a slash, spaces, markup
+_VSEP = r"[^A-Za-z0-9<>]{0,8}" + _GAP
 
 
 def _unspell(token):
@@ -7405,17 +8690,57 @@ _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", _COUNT + r"sub-?comm?ands", None),
-    ("subcommands.count", r"(\d+)\s+subcomandos", None),
+    # `_GAP` rather than a plain space since 2.2.0: the site's stat tiles put the count in one
+    # element and its noun in the next (`<div class="v">52</div><div class="k">engine
+    # subcommands</div>`), so a gate that demanded whitespace between them read the homepage's
+    # headline numbers as prose. It had `52 engine subcommands` and `9/12 archetypes` on one
+    # screen, both stale, both invisible to a green release.
+    ("subcommands.count", _NUM + _GAP + r"(?:engine\s+)?sub-?comm?ands", None),
+    ("subcommands.count", r"\b(\d+)" + _GAP + r"subcomandos", 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),
+    ("skills.count", _NUM + _GAP + r"(?:agent\s+)?skills", None),
+    # The Diamond Bench headline (2.2.0). The homepage said 9/12 for nine releases after ADR-042
+    # moved `transformer` to PARTIAL, because no gate could see the claim: the number sat in one
+    # HTML element and its noun in the next.
+    #
+    # Two shapes only, and both are narrow BY MEASUREMENT -- each wider draft was tried against
+    # the gated set first and rejected by what it caught:
+    #
+    #   `<n>/12 archetypes`, `<n> of 12 archetypes`, `<n> de 12 arquetipos` -- the count must be
+    #   followed, across markup but never across prose, by the noun it counts, and the
+    #   denominator must be the DIGITS 12. That is what keeps the repo's own historical sentence
+    #   ("It was 9 of 12 until ADR-042 moved transformer") and the paper's "ten of twelve
+    #   archetypes" out of a writer that would have silently rewritten both.
+    #
+    #   `<n> PASS <sep> <n> PARTIAL` as ONE shape, verdicts case-sensitive (`(?-i:...)` against
+    #   the module-wide re.I). Reading the two numbers independently caught the paper's snapshot
+    #   of the July-August arm -- "nine archetypes PASS ... three PARTIAL", a sentence about a
+    #   different experiment -- and would have offered to rewrite it. The bench headline always
+    #   writes the pair together, so adjacency is both narrower and closer to the real claim.
+    #
+    # `<n> archetypes` alone is deliberately NOT a claim: across the gated set it names subsets
+    # far more often than the bench ("five archetypes", "two archetypes have no second run"), so
+    # the entries count stays a derived fact with no recognised published shape.
+    ("diamond.pass", _NUM + _GAP + r"(?:/|of|de)" + _GAP + r"12" + _GAP + _ARCH, None),
+    ("diamond.pass", _NUM + _GAP + r"(?-i:PASS)" + _VSEP + _ANYNUM + _GAP + r"(?-i:PARTIAL)",
+     None),
+    ("diamond.partial",
+     r"\b" + _ANYNUM + _GAP + r"(?-i:PASS)" + _VSEP + _NUM + _GAP + r"(?-i:PARTIAL)", None),
 )
 
 
 def _fact_value(facts, dotted):
+    """The derived fact behind a claim key, or None when THIS tree cannot derive it.
+
+    Not every fact exists everywhere: an installed kit has no `DIAMOND-BENCH.md`, so
+    `diamond.*` is null there. None is the honest answer and both consumers act on it --
+    `--write` leaves the claim alone (there is nothing to write it to) and `--check` reports it
+    as UNMEASURED. Neither treats an underivable fact as agreement."""
     cur = facts
     for part in dotted.split("."):
+        if not isinstance(cur, dict) or cur.get(part) is None:
+            return None
         cur = cur[part]
     return str(cur)
 
@@ -7506,7 +8831,10 @@ def _write_claims(facts, paths):
             # 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:
+                if actual is None or _claim_norm(token) == actual:
+                    # None = this tree cannot derive the fact; there is nothing to rewrite the
+                    # claim TO, and inventing one would be the opposite of the gate. The --check
+                    # that follows reports it as UNMEASURED.
                     continue
                 line = line[:start] + _claim_rewrite(token, actual) + line[end:]
                 n += 1
@@ -7579,7 +8907,11 @@ def cmd_facts(args):
                 # 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:
+                    if actual is None:
+                        problems.append((path, n, key, claimed,
+                                         "UNMEASURED -- this tree derives no such fact "
+                                         "(see SYSTEM-FACTS _derivation)"))
+                    elif _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
@@ -7619,9 +8951,12 @@ def cmd_facts(args):
     body = json.dumps(facts, indent=2, ensure_ascii=False, sort_keys=True) + "\n"
     with open(args.out, "w", encoding="utf-8", newline="\n") as fh:
         fh.write(body)
-    print("FACTS -> %s: version %s · %d subcommands · %d skills"
+    dia = facts.get("diamond")
+    print("FACTS -> %s: version %s · %d subcommands · %d skills · diamond %s"
           % (args.out, facts["version"], facts["subcommands"]["count"],
-             facts["skills"]["count"]))
+             facts["skills"]["count"],
+             ("%d PASS · %d PARTIAL of %d" % (dia["pass"], dia["partial"], dia["entries"])
+              if dia else "UNMEASURED (no %s beside the kit)" % BENCH_DOC)))
 
 
 
@@ -8399,17 +9734,21 @@ def cmd_dashboard(args):
     subscores = [{"k": "coverage",
                   "val": round(covp) if isinstance(covp, (int, float)) else None,
                   "bd": (f"{round(covp)}%" if isinstance(covp, (int, float)) else None)}]
-    gate_block, gate_note = {}, {}
+    gate_block, gate_note, gate_adv = {}, {}, {}
     for g in rd.get("gates", []):
         kind = (g.get("tool") or "").replace("gate:", "")
         key = "golden" if kind.startswith("golden") else kind
         gate_block[key] = gate_block.get(key, False) or bool(g.get("blocking"))
+        gate_adv[key] = gate_adv.get(key, False) or bool(g.get("advisory"))
         if g.get("note") and key not in gate_note:
             gate_note[key] = g.get("note")
     for key in ("simplicity", "waste", "golden"):
         if key in gate_block:
+            # ADR-043: a non-blocking ADVISORY is not "OK" — OK means a declared gate ran clean.
+            _bd = ("FAIL" if gate_block[key]
+                   else "ADVISORY" if gate_adv.get(key) else "OK")
             subscores.append({"k": key, "val": None,
-                              "bd": gate_note.get(key) or ("FAIL" if gate_block[key] else "OK")})
+                              "bd": gate_note.get(key) or _bd})
 
     # loops: iters + estado por repo (escalated > converged > active). max sin fuente.
     # El estado se deriva ENTERO con _derive_phase (kit 1.48.1) — la MISMA funcion que
@@ -9033,6 +10372,10 @@ def _top_events(ledger, limit=TOP_EVENTS_TAIL):
                 gated = it.get("gated_reported")
                 if kind == "gate-not-run":
                     tail = "not run — nobody measured it"
+                elif kind == "static-gate" and it.get("advisory"):
+                    # ADR-043: measured but not gating. `info` (never green, never red) is the
+                    # honest level -- rendering it `pass`/`clean` is the false clean again.
+                    level, tail = "info", "advisory — measured, not gating"
                 elif kind == "static-gate" and isinstance(gated, int):
                     level = "fail" if gated >= 1 else "pass"
                     tail = "%d gated finding(s)" % gated if gated else "clean"
@@ -9583,10 +10926,33 @@ def cmd_readiness(args):
     # ingeridos (y 0 rojos). El checkbox es RELATO; el testcase es HECHO.
     ac_ids = [i for i in acc_items if i["id"]]
     ac_tags, stale_reports = _sum_ac_tags(ledger)
+    # ADR-046: a green corpus run is the OTHER way a criterion closes measured. Greenfield has
+    # no old code to characterize, so for the criteria that are about real-world input the only
+    # field evidence there can be is a corpus run over real inputs -- and it closes exactly like
+    # a green testcase does, with the same fail-closed rule below. `corpus_red` is a FAILING
+    # tagged run -- evidence AGAINST, in ADR-046's own words -- and it vetoes like a red
+    # testcase; an ADVISORY run is neither and does neither.
+    corpus_closed, corpus_red = _corpus_ac_verdicts(ledger)
+    # ADR-047: and a green SMOKE check is the third way. "the jar served /admin" used to
+    # arrive as a sub-agent's sentence; now it arrives as a check in a report the engine
+    # READ, and a check named "AC-28 ..." closes AC-28 exactly as a green testcase named
+    # "AC-28 ..." does. `smoke_red` is a FAILED tagged check -- red evidence, and it vetoes
+    # like a red testcase.
+    smoke_closed, smoke_red = _smoke_ac_verdicts(ledger)
 
     def _ac_closed(cid):
         d = ac_tags.get(cid)
-        return bool(d and d["green"] >= 1 and d["red"] == 0)
+        # fail-closed FIRST, always: red evidence of ANY kind outranks every green one,
+        # because the cheapest way to fake a closed criterion is to add a green beside a red.
+        if d and d["red"]:
+            return False          # red evidence vetoes, whatever else says (fail-closed)
+        if cid in smoke_red:
+            return False          # a FAILED tagged smoke check is red evidence too
+        if cid in corpus_red:
+            return False          # and so is a FAILING tagged corpus run (ADR-046)
+        if d and d["green"] >= 1:
+            return True
+        return cid in corpus_closed or cid in smoke_closed
 
     # IDs duplicados (ACCEPTANCE mal numerado) cuentan UNA sola vez — si no,
     # un solo test verde cierra "medido" tantos criterios como copias del ID.
@@ -9832,6 +11198,17 @@ def cmd_readiness(args):
                                         if (acc_traceable and total) else None),
                        "narrated_only": narrated_only,
                        "measured_unchecked": measured_unchecked,
+                       # ADR-046: WHICH ids a green corpus run closed, so a reader can tell
+                       # field evidence from suite evidence instead of inferring it -- and
+                       # `corpus_vetoed` for the ids a FAILING run holds open, the half a
+                       # reader cannot infer from the closed list.
+                       "corpus_closed": sorted(corpus_closed, key=_top_ac_key),
+                       "corpus_vetoed": sorted(corpus_red, key=_top_ac_key),
+                       # ADR-047: the same for the ids a green smoke check closed -- and
+                       # `smoke_vetoed` for the ids a FAILED one holds open, which is the
+                       # half a reader cannot infer from the closed list.
+                       "smoke_closed": sorted(smoke_closed, key=_top_ac_key),
+                       "smoke_vetoed": sorted(smoke_red, key=_top_ac_key),
                        "stale_reports": stale_reports},
         "facts": {"coverage_pct": round(agg_cov_pct, 2), "coverage_threshold": threshold,
                   "gated_open": total_open, "severity": agg_sev,
@@ -9854,9 +11231,32 @@ def cmd_readiness(args):
     # lifecycle (ADR-040): advisory, and CONDITIONAL like fast_path/spec_drift -- a project
     # that declares no lifecycle: block keeps the exact prior payload and the exact prior
     # text. Speaking only when it matters is the anti-ceremony rule applied to itself.
-    _lc = _lifecycle_for(os.path.dirname(os.path.abspath(args.ledger)) or os.getcwd())
+    _ready_root = os.path.dirname(os.path.abspath(args.ledger)) or os.getcwd()
+    _lc = _lifecycle_for(_ready_root)
     if _lc["declared"]:
         out["lifecycle"] = _lc
+    # agent-origin (ADR-044): advisory and CONDITIONAL for the same reason -- a project
+    # that tags nothing keeps the exact prior payload and the exact prior text. It never
+    # enters the gates line, never caps the score, never blocks convergence.
+    # field truth (ADR-046): advisory and CONDITIONAL for the same reason -- a project that
+    # declares no corpus and ran none keeps the exact prior payload and the exact prior text.
+    # The `field` DIMENSION and its weight are deliberately NOT here: adding one moves every
+    # existing project's score, and that is its own ADR.
+    _field = _corpus_field(ledger)
+    if _field:
+        out["field"] = _field
+    # smoke (ADR-047): conditional for the same reason. A failing smoke ALREADY blocks
+    # through its `gate:smoke` record; this block adds what the rollup cannot carry --
+    # which checks ran, and which of them answered wrong.
+    _smoke = _smoke_report(ledger)
+    if _smoke:
+        out["smoke"] = _smoke
+    _ao = _agent_origin_report(_ready_root,
+                               acc_path if acc_found else None)
+    if _ao["n_unconfirmed"] or _ao["confirmed"]:
+        out["agent_origin"] = {"unconfirmed": _ao["unconfirmed"],
+                               "confirmed": _ao["confirmed"],
+                               "files_scanned": _ao["files_scanned"]}
     if args.json:
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return
@@ -9890,8 +11290,9 @@ def cmd_readiness(args):
               "or the explicit weight in config.defaults.readiness_weights")
     if narrated_only:
         print(f"  ! narrated-only: {', '.join(narrated_only)} — checkbox ticked "
-              f"WITHOUT a green 'AC-n' testcase in the reports (measured beats "
-              f"narrated: does NOT close)")
+              f"WITHOUT a green 'AC-n' testcase in the reports, without a green "
+              f"corpus run carrying it and without a green 'AC-n' smoke check "
+              f"(measured beats narrated: does NOT close)")
     if measured_unchecked:
         print(f"  · measured but unticked: {', '.join(measured_unchecked)} — there is "
               f"a green testcase; tick the checkbox if the criterion is done")
@@ -9957,13 +11358,52 @@ def cmd_readiness(args):
     gate_roll = out["gates"]
     if gate_roll:
         blocking = [g for g in gate_roll if g["blocking"]]
-        n_ok = len(gate_roll) - len(blocking)
+        # ADR-043: an advisory NEVER joins the ok count. "3 ok" must mean three gates ran and
+        # came back clean; folding a check the project never declared as a gate into that number
+        # is the false clean the advisory verdict exists to refuse. The segment is conditional,
+        # so a ledger with no advisory record prints exactly what it printed before.
+        advisory = [g for g in gate_roll if g.get("advisory") and not g["blocking"]]
+        n_ok = len(gate_roll) - len(blocking) - len(advisory)
+        adv_str = (f" · {len(advisory)} advisory ("
+                   + ", ".join(f"{g['repo']}/{g['tool']}" for g in advisory) + ")"
+                   if advisory else "")
         hint = "" if args.verbose else "   (readiness --verbose for the detail)"
         if blocking:
             names = ", ".join(f"{g['repo']}/{g['tool']}" for g in blocking)
-            print(f"--- gates: {n_ok} ok · {len(blocking)} blocking ({names}){hint}")
+            print(f"--- gates: {n_ok} ok{adv_str} · {len(blocking)} blocking ({names}){hint}")
         else:
-            print(f"--- gates: {n_ok} ok, none blocking{hint}")
+            print(f"--- gates: {n_ok} ok{adv_str}, none blocking{hint}")
+    # ADR-046: the FIELD line, one per repo that declares a corpus or has run one. A failing
+    # corpus ALREADY appears in the gates rollup above (it is a gate:corpus record like any
+    # other); this line adds the number the rollup cannot carry -- what percentage of REAL
+    # inputs the system gets right, against which declared budget.
+    for _rname in sorted(_field):
+        print(_corpus_field_line(_rname, _field[_rname]))
+    # ADR-047: the SMOKE line, one per repo that ingested a report. Like the field line it
+    # adds the numbers the gates rollup cannot carry -- how many checks ran, how many
+    # answered wrong, and WHICH ones, so the failure is named instead of counted.
+    for _rname in sorted(_smoke):
+        print(_smoke_line(_rname, _smoke[_rname]))
+    # ADR-044: its OWN line, deliberately outside the gates rollup. An unconfirmed
+    # agent-origin item is a decision still owed to the human, not a gate that ran --
+    # folding it into "N ok" or into "N blocking" would be the false clean ADR-043
+    # refused, in the other direction. It caps nothing and blocks nothing.
+    if _ao["n_unconfirmed"]:
+        print(f"--- origin: {_ao['n_unconfirmed']} agent-origin item(s) unconfirmed"
+              f"   (spec-check names them)")
+    # ADR-048: operability gets its own line, CONDITIONAL on a record existing -- a ledger that
+    # never ran the check prints exactly what it printed before. The gates rollup above already
+    # counts the record correctly (ok / blocking / advisory); what it cannot say is WHICH of the
+    # four is the one to go and build, and "1 blocking (backend-api/gate:operability)" is
+    # precisely the message that sends a human to read the source.
+    _ops = [(rname, _latest_static_by_tool(rnode).get("gate:operability"))
+            for rname, rnode in ledger["repos"].items()]
+    _ops = [(rname, rec) for rname, rec in _ops if rec and rec.get("note")]
+    for _rname, _op in _ops:
+        _label = "operability" if len(_ops) == 1 else "operability %s" % _rname
+        _state = (" (advisory)" if _op.get("advisory")
+                  else " (gate: FAIL)" if (_op.get("gated_reported") or 0) else " (gate)")
+        print(f"--- {_label}: {_op['note']}{_state}")
     if not args.verbose:
         return
     print("--- dimensions (weight | raw | contribution) ---")
@@ -10023,6 +11463,14 @@ DEFAULT_COVERAGE_TOLERANCE = 5.0  # pct points the rebuilt coverage may drop
 # abstraction is INTENTIONALLY not weighted: the "new types" regex is a prose/AST proxy
 # that false-positives on Java records/DTOs, so it must not gate the band. It stays as an
 # advisory metric + flag only (distilled: hard caps gate, guessy proxies advise).
+#
+# ADVISORY BY DEFAULT (kit 2.1.0, ADR-043). Every budget below is the KIT'S OPINION, not the
+# project's requirement, and an opinion that exits 1 is a gate nobody declared. Until a project
+# declares at least one numeric budget AND `defaults.simplicity.gate: true`, the verdict is
+# reported and the exit code is 0. This is NOT INV-ADVISORY-01 (that invariant quarantines
+# LLM-class JUDGMENT; these proxies are deterministic and may gate the moment a human says so)
+# -- it is the provenance rule of 1.17.0 applied to an exit code: a default is an opinion, and
+# only a declaration is a requirement.
 SIMPLICITY_WEIGHTS = {
     "diff_size": 35, "nesting": 30, "net_growth": 20, "fan_out": 8, "blob": 7,
 }
@@ -10037,6 +11485,17 @@ SIMPLICITY_DEFAULTS = {
     "max_abstraction_density": 3.0,   # new *types* per 100 added LOC
     "indent_width": 4,
 }
+# Keys under defaults.simplicity that are NOT budgets, so declaring one never satisfies the
+# "a gate needs a budget" rule: `indent_width` is a PARSING parameter and `gate` is the switch
+# itself. `gate: true` with nothing but these declared is a refusal, not a gate (ADR-043).
+_SIMPLICITY_NON_BUDGET = ("indent_width", "gate")
+# What `max_nesting` actually measures, said once and reused by every surface that prints it.
+# It is INDENTATION DEPTH over added lines, not AST nesting: a wrapped call argument, JSX, a
+# multi-line Java string or any deep continuation raises it without any control flow existing.
+# The kit does NOT make it language-aware (that needs a parser per stack, which this stdlib
+# engine will not have) -- it names the proxy instead, so a reader can discount it.
+_NESTING_PROXY_NOTE = ("indentation depth over added lines, NOT AST nesting -- continuation "
+                       "lines, JSX and multi-line literals inflate it")
 # code files only — docs, config, resources and generated trees are noise for a
 # code-simplicity gate. Broader than SOURCE_EXT (which is repo-typed for rebuild).
 _SIMPLICITY_CODE_EXT = {
@@ -10235,18 +11694,25 @@ def _rebuild_compare(args):
 # --------------------------------------------------------------------------- #
 # simplicity-check  (the "Reduce" gate)
 # --------------------------------------------------------------------------- #
-def _read_diff(args):
-    """Unified-diff text from --diff, --from-git, or stdin."""
+def _read_diff(args, detect_renames=False):
+    """Unified-diff text from --diff, --from-git, or stdin.
+
+    detect_renames (2.2.0) adds `-M` to the `--from-git` command so git reports a rename AS a
+    rename, whatever the caller's `diff.renames` config says. It is OPT-IN because the other
+    readers of this helper count LINES (simplicity, waste, regression): collapsing a rename into
+    a header would silently change the numbers they have been measuring for releases. gate-check
+    is the caller that needs it -- a rename read as a delete/add pair is what made
+    `git mv tests/a_test.py tests/b_test.py` block as a deleted test in the field."""
     if getattr(args, "diff", None):
         with open(args.diff, "r", encoding="utf-8", errors="replace") as fh:
             return fh.read()
     if getattr(args, "from_git", False):
         import subprocess
         base = args.base or "HEAD"
+        cmd = ["git", "diff", "--unified=0"] + (["-M"] if detect_renames else []) + [base]
         try:
             return subprocess.run(
-                ["git", "diff", "--unified=0", base],
-                check=True, capture_output=True, text=True,
+                cmd, check=True, capture_output=True, text=True,
                 encoding="utf-8", errors="replace").stdout
         except Exception as exc:  # noqa: BLE001
             print(f"[qa_ledger] git diff failed: {exc}", file=sys.stderr)
@@ -10449,8 +11915,9 @@ def _simplicity_score(m, b):
 def _simplicity_flags(m, b):
     f = []
     if m["max_nesting"] > b["max_nesting_depth"]:
-        f.append(f"nesting {m['max_nesting']} > {b['max_nesting_depth']} — "
-                 f"aplanar: guard clauses / extraer función (CWE-1124)")
+        f.append(f"max_nesting (indentation proxy) {m['max_nesting']} > "
+                 f"{b['max_nesting_depth']} — aplanar: guard clauses / extraer función "
+                 f"(CWE-1124). Proxy: {_NESTING_PROXY_NOTE}")
     if m["new_abstractions"] > b["max_new_abstractions"]:
         f.append(f"{m['new_abstractions']} tipos/capas nuevos > "
                  f"{b['max_new_abstractions']} — ¿todos pedidos? "
@@ -10476,10 +11943,12 @@ def _simplicity_flags(m, b):
 def cmd_simplicity_check(args):
     b = dict(SIMPLICITY_DEFAULTS)
     declared = set()   # presupuestos declarados por el humano (config o CLI)
+    gate = False       # ADR-043: solo lo enciende una DECLARACION, nunca un default
     if args.config and os.path.exists(args.config):
         cfg = _load(args.config).get("defaults", {}).get("simplicity", {})
         b.update({k: cfg[k] for k in b if k in cfg})
-        declared |= {k for k in b if k in cfg and k != "indent_width"}
+        declared |= {k for k in b if k in cfg and k not in _SIMPLICITY_NON_BUDGET}
+        gate = bool(cfg.get("gate"))
     for k in ("max_lines_added", "max_net_lines", "max_files_changed",
               "max_nesting_depth", "max_hunk_added", "max_new_abstractions",
               "indent_width"):
@@ -10491,34 +11960,55 @@ def cmd_simplicity_check(args):
     if args.max_abstraction_density is not None:
         b["max_abstraction_density"] = args.max_abstraction_density
         declared.add("max_abstraction_density")
+    if getattr(args, "gate", False):
+        gate = True
+    # A gate with no budget is not a gate: it is the kit's opinion wearing an exit code, which
+    # is exactly the defect ADR-043 exists to remove. Refuse BEFORE reading the diff -- a
+    # misconfigured gate must not produce a score anyone could quote.
+    if gate and not declared:
+        print("[qa_ledger] invalid config: defaults.simplicity.gate is true (or --gate was "
+              "passed) but no simplicity budget is declared — a gate with no budget is not a "
+              "gate, only the kit's opinion with an exit code. Declare at least one of "
+              "max_lines_added, max_net_lines, max_files_changed, max_nesting_depth, "
+              "max_hunk_added, max_new_abstractions, max_abstraction_density in "
+              "defaults.simplicity (or pass the matching --max-... flag), or set gate to false.",
+              file=sys.stderr)
+        sys.exit(2)
+    mode = "gate" if gate else "advisory"
 
     m = _simplicity_metrics(_read_diff(args), b["indent_width"])
     score, dims = _simplicity_score(m, b)
     verdict = _simplicity_band(score)
     flags = _simplicity_flags(m, b)
+    exit_code = 1 if (verdict == "OVERBUILT" and gate) else 0
 
-    out = {"score": score, "verdict": verdict, "weights": SIMPLICITY_WEIGHTS,
+    out = {"score": score, "verdict": verdict, "mode": mode, "gate": gate,
+           "weights": SIMPLICITY_WEIGHTS,
            "dimensions": {k: round(v, 3) for k, v in dims.items()},
-           "metrics": m, "budgets": b, "budgets_declared": sorted(declared),
+           "metrics": m, "metrics_notes": {"max_nesting": _NESTING_PROXY_NOTE},
+           "budgets": b, "budgets_declared": sorted(declared),
            "flags": flags}
     if args.json:
         print(json.dumps(out, indent=2, ensure_ascii=False))
-        sys.exit(0 if verdict != "OVERBUILT" else 1)
+        sys.exit(exit_code)
 
-    print(f"SIMPLICITY: {score}/100 — {verdict}")
+    mode_str = ("declared gate" if gate else
+                "advisory (declare budgets + defaults.simplicity.gate to make it block)")
+    print(f"SIMPLICITY: {score}/100 — {verdict}  ({mode_str})")
     print("--- metrics (value / budget · * = declared by the human) ---")
     rows = [
         ("lines_added", m["lines_added"], b["max_lines_added"], "max_lines_added"),
         ("net_lines", m["net_lines"], b["max_net_lines"], "max_net_lines"),
         ("files_changed", m["files_changed"], b["max_files_changed"], "max_files_changed"),
-        ("max_nesting", m["max_nesting"], b["max_nesting_depth"], "max_nesting_depth"),
+        ("max_nesting (indentation proxy)", m["max_nesting"], b["max_nesting_depth"], "max_nesting_depth"),
         ("new_abstractions", m["new_abstractions"], b["max_new_abstractions"], "max_new_abstractions"),
         ("abstraction/100", m["abstraction_density"], b["max_abstraction_density"], "max_abstraction_density"),
         ("max_hunk_added", m["max_hunk_added"], b["max_hunk_added"], "max_hunk_added"),
     ]
     for name, val, bud, key in rows:
         mark = "*" if key in declared else ""
-        print(f"  {name:17s} {str(val):>7s} / {bud}{mark}")
+        print(f"  {name:31s} {str(val):>7s} / {bud}{mark}")
+    print(f"  (max_nesting is a PROXY: {_NESTING_PROXY_NOTE})")
     if not declared:
         print("  (every budget is a kit default — an opinion, not a "
               "requirement: declare yours in config.defaults.simplicity)")
@@ -10535,7 +12025,11 @@ def cmd_simplicity_check(args):
             print(f"  ! {fl}")
     else:
         print("  within budget — nothing to cut")
-    sys.exit(0 if verdict != "OVERBUILT" else 1)
+    if verdict == "OVERBUILT" and not gate:
+        print("--- advisory: OVERBUILT is REPORTED, not enforced (exit 0). Cut what is cheap, "
+              "say so in the PR body, and do not let it block the loop. To make it block, "
+              "declare your budgets AND defaults.simplicity.gate: true ---")
+    sys.exit(exit_code)
 
 
 # --------------------------------------------------------------------------- #
@@ -10978,8 +12472,125 @@ def _gc_new_dep(path, body):
     return bool(rx.search(body)) if rx else False
 
 
+def _gc_moves(diff):
+    """Renames read as MOVES, never as deletions (2.2.0 field fix).
+
+    `git mv tests/a_test.py tests/b_test.py` used to be reported as a deleted test -- a BLOCKER
+    and exit 1 for a change that deleted nothing. A rename reaches this parser in one of two
+    shapes, and both are read here:
+
+      * git's own `rename from` / `rename to` headers, present when the producer detected
+        renames (`--from-git` now forces `-M`, so the caller's `diff.renames` config can no
+        longer hide one); and
+      * an EXACT delete/add pair -- the same file content leaving one path and arriving at
+        another inside the same diff. That is what a producer with rename detection OFF emits,
+        and it is the shape that actually blocked in the field.
+
+    Returns (moves, paired). `moves` is the informational report. `paired` holds the paths of
+    the exact pairs ONLY: their hunks say nothing about the change and are skipped. A rename
+    WITH edits keeps its hunks, because moving a file is not a deletion but deleting a test out
+    of a moved file still is -- and that verdict must not change.
+
+    The pairing is deliberately EXACT and one-to-one: same content, one file losing it, one file
+    gaining it. Two deleted files with identical bodies are ambiguous, so neither is paired --
+    guessing which moved where would be inventing a fact to clear a gate, which is the one thing
+    this gate exists to refuse."""
+    moves = []
+    deleted, added = {}, {}      # path -> tuple of line bodies
+    path = None                  # the whole-file side currently being collected
+    side = None                  # "-" while inside a deletion, "+" inside an addition
+    bodies = []
+    minus_path = None
+
+    def _flush():
+        if path is not None and bodies:
+            (deleted if side == "-" else added)[path] = tuple(bodies)
+
+    for raw in diff.splitlines():
+        if raw.startswith("diff --git"):
+            _flush()
+            path, side, bodies, minus_path = None, None, [], None
+            continue
+        if raw.startswith("rename from "):
+            minus_path = raw[len("rename from "):].strip()
+            continue
+        if raw.startswith("rename to "):
+            if minus_path:
+                moves.append("%s -> %s" % (minus_path, raw[len("rename to "):].strip()))
+            minus_path = None
+            continue
+        if raw.startswith("--- "):
+            p = raw[4:].strip().split("\t")[0]
+            if p == "/dev/null":
+                side = "+"
+            else:
+                minus_path = p[2:] if p[:2] in ("a/", "b/") else p
+            continue
+        if raw.startswith("+++ "):
+            p = raw[4:].strip().split("\t")[0]
+            if p == "/dev/null":
+                side, path = "-", minus_path
+            elif side == "+":
+                path = p[2:] if p[:2] in ("a/", "b/") else p
+            else:
+                path, side = None, None      # an ordinary edit: neither half of a move
+            bodies = []
+            continue
+        if path is not None and side and raw.startswith(side):
+            bodies.append(raw[1:])
+    _flush()
+
+    paired = set()
+    for dpath, content in deleted.items():
+        hits = [a for a, c in added.items() if c == content]
+        if len(hits) != 1:
+            continue
+        if sum(1 for c in deleted.values() if c == content) != 1:
+            continue
+        moves.append("%s -> %s" % (dpath, hits[0]))
+        paired.add(dpath)
+        paired.add(hits[0])
+    return sorted(set(moves)), paired
+
+
+def _gc_scope(args, ledger):
+    """`--repo R` SCOPES the diff to the files under repos[R].path (2.2.0 field fix).
+
+    In a monorepo one `git diff` carries every repo's hunks, and gate-check reported all of them
+    under whichever repo was named: a fact about someone ELSE's code, attributed to yours, with
+    your exit code behind it. Returns (base, scope) as absolute directories, or None when there
+    is nothing to scope by (no --repo, or a scope that is the whole tree).
+
+    realpath on BOTH sides before comparing. On Windows a path under a username longer than 8
+    characters comes back short-formed (`RUNNER~1`) from one API and long-formed from another,
+    and a file INSIDE the tree is then judged outside it -- the CI-only failure this repo has
+    already paid for once. The scope directory is realpath'd; the diff path is joined onto an
+    already-realpath'd base rather than realpath'd itself, because a DELETED file no longer
+    exists and would resolve inconsistently."""
+    if ledger is None or not getattr(args, "repo", None):
+        return None
+    base = os.path.realpath(os.path.dirname(os.path.abspath(args.ledger)) or ".")
+    scope = os.path.realpath(os.path.join(base, _scope_path(ledger, args.repo)))
+    return None if scope == base else (base, scope)
+
+
+def _gc_in_scope(path, scope):
+    if scope is None:
+        return True
+    base, root = scope
+    full = os.path.normpath(os.path.join(base, path.replace("/", os.sep)))
+    return full == root or full.startswith(root + os.sep)
+
+
 def cmd_gate_check(args):
-    diff = _read_diff(args)
+    # --repo now does TWO things, and both need the ledger: it scopes the diff to that repo's
+    # path (_gc_scope) and it adds the measured snapshot cross-check below. Loading it here
+    # keeps the existing behaviour of an unreadable ledger or an unknown repo name exiting 2
+    # rather than being scoped to nothing in silence.
+    ledger = _load(args.ledger) if getattr(args, "repo", None) else None
+    scope = _gc_scope(args, ledger)
+    diff = _read_diff(args, detect_renames=True)
+    moves, paired = _gc_moves(diff)
     removed_tests, disabled_tests, suppressions, thresholds = [], [], [], []
     secrets, secret_literals, scrub_edits, new_deps = [], [], [], []
     assertions_removed = 0
@@ -11010,12 +12621,16 @@ def cmd_gate_check(args):
                     path = minus_path
                 else:
                     path = p[2:] if p[:2] in ("a/", "b/") else p
-                    if _GC_KEYFILE.search(path):
-                        secrets.append(f"{path}: contenedor de claves agregado/modificado")
+                if path is not None and (path in paired or not _gc_in_scope(path, scope)):
+                    # a MOVED half (one side of an exact delete/add pair) and a file outside
+                    # --repo's scope are not this run's business: their hunks are skipped whole.
+                    path = None
+                elif path is not None and p != "/dev/null" and _GC_KEYFILE.search(path):
+                    secrets.append(f"{path}: contenedor de claves agregado/modificado")
             elif raw.startswith("Binary files "):
                 # los .p12/.jks binarios no traen +++ — el lado b/ vive en esta linea
                 m = re.search(r" and b/(.+) differ$", raw)
-                if m and _GC_KEYFILE.search(m.group(1)):
+                if m and _GC_KEYFILE.search(m.group(1)) and _gc_in_scope(m.group(1), scope):
                     secrets.append(f"{m.group(1)}: contenedor de claves agregado/modificado (binario)")
             continue
         if not path:
@@ -11076,9 +12691,8 @@ def cmd_gate_check(args):
     # optional MEASURED cross-check (heuristic-independent): with --repo, compare the
     # last two snapshots' executed-test totals — a drop is a fact no regex can miss.
     test_count_drop = None
-    if getattr(args, "repo", None):
+    if ledger is not None:
         try:
-            ledger = _load(args.ledger)
             node = _repo_node(ledger, args.repo)
             snaps = node.get("snapshots", [])
             if len(snaps) >= 2:
@@ -11112,10 +12726,15 @@ def cmd_gate_check(args):
             "new_dependencies": sorted(set(new_deps)),
             "assertions_removed": assertions_removed,
             "test_count_drop": test_count_drop,
+            # informational, and deliberately OUTSIDE hard/soft: a move is neither a finding
+            # nor an absolution, it is the reason a deletion is not being reported.
+            "moved": moves,
+            "scope": (os.path.basename(scope[1]) if scope else None),
         }, indent=2, ensure_ascii=False))
         sys.exit(1 if blocker else 0)
 
-    print(f"GATE-INTEGRITY: {verdict}")
+    print(f"GATE-INTEGRITY: {verdict}"
+          + (f" (scoped to {args.repo})" if scope else ""))
 
     def _show(label, items):
         if items:
@@ -11137,6 +12756,10 @@ def cmd_gate_check(args):
         print(f"  ~ asserts removed from tests: {assertions_removed} (review)")
     if test_count_drop:
         print(f"  ~ executed-test count dropped: {test_count_drop} (measured in snapshots — review)")
+    if moves:
+        tail = " ..." if len(moves) > 5 else ""
+        print(f"  . files moved: {len(moves)} — {'; '.join(moves[:5])}{tail} "
+              f"(informational: a rename is not a deletion)")
     if verdict == "CLEAN":
         print("  the change does not weaken the measuring apparatus")
     elif not blocker:
@@ -11529,6 +13152,142 @@ def _lifecycle_for(root, adr_dir=None, spec_text=None, fallback=True):
     return _lifecycle_report(adr_dir or os.path.join(root, "docs", "adr"), spec_text)
 
 
+# --------------------------------------------------------------------------- #
+# agent-origin markers (ADR-044): the agent asks for DECISIONS, never for INFORMATION
+# --------------------------------------------------------------------------- #
+# A decision the human never made must not enter scope by rebound. Every acceptance
+# criterion, ADR decision item or HANDOFF rule the AGENT introduced carries one trailing
+# marker on its own line:
+#
+#     (origin: agent)                          introduced by the agent, NOT confirmed
+#     (origin: agent, confirmed: YYYY-MM-DD)   a human confirmed THIS item, on that day
+#
+# No marker = human origin. That is the default on purpose: nothing existing is
+# retro-tagged, so the absence of a marker never has to be re-audited.
+#
+# ADVISORY, always. This section never changes an exit code and never caps readiness --
+# it reports what has not been confirmed yet, and the human decides. A gate here would
+# need an adopted budget (the 2.1.0 posture, ADR-043), and nobody has declared one.
+#
+# A marker inside a fenced block or an inline code span is DOCUMENTATION, not a decision:
+# the ADR and the ACCEPTANCE section that DEFINE this grammar quote it, and a scanner that
+# read its own definition as a finding would be measuring its own prose.
+_AO_MARK_RX = re.compile(r"origin:\s*agent\b(?P<rest>[^)\n]*)", re.I)
+_AO_CONF_RX = re.compile(r"confirmed:\s*(?P<value>[^,)\s]*)", re.I)
+_AO_ID_RX = re.compile(r"^[\s>*+-]*(?:\[[ xX]\]\s*)?(?:\d+[.)]\s*)?[*_]*"
+                       r"(?P<id>[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+)")
+_AO_INLINE_CODE_RX = re.compile(r"`[^`]*`")
+_AO_HTML_COMMENT_RX = re.compile(r"<!--.*?-->")
+
+
+def _agent_origin_scan_text(text, label):
+    """Every agent-origin marker in one markdown file. Returns (unconfirmed, confirmed):
+    a list of {id, file, line, malformed, detail} and a count. A `confirmed:` that is not
+    a real YYYY-MM-DD date counts as UNCONFIRMED and is NAMED -- a typo must never read as
+    a human's approval, which is the one failure this marker exists to prevent."""
+    lines = text.split("\n")
+    # A fence that never closes is a typo, not a decision to hide the rest of the file:
+    # the lines after an unmatched opener are scanned as prose. Every OTHER fence still
+    # hides its body, so the grammar's own definitions stay documentation.
+    fenced, in_fence, opener = [False] * len(lines), False, None
+    for idx, raw in enumerate(lines):
+        st = raw.strip()
+        if st.startswith("```") or st.startswith("~~~"):
+            in_fence = not in_fence
+            opener = idx if in_fence else None
+            fenced[idx] = True
+            continue
+        fenced[idx] = in_fence
+    if in_fence and opener is not None:
+        for idx in range(opener, len(lines)):
+            fenced[idx] = False
+    unconfirmed, confirmed = [], 0
+    for i, raw in enumerate(lines, 1):
+        if fenced[i - 1]:
+            continue
+        line = _AO_HTML_COMMENT_RX.sub("", _AO_INLINE_CODE_RX.sub("", raw))
+        idm = _AO_ID_RX.match(line)
+        item = idm.group("id") if idm else "line %d" % i
+        # every marker on the line, not the first: a confirmation appended after the
+        # original tag must be read, never dropped in silence
+        for m in _AO_MARK_RX.finditer(line):
+            cm = _AO_CONF_RX.search(m.group("rest") or "")
+            if cm is None:
+                unconfirmed.append({"id": item, "file": label, "line": i,
+                                    "malformed": False, "detail": None})
+            elif _lc_valid_date(cm.group("value")):
+                confirmed += 1
+            else:
+                unconfirmed.append({"id": item, "file": label, "line": i, "malformed": True,
+                                    "detail": "malformed confirmed: %s"
+                                              % (cm.group("value") or "(empty)")})
+    return unconfirmed, confirmed
+
+
+def _agent_origin_report(root, acceptance=None, adr_dir=None, extra=()):
+    """The advisory dimension over the files that hold decisions: the ACCEPTANCE file
+    (the one named, else `<root>/ACCEPTANCE.md`), every ADR under `adr_dir`, `HANDOFF.md`
+    when present, and whatever the caller already had open (`extra`). Absent files are
+    simply not scanned -- there is nothing to report about a file that does not exist."""
+    paths, seen = [], set()
+
+    def add(p):
+        if not p:
+            return
+        try:
+            key = os.path.realpath(p)
+        except OSError:
+            key = os.path.abspath(p)
+        if key in seen or not os.path.isfile(p):
+            return
+        seen.add(key)
+        paths.append(p)
+
+    for p in extra:
+        add(p)
+    add(acceptance or os.path.join(root, "ACCEPTANCE.md"))
+    add(os.path.join(root, "HANDOFF.md"))
+    adr = adr_dir or os.path.join(root, "docs", "adr")
+    if os.path.isdir(adr):
+        for f in sorted(glob.glob(os.path.join(adr, "*.md"))):
+            add(f)
+    unconfirmed, confirmed, scanned = [], 0, []
+    for p in paths:
+        try:
+            with open(p, "r", encoding="utf-8", errors="replace") as fh:
+                body = fh.read()
+        except OSError:
+            continue          # unreadable is not a finding; it is simply not scanned
+        # forward slashes always: the same tree must name the same file the same way on
+        # Windows and on the CI cells, or a pinned line differs by separator alone.
+        label = _lc_short(p).replace("\\", "/")
+        scanned.append(label)
+        u, c = _agent_origin_scan_text(body, label)
+        unconfirmed += u
+        confirmed += c
+    return {"unconfirmed": unconfirmed, "confirmed": confirmed,
+            "n_unconfirmed": len(unconfirmed), "files_scanned": scanned}
+
+
+def _agent_origin_names(ao, limit=6):
+    """`AC-07 (ACCEPTANCE.md:41), D-03 (docs/adr/ADR-002-x.md:57)` -- the id, where it is,
+    and for a malformed marker WHY it did not count as confirmed."""
+    items = ao["unconfirmed"]
+    out = ", ".join("%s (%s:%d%s)" % (x["id"], x["file"], x["line"],
+                                      ", " + x["detail"] if x["detail"] else "")
+                    for x in items[:limit])
+    if len(items) > limit:
+        out += " +%d more" % (len(items) - limit)
+    return out
+
+
+def _agent_origin_line(ao):
+    """The one advisory line, shared by spec-check and readiness so the two surfaces
+    cannot drift apart."""
+    return ("origin: %d agent-origin item(s) unconfirmed -- %s"
+            % (ao["n_unconfirmed"], _agent_origin_names(ao)))
+
+
 def _spec_check_text(text):
     lines = text.split("\n")
     n = len(lines)
@@ -11824,10 +13583,14 @@ def cmd_spec_check(args):
          else {"blockers": [], "untestable": [], "stack_hits": [],
                "non_ears": 0, "n_criteria": 0})
     # lifecycle (ADR-040): read-only and advisory -- it never touches `fail` below.
-    lc = _lifecycle_for(_lifecycle_root(args.spec[0] if args.spec else None,
-                                        args.acceptance),
-                        getattr(args, "adr_dir", None), text,
+    _root = _lifecycle_root(args.spec[0] if args.spec else None, args.acceptance)
+    lc = _lifecycle_for(_root, getattr(args, "adr_dir", None), text,
                         fallback=not args.spec)
+    # agent-origin (ADR-044): read-only and advisory -- like lifecycle above, it never
+    # touches `fail` below. An unconfirmed item is not a defect; it is a decision still
+    # owed to the human.
+    ao = _agent_origin_report(_root, args.acceptance,
+                              getattr(args, "adr_dir", None), extra=args.spec or ())
     structural = len(m["blockers"]) + len(acc_block)  # estructura = FACT -> bloquea
     soft_find = len(m["untestable"]) + len(m["stack_hits"]) + len(acc_adv)
     fail = structural > 0 or (args.strict and soft_find > 0)
@@ -11836,7 +13599,9 @@ def cmd_spec_check(args):
     if args.json:
         print(json.dumps({"verdict": verdict, "advisory": structural == 0,
                           "acceptance_blockers": acc_block,
-                          "acceptance_advisory": acc_adv, "lifecycle": lc, **m},
+                          "acceptance_advisory": acc_adv, "lifecycle": lc,
+                          "agent_origin": {"unconfirmed": ao["unconfirmed"],
+                                           "confirmed": ao["confirmed"]}, **m},
                          indent=2, ensure_ascii=False))
         sys.exit(1 if fail else 0)
 
@@ -11862,6 +13627,10 @@ def cmd_spec_check(args):
         print("      %s %s %s - %s (%s)"
               % ("!" if c["status"] == "expires before go-live" else "~",
                  c["component"], c.get("version") or "?", c["status"], c["detail"]))
+    # conditional, like every other advisory line here: a tree with no marker prints
+    # exactly what it printed before this release.
+    if ao["n_unconfirmed"]:
+        print("  ~ " + _agent_origin_line(ao))
     print("  i consistency: INFERENTIAL (an uncorrelated checker), not this lint · "
           "structure = FACT (blocks) · prose = advisory (--strict to gate)")
     if verdict == "OK":
@@ -12216,6 +13985,91 @@ def _doctor_hook_registered(settings_path):
     return next((n for n in HOOK_NAMES if n in blob), None)
 
 
+# --------------------------------------------------------------------------- #
+# installed-skill freshness (2.2.0)
+# --------------------------------------------------------------------------- #
+# The field case: skills sat under ~/.claude/skills/uscha-* dated before 1.54.0 while the kit
+# was 1.97.0. A whole discovery ran on the old prose and nothing said a word, because a SKILL.md
+# carried no version to compare. Since 2.2.0 the GENERATED orientation block opens with
+# `<!-- uscha kit: X.Y.Z ... -->` (tools/skill-blocks/, rendered by tools/gen-skill-blocks.py and
+# re-rendered by tools/release.py at every bump), so the comparison is mechanical.
+#
+# ADVISORY, always: this reports, it never gates. `doctor` already exits 1 only on errors, and an
+# outdated install is a WARN -- the operator may be pinning a version on purpose.
+SKILL_KIT_MARK = re.compile(r"uscha kit:\s*(\d+\.\d+\.\d+)")
+# Where install-uscha.py puts the skills: TARGETS = ("codex", "claude") + SKILL_ROOTS. Retyped
+# here rather than imported because install-uscha.py lives at the KIT ROOT and is not installed
+# alongside the engine -- an installed engine could not import it. Kept in one place so the
+# drift, if it ever happens, is one table against one table.
+SKILL_INSTALL_ROOTS = (
+    ("claude", (".claude", "skills")),
+    ("codex", ("plugins", "uscha", "skills")),
+    ("pi", (".agents", "skills")),
+    ("cursor", (".cursor", "skills")),
+    ("copilot", (".copilot", "skills")),
+    ("gemini", (".gemini", "skills")),
+    ("cline", (".cline", "skills")),
+)
+
+
+def _semver_tuple(text):
+    """(major, minor, patch) for comparison, or None when the string is not one."""
+    m = re.match(r"^(\d+)\.(\d+)\.(\d+)$", (text or "").strip())
+    return tuple(int(g) for g in m.groups()) if m else None
+
+
+def _installed_skill_report(root, kit_version):
+    """One install root's uscha-* skills, each with the kit version its block was stamped with.
+
+    Returns None when the root holds no uscha skill at all -- "not installed" is a state, not a
+    fault, and reporting it as an error would make `doctor` red on every machine that installed
+    for one agent out of seven."""
+    if not os.path.isdir(root):
+        return None
+    want = _semver_tuple(kit_version)
+    found, oldest = [], None
+    for name in USCHA_SKILLS:
+        smd = os.path.join(root, name, "SKILL.md")
+        if not os.path.isfile(smd):
+            continue
+        try:
+            with open(smd, encoding="utf-8", errors="replace") as fh:
+                head = fh.read(8192)
+        except OSError:
+            head = ""
+        m = SKILL_KIT_MARK.search(head)
+        seen = m.group(1) if m else None
+        found.append({"skill": name, "installed": seen})
+        got = _semver_tuple(seen)
+        if got is not None and (oldest is None or got < oldest):
+            oldest = got
+    if not found:
+        return None
+    unmarked = [f["skill"] for f in found if f["installed"] is None]
+    if unmarked:
+        # no marker at all = a block rendered before 2.2.0. Older than anything that carries
+        # one, and said that way rather than as a version nobody wrote.
+        status = "outdated"
+        installed = None
+    elif want is None or oldest is None:
+        status = "unknown"
+        installed = ".".join(str(p) for p in oldest) if oldest else None
+    else:
+        installed = ".".join(str(p) for p in oldest)
+        status = "outdated" if oldest < want else "current"
+    return {"root": root, "status": status, "installed": installed, "kit": kit_version,
+            "skills": found, "unmarked": unmarked}
+
+
+def _installed_skill_roots(args):
+    """(target, root) pairs to inspect: the caller's `--installed` when given, else every root
+    the installer knows, under the user's home."""
+    if getattr(args, "installed", None):
+        return [("--installed", d) for d in args.installed]
+    home = os.path.expanduser("~")
+    return [(t, os.path.join(home, *parts)) for t, parts in SKILL_INSTALL_ROOTS]
+
+
 def cmd_doctor(args):
     checks = []   # (nivel 'ok'|'warn'|'error', titulo, detalle)
 
@@ -12285,6 +14139,45 @@ def cmd_doctor(args):
         if mismatched:
             err(f"SKILL.md con frontmatter name distinto al directorio: {', '.join(mismatched)}")
 
+    # --- installed skills vs the kit's VERSION (2.2.0) ----------------------
+    # A discovery once ran on prose from 1.54.0 while the kit was 1.97.0, and nothing said so.
+    # Advisory: reported as a warning, never an error, so it can never fail an installation
+    # someone pinned on purpose.
+    kit_version, version_src = _engine_kit_version()
+    skills_installed = []
+    absent = []
+    for target, sroot in _installed_skill_roots(args):
+        rep = _installed_skill_report(sroot, kit_version)
+        if rep is None:
+            absent.append((target, sroot))
+            skills_installed.append({"target": target, "root": sroot,
+                                     "status": "not installed", "installed": None,
+                                     "kit": kit_version, "skills": [], "unmarked": []})
+            continue
+        rep["target"] = target
+        skills_installed.append(rep)
+        fix = (f"re-install: python install-uscha.py install --target {target} "
+               f"(or `uscha install`)")
+        if rep["status"] == "outdated":
+            shown = rep["installed"] or "no `kit:` marker (block rendered before 2.2.0)"
+            warn(f"SKILLS OUTDATED at {sroot}: installed {shown} < kit {kit_version}", fix)
+        elif rep["status"] == "current":
+            ok(f"skills {target}: current (kit {kit_version})", sroot)
+        else:
+            warn(f"skills {target}: version UNMEASURED at {sroot}",
+                 "the installed blocks carry a marker this engine cannot compare "
+                 f"(installed {rep['installed']!r}, kit {kit_version!r})")
+    if absent:
+        ok("skills not installed for: " + ", ".join(t for t, _ in absent),
+           "not an error -- the kit installs per agent, one target at a time")
+    if kit_version is None:
+        warn("kit version not readable: installed-skill freshness is UNMEASURED",
+             "the comparison needs a `%s`, a `VERSION` or an `uscha-install.json` at or "
+             "above the engine; looked in: " % KIT_VERSION_COPY
+             + ", ".join(version_src or []) + " -- re-install with "
+             "`python install-uscha.py install` (2.2.0 and later copy it beside the "
+             "installed skills)")
+
     # --- hook INV-GOLDEN-01 -------------------------------------------------
     kit_root = os.path.abspath(os.path.join(engine_dir, "..", "..", ".."))
     hook_dirs = [os.path.join(os.path.expanduser("~"), ".claude", "hooks"),
@@ -12461,6 +14354,10 @@ def cmd_doctor(args):
                           # effective settings + origin per knob (2.0.0); null when there is
                           # no project config here to resolve them from
                           "risk_profile": risk_profile, "effective": effective,
+                          # installed-skill freshness (2.2.0): one row per install root the
+                          # installer knows, with BOTH versions -- advisory, never in the verdict
+                          "kit_version": kit_version,
+                          "skills_installed": skills_installed,
                           "checks": [{"level": lv, "title": t, "detail": d}
                                      for lv, t, d in checks]},
                          indent=2, ensure_ascii=True))
@@ -12489,6 +14386,11 @@ def build_parser():
              "python/git, skills, hook, project config, per-repo toolchains")
     pdoc.add_argument("--config", default=None,
                       help="project config to inspect (default: ./uscha.config.json)")
+    pdoc.add_argument("--installed", action="append", default=None, metavar="DIR",
+                      help="skill install root to compare against the kit's VERSION "
+                           "(repeatable; default: every root install-uscha.py writes to, "
+                           "under ~). Advisory -- an outdated install is a warning, never "
+                           "an error")
     pdoc.add_argument("--ledger", default=DEFAULT_LEDGER)
     pdoc.add_argument("--json", action="store_true")
     pdoc.set_defaults(func=cmd_doctor)
@@ -12510,9 +14412,21 @@ def build_parser():
     pri.add_argument("--json", action="store_true")
     pri.set_defaults(func=cmd_rubric_ingest)
 
-    pi = sub.add_parser("init", help="create the ledger from a config file")
-    pi.add_argument("--config", required=True)
+    pi = sub.add_parser("init", help="create the ledger from a config file, or --add-repo one "
+                                     "repo into an existing ledger")
+    pi.add_argument("--config", default=None,
+                    help="the uscha.config.json to freeze into a NEW ledger (required unless "
+                         "--add-repo); with --add-repo it is the file to mirror the new repo "
+                         "into (default: uscha.config.json next to --out)")
     pi.add_argument("--out", default=DEFAULT_LEDGER)
+    pi.add_argument("--add-repo", dest="add_repo", default=None, metavar="NAME",
+                    help="append ONE repo to the EXISTING ledger at --out instead of creating a "
+                         "new one: every existing repo's steps, snapshots and iterations are "
+                         "left untouched and the checksum is re-sealed")
+    pi.add_argument("--path", default=None, help="(with --add-repo) the new repo's path")
+    pi.add_argument("--type", default=None, help="(with --add-repo) the new repo's type")
+    pi.add_argument("--test-command", dest="test_command", default=None,
+                    help="(with --add-repo) the new repo's test command")
     pi.set_defaults(func=cmd_init)
 
     def add_ledger(sp):
@@ -12858,6 +14772,15 @@ def build_parser():
                      help="override defaults.spec_drift.max_lag_days (default 30)")
     psd.add_argument("--json", action="store_true")
     psd.set_defaults(func=cmd_spec_drift)
+
+    pop = sub.add_parser("operability",
+                         help="measure CI / release / RUNBOOK / seed as FACTS in the tree "
+                              "(ADR-048); exit 0 always -- the gate is the profile's")
+    add_ledger(pop)
+    pop.add_argument("--repo", required=True)
+    pop.add_argument("--iteration", type=int, default=1)
+    pop.add_argument("--json", action="store_true")
+    pop.set_defaults(func=cmd_operability)
     pre = sub.add_parser("resolve-escalation",
                          help="close open escalations for a repo (recorded event; "
                               "lifts the readiness cap)")
@@ -12868,20 +14791,82 @@ def build_parser():
 
     plg = sub.add_parser(
         "log-gate",
-        help="persist a FACT-gate verdict (golden-diff/gate-check/pit-check/simplicity/regression) "
-             "so converged and readiness actually see it")
+        help="persist a FACT-gate verdict (golden-diff/gate-check/pit-check/simplicity/"
+             "regression/ci) so converged and readiness actually see it")
     add_ledger(plg)
     plg.add_argument("--repo", required=True)
     plg.add_argument("--iteration", type=int, required=True)
     plg.add_argument("--kind", required=True,
                      choices=["golden-diff", "gate-check", "pit-check", "simplicity",
-                              "regression", "rubric", "waste"])
-    plg.add_argument("--verdict", required=True, choices=["pass", "fail", "not-run"])
+                              "regression", "rubric", "waste", "ci", "corpus", "smoke",
+                              "operability"],
+                     help="ci (2.2.0) records a pipeline run as the FACT it is: a fail caps "
+                          "readiness <=65 and blocks convergence exactly like gate-check. "
+                          "corpus (ADR-046) is the parity door for a field-truth run measured "
+                          "elsewhere; corpus-run writes the same record with the evidence on "
+                          "it. smoke (ADR-047) is the same door for a smoke run measured "
+                          "elsewhere -- a FACT kind, so advisory is refused on it. "
+                          "operability (ADR-048) is accepted for parity with the "
+                          "`operability` subcommand, which is what normally writes it")
+    plg.add_argument("--verdict", required=True,
+                     choices=["pass", "fail", "advisory", "not-run"],
+                     help="advisory (ADR-043) records a measured, non-gating run: it never "
+                          "caps readiness, never blocks convergence, and never reads as ok; "
+                          "accepted only for --kind simplicity|waste|corpus|operability, a FACT "
+                          "gate refuses it")
     plg.add_argument("--count", type=int, default=1,
                      help="failing finding count (fail only; default 1)")
     plg.add_argument("--note", default=None)
+    plg.add_argument("--ref", default=None,
+                     help="where the verdict was measured (a CI run URL or id), stored on the "
+                          "record so the evidence outlives the conversation")
     plg.set_defaults(func=cmd_log_gate)
 
+    pcr = sub.add_parser(
+        "corpus-run",
+        help="run a REAL-INPUT corpus against a command and persist gate:corpus (ADR-046): "
+             "field truth for greenfield, where every test payload was invented by the agent")
+    add_ledger(pcr)
+    pcr.add_argument("--repo", required=True)
+    pcr.add_argument("--corpus", default=None,
+                     help="JSONL corpus: one {\"input\": ..., \"expected\": ..., \"id\": ...} "
+                          "per line (default: repos[R].corpus from the config)")
+    pcr.add_argument("--command", required=True,
+                     help="the command under test; each case's input arrives on ITS stdin "
+                          "(JSON-encoded when it is not a string)")
+    pcr.add_argument("--threshold", type=float, default=None,
+                     help="hit percentage the run must reach to PASS (default: "
+                          "repos[R].corpus_threshold, else defaults.corpus_threshold; with "
+                          "NONE declared the run is advisory -- a gate needs an adopted budget)")
+    pcr.add_argument("--ac", action="append", default=None,
+                     help="criterion id this run is evidence for (repeatable); a criterion "
+                          "whose only evidence is a corpus record closes MEASURED iff it passed")
+    pcr.add_argument("--timeout", type=float, default=CORPUS_DEFAULT_TIMEOUT,
+                     help="per-case seconds before the case is a miss named `timeout` "
+                          "(default %d)" % CORPUS_DEFAULT_TIMEOUT)
+    pcr.add_argument("--max-misses", type=int, default=CORPUS_DEFAULT_MAX_MISSES,
+                     help="how many misses to report and persist (default %d)"
+                          % CORPUS_DEFAULT_MAX_MISSES)
+    pcr.add_argument("--iteration", type=int, default=1)
+    pcr.add_argument("--json", action="store_true")
+    pcr.set_defaults(func=cmd_corpus_run)
+
+    psi = sub.add_parser(
+        "smoke-ingest",
+        help="ingest a smoke report as gate:smoke (ADR-047): the smoke run MEASURED "
+             "instead of narrated -- evidence is executed, not written down")
+    add_ledger(psi)
+    psi.add_argument("--repo", required=True)
+    psi.add_argument("--report", required=True,
+                     help='JSON the PROJECT writes with its own smoke tool: '
+                          '{"checks": [{"name": ..., "ok": true|false, "status": ..., '
+                          '"latency_ms": ..., "evidence": ...}, ...]}. A missing `checks`, '
+                          'an empty list, or a check without a name or a boolean `ok` is '
+                          'exit 2 naming it -- never a scored run')
+    psi.add_argument("--iteration", type=int, default=1)
+    psi.add_argument("--json", action="store_true")
+    psi.set_defaults(func=cmd_smoke_ingest)
+
     pfb = sub.add_parser(
         "flag-blocker",
         help="record (or --resolve) a CONSTITUTION/invariant breach as a BLOCKER "
@@ -13057,7 +15042,9 @@ def build_parser():
 
     ps2 = sub.add_parser(
         "simplicity-check",
-        help="Reduce gate: score diff minimality/complexity over a unified diff")
+        help="Reduce gate: score diff minimality/complexity over a unified diff. Advisory "
+             "by default; gates only with --gate or defaults.simplicity.gate AND at least "
+             "one declared budget")
     ps2.add_argument("--diff", help="path to a unified diff (else --from-git or stdin)")
     ps2.add_argument("--from-git", action="store_true",
                      help="run `git diff --unified=0 <base>` for the diff")
@@ -13073,6 +15060,10 @@ def build_parser():
     ps2.add_argument("--max-abstraction-density", dest="max_abstraction_density",
                      type=float, default=None)
     ps2.add_argument("--indent-width", dest="indent_width", type=int)
+    ps2.add_argument("--gate", action="store_true",
+                     help="make an OVERBUILT verdict exit 1 (same switch as "
+                          "defaults.simplicity.gate). Requires at least one declared budget: "
+                          "without one the run REFUSES with exit 2 (ADR-043)")
     ps2.add_argument("--json", action="store_true")
     ps2.set_defaults(func=cmd_simplicity_check)
 
@@ -13121,8 +15112,9 @@ def build_parser():
     pgc.add_argument("--ledger", default=DEFAULT_LEDGER,
                      help="(with --repo) ledger for the measured test-count cross-check")
     pgc.add_argument("--repo", default=None,
-                     help="optional: compare the last two snapshots' executed-test totals "
-                          "(a measured drop flags REVIEW — no regex can miss it)")
+                     help="SCOPE the diff to repos[R].path (a monorepo sibling's hunks are not "
+                          "this repo's findings) and compare the last two snapshots' "
+                          "executed-test totals (a measured drop flags REVIEW)")
     pgc.add_argument("--json", action="store_true")
     pgc.set_defaults(func=cmd_gate_check)