@andresmassello/uscha 2.4.0 → 2.6.0

package/README.md

@@ -45,7 +45,7 @@ runtime dependencies). The npm package is a thin router; the canonical installer
 `uscha-kit/install-uscha.py`. `init` also writes a minimal, per-repo-type `.gitignore` when the
 project has none (kit 2.4.0) — it never lists `reports/`, the ledger's own evidence.
 
-**Kit v2.4.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v2.6.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)
 
@@ -81,7 +81,7 @@ and see which file, which test, and when.
 | `/uscha-mirador` | Bird's-eye HTML dashboard: readiness, trail, acceptance, loops |
 | `/uscha-status` | One-line progress readout, in chat |
 
-**A measurement engine** (`qa_ledger.py`, 56 subcommands, Python stdlib) that ingests
+**A measurement engine** (`qa_ledger.py`, 57 subcommands, Python stdlib) that ingests
 evidence from **11 language stacks** — maven, gradle, ant, python, node, go, rust, dotnet,
 cpp, swift, flutter — and computes a readiness score with hard caps and visible provenance.
 
@@ -185,18 +185,18 @@ automatic tool can perform: a human verdict.
    from the compiled code: 0.815 measured (12 archetypes) — names AND behaviour
 ```
 
-**What each arrow is, in the engine (kit 1.96.0, 56 subcommands, all measured):**
+**What each arrow is, in the engine (57 subcommands, all measured):**
 
 | Leg | Subcommands | What it establishes |
 |---|---|---|
 | Asset → typed graph | `ir-extract`, `ir-render` | the whole package becomes one canonical IR (M2, ADR-015) — deterministic, `UNTYPED` is a measurement not an error |
 | Forward, the compiler | `compile-validate`, `compile-ingest` | any model produces code; the engine validates the output contract and never compiles (M3, ADR-016) |
-| Forward, is it the *same* system? | `bootstrap-oracle`, `bootstrap-variance`, `bench` | a withheld oracle judges blind compilations — **12 archetypes, 8 PASS · 4 PARTIAL**, four blind compilers across two vendors (Haiku · Sonnet · Opus · OpenAI Codex `gpt-5.5`), JS included (M4/M5, ADR-017/018/028/029/042) |
+| Forward, is it the *same* system? | `bootstrap-oracle`, `bootstrap-variance`, `bench` | a withheld oracle judges blind compilations — **12 archetypes, 8 PASS · 4 PARTIAL (measured September 2026)**, four blind compilers across two vendors (Haiku · Sonnet · Opus · OpenAI Codex `gpt-5.5`), JS included (M4/M5, ADR-017/018/028/029/042) |
 | Reverse, facts | `discover`, `golden-diff` (+ the `/uscha-characterize` skill) | system map + mechanically captured golden; typed candidate observations with evidence class (M1, ADR-013) |
 | Reverse, the human gate | `curate`, `promote`, `curation-check`, `bench-curate` | one verdict per candidate, append-only ledger verified against git; unjudged → `pr-ready` blocked naming it (ADR-009/010, INV-CURATION-01) |
 | Fidelity, honestly | `fidelity`, `roundtrip`, `bench-roundtrip`, `bench-r2` | per-compiler fidelity vector, id-level round trip, recoverability **0.815**, and the **noise floor** under every variance claim (ADR-014/022/027/030) |
 
-**Read the numbers the way the repo does.** 8 of 12 archetypes regenerate to the same system
+**Read the numbers the way the repo does.** 8 of 12 archetypes (measured September 2026; four blind compilers — Haiku, Sonnet, Opus and OpenAI Codex gpt-5.5) regenerate to the same system
 under an oracle the compilers never saw — that is the closed loop working. It was 9 of 12 until
 1.99.0, when a fourth compiler from a second vendor read one genuinely ambiguous sentence in
 `transformer` the other way and lost a case the three Claude-family models had agreed on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "2.4.0",
+  "version": "2.6.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-adr-refine/SKILL.md

@@ -19,7 +19,7 @@ phases. **You are NOT a generator. You are an interrogator that distills.** The
 is in the questions, not in agreeing.
 
 <!-- uscha:orientation-block:begin -->
-<!-- uscha kit: 2.4.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
+<!-- uscha kit: 2.6.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
 
 ## First contact (show ONCE, then never again)
 

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

@@ -19,7 +19,7 @@ what the code DOES, mechanically, by running it — never what it should do.** Y
 the capture harness; you may NOT create, rename, or edit any `.approved` file.
 
 <!-- uscha:orientation-block:begin -->
-<!-- uscha kit: 2.4.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
+<!-- uscha kit: 2.6.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
 
 ## First contact (show ONCE, then never again)
 

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

@@ -27,7 +27,7 @@ artifacts; these can block) and **self-reported** agent counts (log-step — nar
 recorded for the retrospective; a measured red always overrides a narrated green).
 
 <!-- uscha:orientation-block:begin -->
-<!-- uscha kit: 2.4.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
+<!-- uscha kit: 2.6.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
 
 ## First contact (show ONCE, then never again)
 
@@ -207,6 +207,34 @@ install `hooks/block-approved-writes.py` as a `PreToolUse` hook in
 `settings.json`, and add `*.approved.* binary` to `.gitattributes` (ships in
 `templates/.gitattributes`) so line endings can't lie in the byte-compare.
 
+### QA-tool pre-flight (ADR-051; run BEFORE Phase 0a)
+
+Phase 3 runs QA tools the kit ORCHESTRATES but does not ship (`qa_tools_order`). Before any
+planning, verify they are actually installed — the devloop never assumed this before, and a loop
+must not converge trusting a QA tool that never ran:
+
+```bash
+python3 $QL qa-tools-check --repo <REPO>
+```
+
+Every tool resolves to a source — a project skill, a global skill under ANY agent root the
+installer knows (`~/.claude/skills` or `$CLAUDE_CONFIG_DIR/skills`, Codex `~/plugins/uscha/skills`,
+pi `~/.agents/skills`, cursor, copilot, gemini, cline — the row names the root that hit), an
+installed+enabled plugin, a harness built-in (`code-review`, assumed and reported honestly as
+*not measured*), a tool you declared in `defaults.qa_tools_external`, or **MISSING**. A MISSING
+tool exits 1 and persists `gate:qa-tools` (readiness cap ≤ 65, convergence blocked,
+`phase --require pr-ready` refuses naming it). If a tool is MISSING, **STOP** and tell the human
+the named tool: install it, enable the plugin that provides it, or declare it in
+`defaults.qa_tools_external` of the project's `uscha.config.json` if it is harness-provided, then
+re-run `qa-tools-check`. A LIVE config that declares this one key wins over the ledger's frozen
+copy (it is a fact about the machine, not a run parameter), so no re-init is needed; a live
+config that omits it leaves the frozen declaration standing, an explicit `[]` withdraws it, and
+a value that is not a list of unique nonempty strings is refused by name; `doctor` and the
+check print the same value and origin (`live-config` / `frozen` / `default`). The gate is written
+ONLY by `qa-tools-check` — `log-gate --kind qa-tools` does not exist. A step logged while its
+tool was MISSING stays `unverified` after the tool is installed: re-log it. With no
+`qa_tools_order` declared the check reports UNMEASURED and persists nothing.
+
 ## Phase 0a — Fast-path check (ADR-003; run FIRST, before planning ceremony)
 
 If `defaults.fast_path` exists in config, run the measured classifier before demanding a
@@ -389,6 +417,12 @@ config, so `qa_tools_order` is often absent there and resolves from `defaults.ri
 project on **profile A runs `code-review` only** — do NOT invoke judgment-day or improve there,
 and convergence must not wait for them.
 
+These tools are **resolved, not assumed** (ADR-051): the QA-tool pre-flight already proved each
+one is a project/global skill, an installed+enabled plugin, a harness built-in, or
+declared-external — and `log-step` stamps every step with its tool's resolved `source`. A step
+whose tool is MISSING is recorded `unverified` and cannot satisfy convergence, so this loop never
+closes on a QA pass from a tool that is not installed.
+
 After **each** tool pass:
 
 1. Apply only fixes at/above the severity gate. Send the rest to `ISSUES-DEFERRED.md`.