@andresmassello/uscha 2.5.0 → 2.6.0

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

@@ -22,7 +22,7 @@ switch between at any time:
   coverage, known deferred issues.
 
 <!-- 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.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-plugin/plugin.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "2.5.0",
+  "version": "2.6.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, 56 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
+  "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, 57 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {
     "name": "Andres Massello",
     "url": "https://github.com/andresmassello"

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

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "2.5.0",
+  "version": "2.6.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:** v2.5.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v2.6.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`,
@@ -171,6 +171,34 @@ engine's default and `true` on presets **C, D and E**:
 Nothing is graded. The engine can see that a `## Rollback` heading exists; whether the procedure
 under it is correct is yours.
 
+## QA-tool readiness — `qa-tools-check` (ADR-051)
+
+Phase 3 runs QA tools the kit ORCHESTRATES but does not ship (`qa_tools_order`, default
+`code-review → judgment-day → improve`). Nothing used to check they were installed — a loop could
+converge trusting a tool that never ran. Now each tool is RESOLVED to a source:
+
+```bash
+python3 $QL qa-tools-check --repo <name> [--json]   # exit 1 when a tool is MISSING
+```
+
+| Source | What it means |
+|---|---|
+| `project-skill` / `global-skill` | `./.claude/skills/<name>/SKILL.md`, or `<root>/<name>/SKILL.md` under any agent skills root the installer knows — `~/.claude/skills` (or `$CLAUDE_CONFIG_DIR/skills`), Codex `~/plugins/uscha/skills`, pi `~/.agents/skills`, cursor, copilot, gemini, cline (path + sha256 + the root that hit reported) |
+| `plugin` | an installed **and enabled** plugin provides it (skill or command), bare or `<plugin>:<name>` |
+| `builtin-assumed` | the name is a harness built-in (`code-review`) — assumed, reported honestly as *not measured*, never a false clean and never a block |
+| `declared-external` | you listed it in `defaults.qa_tools_external` (a human declaration, never profile-owned; precedence is per key: a LIVE `uscha.config.json` that declares it — an explicit `[]` included, which withdraws it — wins over the ledger's frozen copy, so declaring it after `init` needs no re-init, while a live file that omits it leaves the frozen declaration standing — origin `live-config` / `frozen` / `default`, the same in `doctor`; a live value of the wrong shape is refused by name) |
+| `MISSING` | none of the above |
+
+Only **MISSING** blocks, under **every** profile: a `missing` tool persists `gate:qa-tools` as a
+BLOCKER — readiness capped ≤ 65, convergence blocked, and `phase --require pr-ready` refuses
+**naming** the tool. "A declared tool is not installed" is a fact, not an opinion, so there is no
+profile knob; `qa-tools` is a FACT kind written only by `qa-tools-check` — there is no
+`log-gate --kind qa-tools` door (refused, exit 2), because the engine measures this fact itself.
+With no `qa_tools_order` declared there is nothing to resolve — UNMEASURED, never a pass.
+`log-step` stamps every step with its tool's resolved source; a MISSING step is recorded
+`unverified` and cannot satisfy convergence — and stays so after you install the tool: re-log it.
+Ledgers written before 2.6.0 carry no provenance and load unchanged.
+
 ## Evidence origin (ADR-007) - green, but green at *what*?
 
 Freshness compares file mtimes, so the ledger could say "tests green" without being able to
@@ -553,7 +581,10 @@ python3 ~/.claude/skills/uscha-devloop/qa_ledger.py doctor --json
 ```
 
   `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
+  `default` (the engine's own value). The one exception is `qa_tools_external` (ADR-051): it is
+  never profile-owned, so its origin is `live-config` (the live `uscha.config.json` declares
+  it), `frozen` (only the ledger's frozen copy does) or `default` (declared nowhere) — or it is absent
+  from `effective`, with a warn naming why, when the live value cannot be resolved. 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
@@ -876,7 +907,7 @@ python3 $QL readiness
 
 ## Ledger subcommands
 
-`bench - bench-curate - bench-r2 - bench-roundtrip - bootstrap-oracle - bootstrap-variance - check-coverage - check-terminado - cleanroom - compile-ingest - compile-validate - converged - corpus-run - 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 - operability - oscillation - phase - pit-check - production-finding - promote - readiness - rebuild - regression-check - resolve-escalation - roundtrip - rubric-ingest - simplicity-check - smoke-ingest - snapshot - spec-change-request - spec-check - spec-doubt - spec-drift - summary - top - waste-check` - the exact current `qa_ledger.py` parser surface (56 subcommands, derived from `SYSTEM-FACTS.json`, itself introspected from `build_parser()`); each supports `--help`.
+`bench - bench-curate - bench-r2 - bench-roundtrip - bootstrap-oracle - bootstrap-variance - check-coverage - check-terminado - cleanroom - compile-ingest - compile-validate - converged - corpus-run - 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 - operability - oscillation - phase - pit-check - production-finding - promote - qa-tools-check - readiness - rebuild - regression-check - resolve-escalation - roundtrip - rubric-ingest - simplicity-check - smoke-ingest - snapshot - spec-change-request - spec-check - spec-doubt - spec-drift - summary - top - waste-check` - the exact current `qa_ledger.py` parser surface (57 subcommands, derived from `SYSTEM-FACTS.json`, itself introspected from `build_parser()`); each supports `--help`.
 
 `gate-check --repo R` SCOPES the diff to `repos[R].path` (2.2.0): in a monorepo one `git diff`
 carries every repo's hunks, and a sibling's findings are neither this repo's report nor this

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 2.5.0
+uscha-kit 2.6.0

package/uscha-kit/WORKBENCH.md

@@ -18,7 +18,7 @@ los linters del static gate, drivers) es el *adapter* del proyecto y vive en el
 | **Python 3.8+** | corre `qa_ledger.py` (stdlib pura, sin dependencias) | `python3` en PATH |
 | **git** | versionado | 2.x, con `user.name`/`user.email` |
 | **gh** (GitHub CLI) | crear repo / abrir PR | opcional pero recomendado |
-| **skills del kit (8)** | `uscha-discovery`, `uscha-adr-refine`, `uscha-devloop`, `uscha-sysdoc`, `uscha-reverse-discovery`, `uscha-characterize`, `uscha-rubric`, `uscha-mirador` | instalados por `npx` en Codex y/o Claude Code |
+| **skills del kit (9)** | `uscha-discovery`, `uscha-adr-refine`, `uscha-devloop`, `uscha-sysdoc`, `uscha-reverse-discovery`, `uscha-characterize`, `uscha-rubric`, `uscha-mirador`, `uscha-status` | instalados por `npx` en Codex y/o Claude Code |
 | **skills de QA** | `code-review`, `judgment-day`, `improve` | tus skills globales (el dev-loop los **orquesta**, no los trae) |
 
 ---

package/uscha-kit/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.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/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.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/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.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`.