@andresmassello/uscha 2.5.0 → 2.7.0

package/README.md

@@ -45,7 +45,18 @@ 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.5.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+The kit declares no dependencies and installs none. Since kit 2.7.0 (ADR-052) `install` ends
+with an **extras report** and the installer's `doctor` repeats it as an advisory section: how
+the dev loop's QA tools (`code-review`, `judgment-day`, `improve`, the kit default order) resolve
+on the target machine — through the engine's own resolver, so `code-review` reads "assumed,
+harness-provided, not measured" — and whether the optional engram (uscha does not require it)
+is present, with the commands to add it. Present means usable from Claude: the engram plugin
+installed and enabled, or an MCP server named `engram` in the Claude configuration; a bare
+binary on PATH reads "binary found, not wired into Claude". The MCP check reads only the Claude
+configuration, for `--target codex` too. It only reports: it installs nothing, asks nothing and
+runs none of the commands it prints, and it never changes an exit code.
+
+**Kit v2.7.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 +92,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,7 +196,7 @@ 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 |
 |---|---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "2.5.0",
+  "version": "2.7.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.5.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
+<!-- uscha kit: 2.7.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.5.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
+<!-- uscha kit: 2.7.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.5.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
+<!-- uscha kit: 2.7.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`.