@andresmassello/uscha 1.99.0 → 2.0.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.0.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.0.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

@@ -314,7 +314,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

@@ -1911,6 +1911,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 +1968,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")
@@ -12273,6 +12323,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 +12347,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 +12430,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 +12458,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))

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.0.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.0.0",
   "description": "Uscha spec-driven development methodology for coding agents. Includes npm/npx router.",
   "author": {
     "name": "Andres Massello",

package/uscha-kit/README.md

@@ -1,6 +1,6 @@
 # uscha-kit
 
-**Kit version:** v1.99.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v2.0.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
 
 Spec-driven orchestrator + multi-repo QA for Claude Code, with a deterministic ledger.
 **Nine skills** (`uscha-discovery`, `uscha-adr-refine`, `uscha-devloop`, `uscha-sysdoc`, `uscha-reverse-discovery`,
@@ -444,7 +444,60 @@ primary toolchain of each repo by type (its absence is a WARNING — it may live
 
 ## Configure
 
-Edit `uscha.config.json`:
+`uscha init` **generates** a minimal `uscha.config.json` for the project: its name, the repo it
+detected (path, type, test command), `acceptance_file`, `id_granularity`, `max_iterations`, and
+the `fast_path` block and the `integration` switch (no contract command: that names a build
+system and is yours to add). Those last two are there because the engine defaults
+both to OFF and the kit means them ON — without them `fastpath-eval` would answer
+`DENY configured: false` on a fresh project and readiness would measure five dimensions instead
+of six. Every other knob is absent on purpose and resolves to the engine default. The kit's own
+`uscha-kit/uscha.config.json` is the **comprehensive reference** — every knob at the kit's
+value, to read and copy from — and is no longer copied into projects.
+
+That matters because of one rule: **a knob you declare > the preset named by
+`defaults.risk_profile` > the engine default**. A copied default is an explicit declaration, so
+a project holding the whole reference leaves its risk profile nothing to decide.
+
+- `defaults.risk_profile`: `A`..`E` (ADR-001) — a named preset that expands into
+  `qa_tools_order`, `coverage_threshold` and `golden_required`. `A` (trivial) runs
+  `[code-review]` only; `E` (migration/legacy) requires the three tools, coverage 80 and an
+  approved golden. Absent = the kit defaults.
+- Check what is actually in force, and where each value came from:
+
+```bash
+python3 ~/.claude/skills/uscha-devloop/qa_ledger.py doctor --json
+# -> "risk_profile" and "effective": {knob: {value, origin}}
+```
+
+  `origin` is `override` (you declared it), `profile <X>` (the preset supplied it), or
+  `default` (the engine's own value). An override that supersedes a profile is reported as
+  information, not an error — declaring a knob by hand is how a preset is bent. Nothing is
+  written back into your config: a knob nobody declared stays absent, which is what lets the
+  engine keep telling a requirement apart from a default. With no profile and no
+  `qa_tools_order`, that knob reads `not declared` and convergence uses a window of
+  `--tools-per-cycle` agent steps.
+
+**Migrating a project initialised before 2.0.0.** Its config is the full copy, so
+`coverage_threshold` and `qa_tools_order` read `origin: override` and no profile can move them.
+(`golden_required` is the one the reference never declared, which is why a profile could still
+supply it — that is the whole shape of the defect: the preset reached only the keys the copy
+happened to omit.) Delete the ones you never meant to declare, then add the profile:
+
+```diff
+ {
+   "defaults": {
+-    "coverage_threshold": 60,
+-    "qa_tools_order": ["code-review", "judgment-day", "improve"],
++    "risk_profile": "A",
+     "acceptance_file": "ACCEPTANCE.md"
+   }
+ }
+```
+
+Nothing is deleted for you: a value equal to a former default cannot be told apart from a value
+you chose, so existing configs keep behaving exactly as they did.
+
+The full set of knobs, all optional:
 
 - `repos[]`: name, `path` (relative to the primary repo), `type` (`maven`|`flutter`|`python`|`node`|`go`|`rust`|`dotnet`|`cpp`|`gradle`|`swift`).
 - `defaults.coverage_threshold`: triggers the characterization phase if below it.

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.99.0
+uscha-kit 2.0.0

package/uscha-kit/install-uscha.py

@@ -693,39 +693,144 @@ def _wire_statusline_settings(repo, force, dry_run):
     return ops, wrote, conflicts
 
 
+# The one marker file that names a repo's toolchain, most specific first: a flutter repo also
+# has a pubspec, a gradle repo has no pom, and a python repo can carry a package.json for its
+# tooling. `.csproj`/`.sln` need a glob, so dotnet is probed separately.
+REPO_TYPE_MARKERS = (
+    ("pubspec.yaml", "flutter"), ("pom.xml", "maven"), ("build.gradle", "gradle"),
+    ("build.gradle.kts", "gradle"), ("go.mod", "go"), ("Cargo.toml", "rust"),
+    ("Package.swift", "swift"), ("pyproject.toml", "python"), ("setup.py", "python"),
+    ("CMakeLists.txt", "cpp"), ("package.json", "node"),
+)
+
+GENERATED_CONFIG_NOTE = (
+    "Minimal project config, generated by `uscha init`. Every knob NOT declared here resolves "
+    "to the engine default -- the kit's own uscha.config.json is the comprehensive reference "
+    "for what can be declared. Precedence is: a knob you write here > the preset named by "
+    "defaults.risk_profile (A..E, ADR-001) > the engine default. That is why this file is "
+    "minimal: a copied default is an explicit declaration, and an explicit declaration "
+    "outranks the preset you selected. The blocks that ARE here are the ones the kit means to "
+    "be on and the engine defaults to off (fast_path, integration) plus what the engine cannot "
+    "derive -- never a knob a risk profile owns."
+)
+
+
+def detect_repo_type(repo):
+    """The repo's toolchain, read off the one marker file each build system leaves at its root.
+    None when nothing is recognised -- the human declares `repos[]` by hand, and `init` says so
+    instead of guessing. Never raises: a missing directory (`--dry-run` on a path that does not
+    exist yet) simply has no markers."""
+    if not repo.is_dir():
+        return None
+    for marker, repo_type in REPO_TYPE_MARKERS:
+        if (repo / marker).is_file():
+            return repo_type
+    return "dotnet" if any(repo.glob("*.csproj")) or any(repo.glob("*.sln")) else None
+
+
+def _kit_value(block, key, prefix=""):
+    """One value the generated config copies from the kit reference. A missing key means the
+    kit's own uscha.config.json has been edited into something `init` cannot generate from --
+    a NAMED refusal, never a raw KeyError traceback out of the installer. `prefix` is only for
+    that message, so it names the path the human has to go and look at."""
+    if not isinstance(block, dict) or key not in block:
+        raise InstallError("[install-uscha] kit uscha.config.json has no %s%s - cannot "
+                           "generate a project config from it" % (prefix, key))
+    return block[key]
+
+
+def project_config_bytes(repo):
+    """The project's uscha.config.json, GENERATED rather than copied (kit 2.0.0).
+
+    Copying the kit's reference config turned every kit default into an explicit project
+    declaration, and an explicit declaration outranks the selected `risk_profile` by design
+    (ADR-001) -- so `risk_profile: "A"` still demanded judgment-day and improve, and `"E"`
+    still measured coverage against 60. The presets had never taken effect in a repo
+    initialised with `init`. What is written here is only what the engine cannot derive:
+    identity, the repos, the knobs whose kit intent differs from the engine default, and the
+    ones the SKILL reads (the engine has no fallback for those). Everything else is absent on
+    purpose, so the preset -- once the human declares one -- has something left to decide.
+
+    "Minimal" is not "empty", and the line is drawn at INTENT, never at size: a knob the kit
+    means to be on and the engine defaults to off must be written, or generating instead of
+    copying would silently turn features off. `fast_path` (engine: absent = fail-closed, so
+    `fastpath-eval` would answer DENY `configured: false` on every fresh project) and
+    `integration` (engine: disabled, so readiness would measure five dimensions instead of
+    six) are exactly that. `fast_path` is copied as a WHOLE block from the reference;
+    `integration` carries only its switch, because its contract command names a build system
+    and guessing one is what this generator exists to refuse. No knob any risk
+    profile owns is written here -- that is the defect this release exists to fix, and
+    `AC-RP-06` measures it against the engine's own table."""
+    kit_cfg = load_json(KIT_ROOT / "uscha.config.json", "kit uscha.config.json")
+    kit_defaults = kit_cfg.get("defaults")
+    defaults = {
+        # engine default is None: without it readiness has no acceptance list to measure
+        "acceptance_file": _kit_value(kit_defaults, "acceptance_file", "defaults."),
+        # engine default is "line"; the kit's chosen value is "file" (stable under refactors)
+        "id_granularity": _kit_value(kit_defaults, "id_granularity", "defaults."),
+        # read by the uscha-devloop SKILL, never by the engine, so it has no fallback
+        "max_iterations": _kit_value(kit_defaults, "max_iterations", "defaults."),
+    }
+    repos = []
+    repo_type = detect_repo_type(repo)
+    if repo_type:
+        key = "test_command_" + repo_type
+        defaults[key] = _kit_value(kit_defaults, key, "defaults.")
+        repos.append({"name": repo.name, "path": ".", "type": repo_type})
+    # engine default: absent means NOT configured, and fastpath-eval fails closed on it
+    defaults["fast_path"] = _kit_value(kit_defaults, "fast_path", "defaults.")
+    config = {"_comment": GENERATED_CONFIG_NOTE, "version": source_version(),
+              "project": repo.name, "defaults": defaults, "repos": repos,
+              # top-level, not a default: engine default is disabled, which drops the
+              # integration dimension out of readiness entirely
+              # integration dimension out of readiness entirely. Only the switch: the
+              # contract command is a build-system guess the kit refuses to make
+              "integration": {"enabled": True}}
+    # byte-identical across runs on the same repo + kit, so a second `init` reports `unchanged`
+    # instead of a conflict; LF explicitly, like every other artifact the kit writes.
+    return (json.dumps(config, indent=2, ensure_ascii=False) + "\n").encode("utf-8")
+
+
 def cmd_init(args):
     repo, operations, conflicts = Path(args.repo).expanduser().resolve(), [], []
-    sources = ([(KIT_ROOT / "uscha.config.json", repo / "uscha.config.json")]
-               + [(KIT_ROOT / "templates" / name, repo / name)
+    # (source path or None, payload bytes or None, target): the config is generated, the rest
+    # are copied from templates/. Exactly one of the first two is set per entry.
+    sources = ([(None, project_config_bytes(repo), repo / "uscha.config.json")]
+               + [(KIT_ROOT / "templates" / name, None, repo / name)
                   # AGENTS.md (kit 1.50.2): the context file Codex/pi read (they do not read
                   # CLAUDE.md); shipped as a thin pointer to CLAUDE.md so there is ONE source.
                   for name in ("CLAUDE.md", "AGENTS.md", "CONSTITUTION.md", ".gitattributes")]
-               + [(KIT_ROOT / "templates" / "scripts" / s, repo / ".claude" / "scripts" / s)
+               + [(KIT_ROOT / "templates" / "scripts" / s, None, repo / ".claude" / "scripts" / s)
                   for s in STATUSLINE_SCRIPTS])
     copies = []
-    for source, target in sources:
-        if not source.is_file():
+    for source, payload, target in sources:
+        if source is not None and not source.is_file():
             raise InstallError("[install-uscha] init source missing: %s" % source)
         if target.is_symlink():
             raise InstallError("[install-uscha] init target must not be a symlink: %s" % target)
         if target.exists() and not target.is_file():
             raise InstallError("[install-uscha] init target must be a file: %s" % target)
-        if target.exists() and target.read_bytes() != source.read_bytes() and not args.force:
-            conflicts.append({"path": str(target), "source": str(source)})
-            operations.append({"action": "conflict", "path": str(target), "source": str(source)})
-        elif target.exists() and target.read_bytes() == source.read_bytes():
+        want = payload if payload is not None else source.read_bytes()
+        label = str(source) if source is not None else "<generated>"
+        if target.exists() and target.read_bytes() != want and not args.force:
+            conflicts.append({"path": str(target), "source": label})
+            operations.append({"action": "conflict", "path": str(target), "source": label})
+        elif target.exists() and target.read_bytes() == want:
             operations.append({"action": "unchanged", "path": str(target)})
         else:
-            operations.append({"action": "copy-file", "path": str(target), "source": str(source), "note": "force" if target.exists() else None})
-            copies.append((source, target))
+            operations.append({"action": "copy-file", "path": str(target), "source": label, "note": "force" if target.exists() else None})
+            copies.append((source, want, target))
     # per-file, not all-or-nothing (kit 1.44.1): a differing CLAUDE.md (which EVERY repo
     # already using Claude Code has) used to block ALL four copies. Now the non-conflicting
     # files are written regardless; each conflict is reported and left untouched (resolve by
     # hand, or re-run with --force). Exit stays nonzero while any conflict remains.
     if not args.dry_run:
-        for source, target in copies:
+        for source, want, target in copies:
             target.parent.mkdir(parents=True, exist_ok=True)
-            shutil.copy2(source, target)
+            if source is None:
+                target.write_bytes(want)
+            else:
+                shutil.copy2(source, target)
     # wire the statusline (kit 1.46.0): merge statusLine + Stop hook into the project's
     # settings.json so the user never edits it by hand -- never clobbering existing keys.
     sl_ops, sl_wrote, sl_conflicts = _wire_statusline_settings(repo, args.force, args.dry_run)
@@ -736,7 +841,7 @@ def cmd_init(args):
         status = "conflicts" if args.dry_run else "partial"
     else:
         status = "planned" if args.dry_run else "initialized"
-    wrote = [str(t) for _, t in copies] if not args.dry_run else []
+    wrote = [str(t) for _, _, t in copies] if not args.dry_run else []
     if sl_wrote:
         wrote.append(str(repo / ".claude" / "settings.json"))
     emit({"status": status, "dry_run": args.dry_run, "repo": str(repo),

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

@@ -314,7 +314,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/skills/uscha-devloop/qa_ledger.py

@@ -1911,6 +1911,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 +1968,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")
@@ -12273,6 +12323,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 +12347,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 +12430,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 +12458,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))

package/uscha-kit/uscha.config.json

@@ -1,5 +1,6 @@
 {
-  "version": "1.99.0",
+  "_comment": "COMPREHENSIVE REFERENCE, not a project config. Every knob the engine and the skills understand, at the kit's own value, so a human can read what can be declared. `uscha init` does NOT copy this file: it GENERATES a minimal project config, because a copied default is an explicit declaration and an explicit declaration outranks the preset named by defaults.risk_profile (ADR-001, as amended). Copy a block from here into your project only when you mean to override the engine default or the preset. NOTE: no version string may be written into this comment -- the release script requires exactly one occurrence of the version in this file (I3), and a second one refuses the next release.",
+  "version": "2.0.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,