@andresmassello/uscha 1.99.0 → 2.1.0

package/README.md

@@ -40,7 +40,7 @@ Requires **Python 3.8+** on the machine (the engine is Python stdlib — no pip
 runtime dependencies). The npm package is a thin router; the canonical installer is
 `uscha-kit/install-uscha.py`.
 
-**Kit v1.99.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v2.1.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
 [changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG.md)
 (the per-release changelogs live in the repo, not in the npm tarball)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "1.99.0",
+  "version": "2.1.0",
   "description": "Spec-driven development for LLM coding agents: 9 skills + a stdlib evidence engine. Facts block, guesses advise; the human approves.",
   "author": {
     "name": "Andres Massello",

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

@@ -255,7 +255,7 @@ Implement per the PLAN. Commit per logical step with conventional commits
 - **Never edit the SPEC/ADR to make the implementation look correct.** If reality forces
   a change, amend the SPEC (version it) and return to Ready.
 
-## Phase 2b — Simplicity gate ("Reduce")
+## Phase 2b — Simplicity check ("Reduce") — ADVISORY by default (kit 2.1.0)
 
 Before the QA loop, check the change isn't overbuilt. This is the CONSTITUTION's
 **Simplicidad** invariant made deterministic — diff minimality, nesting depth and new
@@ -266,11 +266,25 @@ git diff --unified=0 <base> | python3 $QL simplicity-check --config uscha.config
 # or: python3 $QL simplicity-check --from-git --base <base>
 ```
 
-Reads `SIMPLICITY: NN/100 — SIMPLE | ACCEPTABLE | OVERBUILT`. **OVERBUILT (exit 1) is a
-BLOCKER**: reduce first (guard clauses, drop speculative types/layers, split giant hunks)
-and re-run — do not carry it into the QA loop or converge on it. The flags tell you exactly
-what to cut. Budgets live in `config.defaults.simplicity` (tighten per risk profile). For a
-2-space codebase pass `--indent-width 2`.
+Reads `SIMPLICITY: NN/100 — SIMPLE | ACCEPTABLE | OVERBUILT  (advisory | declared gate)`.
+
+**Advisory is the default and it exits 0** (ADR-043). Every budget is the KIT'S OPINION until
+the project declares its own; an opinion that stops a loop is a gate nobody asked for. In
+advisory mode an OVERBUILT verdict is **information for the human**: cut what is cheap to cut,
+**report it in the PR body** with the score and the flags, and **never block on it** — do not
+loop, do not refuse to converge, do not "fix" the diff to chase the number.
+
+**It gates only when the project says so**: at least one declared budget in
+`config.defaults.simplicity` **AND** `defaults.simplicity.gate: true` (or `--gate`). Then
+OVERBUILT is exit 1 and a BLOCKER again: reduce first (guard clauses, drop speculative
+types/layers, split giant hunks) and re-run. `gate: true` with **no** budget declared is a
+config error, exit 2 — a gate with no budget is not a gate.
+
+**`max_nesting` is an INDENTATION-DEPTH proxy, not AST nesting** — it counts leading
+indentation on added lines. A wrapped call argument, JSX, or a multi-line Java/Kotlin literal
+raises it with no control flow present at all, which is the single most common false OVERBUILT.
+Discount it accordingly; the kit does not try to make it language-aware. For a 2-space codebase
+pass `--indent-width 2`.
 
 **Tests are OUTSIDE the budget** (kit 1.11.0): test files (the 9 stack conventions) are
 counted and reported apart (`test_lines_added`) but never gate — writing tests must not
@@ -278,13 +292,22 @@ push a diff toward OVERBUILT (deleting them is already blocked by gate-check). A
 project can have MORE test code than production code.
 
 **Persist the verdict** so convergence and readiness see it (facts block through the
-ledger, not through your goodwill):
+ledger, not through your goodwill) — and persist it as what it WAS:
 
 ```bash
+# advisory mode (the default): the run is recorded, and it caps nothing and blocks nothing
+python3 $QL log-gate --repo <REPO> --iteration <N> --kind simplicity \
+  --verdict advisory [--note "OVERBUILT 58/100 — advisory, no budget declared"]
+
+# declared gate only (defaults.simplicity.gate: true + budgets)
 python3 $QL log-gate --repo <REPO> --iteration <N> --kind simplicity \
   --verdict <pass|fail> [--note "OVERBUILT: +612 lines vs 400 budget"]
 ```
 
+**Never log an advisory run as `pass`.** `pass` means a declared gate ran and came back clean;
+an advisory run means there was no gate. Readiness prints them apart (`N ok · 1 advisory`) and
+the mirador shows `ADVISORY` instead of `OK` — but only if you tell it the truth here.
+
 ### Phase 2c — REUSE-FIRST gate (kit 1.26.0)
 
 Simplicity scores the diff in ISOLATION; it cannot see that the new block re-implements
@@ -314,7 +337,16 @@ profile A (trivial change) skip it. It **collapses into `readiness`** as a `gate
 ## Phase 3 — QA loop (per repo)
 
 Run the tools in `config.defaults.qa_tools_order` (default: code-review → judgment-day
-→ improve). One pass of all tools = one cycle. After **each** tool pass:
+→ improve). One pass of all tools = one cycle.
+
+Read the EFFECTIVE order, not the config file: since 2.0.0 `uscha init` generates a minimal
+config, so `qa_tools_order` is often absent there and resolves from `defaults.risk_profile`
+(ADR-001) or from the engine default. `qa_ledger.py doctor --json` prints it as
+`effective.qa_tools_order` with its `origin`; the ledger froze the same value at `init`. A
+project on **profile A runs `code-review` only** — do NOT invoke judgment-day or improve there,
+and convergence must not wait for them.
+
+After **each** tool pass:
 
 1. Apply only fixes at/above the severity gate. Send the rest to `ISSUES-DEFERRED.md`.
 2. Run the repo test command. If red and the fix isn't obvious → escalate.

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

