@andresmassello/uscha 1.99.0 → 2.1.0

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.1.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.
@@ -568,9 +621,9 @@ python3 $QL rebuild --mode compare --baseline REBUILD-BASELINE.json --json   # c
 - Verdicts: `COVERS ≥90` · `PARTIAL ≥70` · `DIVERGE <70`. The score lists the concrete
   **gaps** — feed them back into the SPEC and re-run. Divergence is a spec hole, not a code bug.
 
-## Simplicity gate — "Reduce" (minimality of the change)
+## Simplicity check — "Reduce" (minimality of the change) — ADVISORY by default
 
-The **Simplicity** invariant of the CONSTITUTION made a deterministic gate: it scores the *diff*
+The **Simplicity** invariant of the CONSTITUTION made deterministic: it scores the *diff*
 (not CC by AST — they are measurable proxies: minimality, nesting, new abstractions).
 
 ```bash
@@ -581,21 +634,35 @@ python3 $QL simplicity-check --diff changes.diff --json        # consumed by usc
 
 - Dimensions/weights: diff_size 35, nesting 30, net_growth 20, fan_out 8, blob 7
   (abstraction does NOT weigh in the score — it's a guessy proxy, kept as a metric + advisory flag).
-- Verdicts: `SIMPLE ≥85` · `ACCEPTABLE ≥65` · `OVERBUILT <65` (exit 1 = BLOCKER: trim and re-run).
+- Verdicts: `SIMPLE ≥85` · `ACCEPTABLE ≥65` · `OVERBUILT <65`.
   A gross excess (2× budget, or very deep nesting) caps the score at 60 no matter what.
+- **Advisory by default, exit 0** (kit 2.1.0, ADR-043): every budget above is the KIT's opinion
+  until you declare your own, and an opinion that exits 1 is a gate nobody asked for. It
+  **gates** — OVERBUILT = exit 1 = BLOCKER — only with at least one budget declared in
+  `defaults.simplicity` **AND** `defaults.simplicity.gate: true` (or `--gate`). `gate: true`
+  with no budget declared is a config error, exit 2: a gate with no budget is not a gate.
+  `log-gate --kind simplicity --verdict advisory` persists an advisory run as an advisory —
+  readiness prints `N ok · 1 advisory` and the mirador reads `ADVISORY`, never `OK`.
+- **`max_nesting` is an INDENTATION-DEPTH proxy**, not AST nesting: it reads leading
+  indentation on added lines, so a wrapped argument, JSX, or a multi-line Java literal inflates
+  it with no control flow present. It is named as a proxy in the report rather than made
+  language-aware. 2-space codebase → `--indent-width 2`.
 - **Tests OUT of the budget** (kit 1.11.0): the test files (conventions of the
   9 stacks) are counted and reported separately (`test_lines_added`) but do not gate — writing
   tests never pushes the diff to OVERBUILT (deleting them is already blocked by gate-check).
 - The flags tell you what to trim (guard clauses, speculative types/layers, giant hunks).
-- Budgets in `defaults.simplicity`; adjustable per risk profile. 2-space → `--indent-width 2`.
+- Budgets in `defaults.simplicity`. No risk profile owns them: the gate is a human declaration
+  under every profile A–E.
 
 ## Ledger subcommands
 
 `bench - bench-curate - bench-r2 - bench-roundtrip - bootstrap-oracle - bootstrap-variance - check-coverage - check-terminado - cleanroom - compile-ingest - compile-validate - converged - curate - curation-check - dashboard - discover - doctor - escalate - execution-policy - facts - fastpath-eval - fidelity - flag-blocker - gate-check - golden-coverage - golden-diff - ingest-gate - init - ir-extract - ir-render - lang-compare - log-gate - log-step - oscillation - phase - pit-check - production-finding - promote - readiness - rebuild - regression-check - resolve-escalation - roundtrip - rubric-ingest - simplicity-check - snapshot - spec-change-request - spec-check - spec-doubt - spec-drift - summary - top - waste-check` - the exact current `qa_ledger.py` parser surface (53 subcommands, derived from `SYSTEM-FACTS.json`, itself introspected from `build_parser()`); each supports `--help`.
 
 The **fact gates** (golden-diff, gate-check, pit-check, simplicity) are PERSISTED with
-`log-gate`: a fail blocks convergence and caps readiness ≤65 via the ledger. A CONSTITUTION
-violation is recorded with `flag-blocker` (same effect, until `--resolve`).
+`log-gate`: a fail blocks convergence and caps readiness ≤65 via the ledger; `--verdict
+advisory` records a run that is measured but not gating (it caps nothing, blocks nothing, and
+never counts as an `ok` gate). A CONSTITUTION violation is recorded with `flag-blocker` (same
+effect, until `--resolve`).
 
 ## Notes
 

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.99.0
+uscha-kit 2.1.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

@@ -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.