@@ -44,7 +44,8 @@ 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]
@@ -1911,6 +1912,53 @@ def _apply_risk_profile(defaults):
     return defaults
 
 
+# The engine's OWN value for each knob a risk profile owns (kit 2.0.0): the bottom rung of
+# the precedence ladder -- explicit override > selected profile > engine default -- as `doctor`
+# reports it, so the origin of every effective value is visible without reading the source.
+#
+# It is a REPORTING table and is deliberately NEVER materialized into `defaults`. Writing an
+# engine default into the config would make the kit's own value indistinguishable from a human
+# declaration, which is precisely what `thresholds_declared` / `declared_caps` exist to keep
+# apart (provenance, kit 1.17.0) -- and precisely the confusion that let a COPIED config
+# outrank the profile until 2.0.0. The fix for that was to stop copying, not to start
+# injecting: `uscha init` now generates a minimal config (install-uscha.py), and a knob it
+# leaves out keeps meaning "not declared" everywhere the engine reads it.
+#
+# qa_tools_order is None on purpose: with no list declared, convergence falls back to a window
+# of --tools-per-cycle agent steps, so there is no default list to name and saying otherwise
+# would be a narrated claim.
+ENGINE_DEFAULTS = {
+    "qa_tools_order": None,
+    "coverage_threshold": 60,
+    "golden_required": False,
+}
+ENGINE_DEFAULT_NOTES = {
+    "qa_tools_order": "not declared - convergence uses a window of --tools-per-cycle "
+                      "agent steps",
+}
+
+
+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."""
+    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")
+    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:
+            origin[key] = "override"
+        elif profile and key in RISK_PROFILES.get(profile, {}):
+            origin[key] = "profile %s" % profile
+        else:
+            origin[key] = "default"
+    return resolved, origin
+
+
 def _validate_init_config(cfg):
     """Validate only the engine's core init contract before creating a ledger."""
     if not isinstance(cfg, dict):
@@ -1921,6 +1969,9 @@ def _validate_init_config(cfg):
     # expand a named risk profile into concrete knobs BEFORE validating them, so the merged
     # values (qa_tools_order, coverage_threshold, golden_required) flow through the checks
     # below. Explicit config wins per key; an unknown profile fails loud (INV-RISK-01).
+    # Nothing else is written into `defaults`: a key the human did not declare and the profile
+    # did not supply stays ABSENT, so provenance can still tell the kit's default apart from a
+    # declaration (1.17.0). ENGINE_DEFAULTS is what `doctor` reports, never what init freezes.
     _apply_risk_profile(defaults)
     if "golden_required" in defaults and not isinstance(defaults["golden_required"], bool):
         raise SystemExit("[qa_ledger] invalid config: golden_required must be a boolean")
@@ -2447,6 +2498,11 @@ 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),
                           "note": rec.get("note")})
     return sorted(gates, key=lambda g: (g["repo"], g["tool"]))
@@ -2674,11 +2730,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):
     """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 = {
@@ -2690,19 +2753,38 @@ 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
     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.
+ADVISORY_CAPABLE_KINDS = ("simplicity", "waste")
+
+
 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).
+      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
@@ -2724,12 +2806,27 @@ 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)
     _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}")
 
 
 def cmd_flag_blocker(args):
@@ -8349,17 +8446,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
@@ -8983,6 +9084,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"
@@ -9907,13 +10012,21 @@ 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}")
     if not args.verbose:
         return
     print("--- dimensions (weight | raw | contribution) ---")
@@ -9973,6 +10086,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,
 }
@@ -9987,6 +10108,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 = {
@@ -10399,8 +10531,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? "
@@ -10426,10 +10559,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"):
@@ -10441,34 +10576,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)")
@@ -10485,7 +10641,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)
 
 
 # --------------------------------------------------------------------------- #
@@ -12273,6 +12433,7 @@ def cmd_doctor(args):
 
     # --- proyecto (si hay config aca) ---------------------------------------
     qa_order = ["code-review", "judgment-day", "improve"]   # default del kit
+    effective, risk_profile = None, None
     cfg_path = args.config or "uscha.config.json"
     if os.path.isfile(cfg_path):
         try:
@@ -12296,7 +12457,50 @@ def cmd_doctor(args):
                     warn(f"ACCEPTANCE {acc} has no criteria (zero checkboxes)")
             elif acc:
                 warn(f"acceptance_file declared but missing: {acc}")
-            qa_order = defaults.get("qa_tools_order", qa_order)
+            # effective settings, with the ORIGIN of each (2.0.0): the three-rung ladder --
+            # explicit override > selected profile > engine default. Reported, never written
+            # back. An override that supersedes the profile is reported as INFORMATION:
+            # declaring a knob by hand is the documented way to bend a preset, never an error.
+            #
+            # An UNKNOWN profile is caught HERE rather than by the config-wide handler below.
+            # `_apply_risk_profile` raises SystemExit on it (INV-RISK-01: a declared risk level
+            # is never inert, and `init` refuses such a config) -- letting that escape would
+            # abandon the toolchain, rubric and ledger checks that follow, so the diagnostic
+            # would go blind on the first bad key instead of naming it. It is a WARN because
+            # that is the verdict doctor gave this config before 2.0.0: resolving the profile
+            # is a new REPORT, and a new report may not silently raise an existing exit code.
+            risk_profile = defaults.get("risk_profile")
+            try:
+                resolved, origin = _resolved_defaults(cfg)
+            except SystemExit:
+                resolved, origin = None, None
+                warn("unknown risk profile %s - no preset applied" % ascii(risk_profile),
+                     "valid: " + ", ".join(sorted(RISK_PROFILES))
+                     + " - `init` refuses this config (INV-RISK-01); fix it before the loop "
+                       "runs. Every other check below still ran.")
+            if origin is not None:
+                effective = {k: {"value": resolved.get(k), "origin": origin[k]}
+                             for k in ENGINE_DEFAULTS}
+                ok("risk profile: %s" % (risk_profile or "none declared"),
+                   "effective settings below - precedence: override > profile > default")
+                for key in ENGINE_DEFAULTS:
+                    value = resolved.get(key)
+                    if isinstance(value, list):
+                        shown = ", ".join(value)
+                    elif value is None:
+                        shown = ENGINE_DEFAULT_NOTES.get(key, "not declared")
+                    else:
+                        shown = value
+                    detail = "origin: " + origin[key]
+                    if (origin[key] == "override" and risk_profile
+                            and key in RISK_PROFILES.get(risk_profile, {})):
+                        detail += (" - this override supersedes profile %s (information: an "
+                                   "explicit declaration is how a preset is bent)"
+                                   % risk_profile)
+                    ok("effective %s = %s" % (key, shown), detail)
+                # the QA-skills check below asks for the tools actually in force; with no list
+                # declared it keeps looking for the kit's three, as it always has
+                qa_order = resolved.get("qa_tools_order") or qa_order
             for r in repos:
                 tool = DOCTOR_TOOLS.get(r.get("type", ""))
                 if not tool:
@@ -12336,8 +12540,11 @@ def cmd_doctor(args):
             err(f"{cfg_path} invalid", str(exc))
     else:
         warn(f"no {cfg_path} in this directory",
-             "install: copy the kit uscha.config.json to the repo root and declare "
-             "your repos/types and your quality bar - only needed to RUN the loop here")
+             "install: run `uscha init` here (or `python install-uscha.py init --repo .`) - it "
+             "GENERATES a minimal one and detects the repo; then declare your quality bar. Do "
+             "NOT copy the kit's uscha.config.json: it is a REFERENCE, and every knob in it "
+             "would arrive as an explicit declaration outranking your risk_profile (ADR-001, "
+             "as amended) - only needed to RUN the loop here")
 
     # --- skills de QA del loop (externas al kit, se orquestan sin traerlas) --
     # sin ellas la fase 3 (QA loop) no corre; chequeables con o sin config.
@@ -12361,6 +12568,9 @@ def cmd_doctor(args):
         print(json.dumps({"verdict": "ERROR" if n_err else ("WARN" if n_warn else "OK"),
                           "ok": n_ok, "warnings": n_warn, "errors": n_err,
                           "global_install": is_global, "plugin_install": is_plugin,
+                          # 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,
                           "checks": [{"level": lv, "title": t, "detail": d}
                                      for lv, t, d in checks]},
                          indent=2, ensure_ascii=True))
@@ -12776,7 +12986,11 @@ def build_parser():
     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"])
+    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, 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)
@@ -12957,7 +13171,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")
@@ -12973,6 +13189,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)
 

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "1.99.0",
+  "version": "2.1.0",
   "description": "Uscha spec-driven development methodology for coding agents. Includes npm/npx router.",
   "author": {
     "name": "Andres Massello",