@andresmassello/uscha 2.5.0 → 2.7.0

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

@@ -58,7 +58,7 @@ that surface the warning cannot come from the skill itself. The `doctor` seam is
 that still works there — it runs from any kit checkout and reads the installs from outside.
 
 <!-- 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) -->
 
 ## Orientation markers (non-negotiable)
 

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

package/uscha-kit/INSTALL.md

@@ -123,6 +123,13 @@ npx --yes @andresmassello/uscha@latest doctor --target both
 
 `doctor` exits 1 for any unhealthy target in either text or `--json` mode. It checks installed skill presence, manifest/marketplace or hook registration, marker, and version; it does not measure file-content integrity.
 
+`install` (after its transaction commits) and `doctor` (as an advisory section) also report the
+extras (ADR-052, kit 2.7.0): how the dev loop's QA tools resolve on the target machine and whether
+the optional engram is present, with the commands to add it. engram is present when it is usable
+from Claude (the plugin installed and enabled, or an `engram` MCP server in the Claude
+configuration); a bare binary on PATH reads "binary found, not wired into Claude". They only
+report: nothing is installed, no command is run, and neither exit code changes.
+
 If `npm view` returns `404` immediately after a new release, wait a few minutes:
 npm search/dist-tags can propagate before the package metadata endpoint used by
 `npx`. Do not republish the same version while propagation is in progress.

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.7.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
@@ -470,6 +498,21 @@ Claude Code's native plugin flow remains available for Claude-only users, but
 
 
 
+**The extras report** (kit 2.7.0, ADR-052). After the install transaction commits, `install`
+reports — and only reports — how the dev loop's QA tools resolve on the target machine (the
+kit default order `code-review`, `judgment-day`, `improve`, through the engine's own
+`resolve_qa_tool`; `code-review` is "assumed, harness-provided, not measured") and whether the
+optional engram is present, printing the commands a human may run to add it. Present means
+usable from Claude: the plugin installed and enabled (its install path on disk), or an MCP server
+named exactly `engram` at machine level (the user-level `mcpServers` of `.claude.json` or the
+plugin's own `.mcp.json`, never another project's entry). The binary on PATH is reported but
+alone reads "binary found, not wired into Claude". The MCP check reads only the Claude
+configuration, for `--target codex` too. It installs nothing beyond the
+kit, shows no prompt, copies no QA skill and runs none of those commands; a detection error
+prints `could not check extras: <reason>` and the install still succeeds. `--dry-run` lists the
+checks without making them, and `install-uscha.py doctor` repeats the report, live, as an
+advisory section that never changes its exit code.
+
 **Verify the installation with `doctor`** (kit 1.22.0, in the spirit of flutter doctor —
 Windows and Linux, ASCII output, exit 1 only on errors):
 
@@ -553,7 +596,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 +922,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.7.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/install-uscha.py

@@ -618,18 +618,231 @@ def cmd_install(args):
         else:
             root = installers[target](home, args.mode, args.dry_run, operations)
         installed[target] = str(root)
-    emit({"status": "planned" if args.dry_run else "installed", "dry_run": args.dry_run, "source_version": source_version(), "home": str(home), "installed": installed, "operations": operations, "next": next_steps(args.target)}, args.json)
+    # ADR-052: the extras report runs only AFTER every install transaction above has committed
+    # (an install that raised never gets here, so its exit code is untouched), and it can only
+    # ever ADD lines -- a detection error is reported, never raised.
+    extras = extras_plan() if args.dry_run else detect_extras(home, explicit_home=bool(args.home))
+    emit({"status": "planned" if args.dry_run else "installed", "dry_run": args.dry_run, "source_version": source_version(), "home": str(home), "installed": installed, "operations": operations, "next": next_steps(args.target), "extras": extras}, args.json)
+    if not args.json:
+        print_extras(extras)
 
 
 def cmd_doctor(args):
     home = home_path(args)
     targets = {target: target_status(home, target) for target in selected_targets(args.target)}
     ok = all(status["healthy"] for status in targets.values())
-    emit({"ok": ok, "source_version": source_version(), "home": str(home), "python": sys.version.split()[0], "targets": targets}, args.json)
+    # Advisory, LIVE and stateless (ADR-052): re-detected on every run through the same functions
+    # the install summary uses, never read from the marker, and never part of `ok`.
+    extras = detect_extras(home, explicit_home=bool(args.home))
+    emit({"ok": ok, "source_version": source_version(), "home": str(home), "python": sys.version.split()[0], "targets": targets, "extras": extras}, args.json)
+    if not args.json:
+        print_extras(extras, advisory=True)
     if not ok:
         raise SystemExit(1)
 
 
+# --------------------------------------------------------------------------------------------- #
+# Optional extras (ADR-052, kit 2.7.0) -- DETECT AND TELL, never install.
+# The dev loop orchestrates QA tools the kit does not ship (code-review / judgment-day / improve)
+# and works with an optional memory plugin (engram). The installer REPORTS whether they are
+# present and prints the commands a human may choose to run. It installs nothing beyond the kit,
+# asks nothing, copies no QA skill and runs none of the commands it prints: the default install
+# stays dependency-free. Tool resolution is NOT reimplemented here -- the engine's own
+# resolve_qa_tool (ADR-051) answers, so `qa-tools-check` and this report cannot disagree.
+# --------------------------------------------------------------------------------------------- #
+EXTRAS_ENGINE = KIT_ROOT / ".claude" / "skills" / "uscha-devloop" / "qa_ledger.py"
+QA_ORDER_NOTE = "the kit default order; your project's risk profile may need fewer"
+QA_SOURCE_NOTES = {"builtin-assumed": "assumed, harness-provided, not measured"}
+ENGRAM_NOTE = "optional -- uscha does not require it"
+ENGRAM_CHECKS = (("binary", "binary on PATH"),
+                 ("plugin", "plugin installed and enabled"),
+                 ("mcp", "MCP server in the Claude config"))
+# Printed for a human to run; this installer never executes them (smoke T170 pins that).
+ENGRAM_ADD_COMMANDS = ("claude plugin marketplace add Gentleman-Programming/engram",
+                       "claude plugin install engram",
+                       "engram setup claude-code")
+ENGRAM_BINARY_NOTE = "The engram binary itself is a separate download."
+ENGRAM_NOT_WIRED = "binary found, not wired into Claude"
+# The MCP server name the engram plugin's own `.mcp.json` declares. Matched EXACTLY, never as a
+# substring: a server called `not-an-engramatic-thing` is not engram.
+ENGRAM_MCP_SERVER = "engram"
+# A directory that is never created: the resolver's PROJECT probes (./.claude/skills, the project
+# settings files) are pointed at it, so the report describes the MACHINE, not whatever directory
+# `npx` happened to be run from.
+MACHINE_SCOPE_DIR = ".uscha-machine-scope"
+
+
+def _extras_engine():
+    # the npm package's own engine, imported, never reimplemented; no bytecode is written into
+    # the package (the bench arms import it the same way)
+    sys.dont_write_bytecode = True
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("uscha_extras_engine", str(EXTRAS_ENGINE))
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def kit_default_qa_order():
+    """The kit's default qa_tools_order, read from its reference config -- one list, not two."""
+    cfg = load_json(KIT_ROOT / "uscha.config.json", "kit reference config")
+    order = (cfg.get("defaults") or {}).get("qa_tools_order")
+    if not isinstance(order, list) or not order or not all(isinstance(t, str) for t in order):
+        raise InstallError("kit reference config has no qa_tools_order list")
+    return order
+
+
+def extras_plan():
+    """--dry-run: list what would be checked; check nothing, write nothing."""
+    try:
+        order = kit_default_qa_order()
+    except Exception as exc:
+        return {"checked": False, "error": "%s: %s" % (type(exc).__name__, exc)}
+    return {"checked": False, "planned": True,
+            "qa_tools": {"order": order, "order_source": QA_ORDER_NOTE},
+            "engram": {"note": ENGRAM_NOTE, "checks": [label for _, label in ENGRAM_CHECKS]}}
+
+
+def _mcp_names(data):
+    servers = data.get("mcpServers") if isinstance(data, dict) else None
+    return [str(k) for k in servers] if isinstance(servers, dict) else []
+
+
+def _engram_mcp_wired(eng, home, installs):
+    """Is an engram MCP server wired into Claude at MACHINE level? Two sources only: the user-level
+    `mcpServers` of `.claude.json`, and the `.mcp.json` of an installed AND enabled engram plugin
+    whose installPath exists (that is how the plugin wires its server; `installs` arrives already
+    filtered). A `projects[<path>].mcpServers` entry serves one OTHER project, not this machine,
+    so it never counts. The Claude config is the only one read, whatever the install --target.
+    The name must equal ENGRAM_MCP_SERVER. A missing or malformed file reads as not wired."""
+    claude_json = (os.path.join(eng._claude_config_dir(str(home)), ".claude.json")
+                   if os.environ.get("CLAUDE_CONFIG_DIR")
+                   else os.path.join(str(home), ".claude.json"))
+    names = []
+    try:
+        with open(claude_json, encoding="utf-8") as fh:
+            names.extend(_mcp_names(json.load(fh)))
+    except (OSError, ValueError):
+        pass
+    for _key, ipath in installs:
+        try:
+            with open(os.path.join(ipath, ".mcp.json"), encoding="utf-8") as fh:
+                names.extend(_mcp_names(json.load(fh)))
+        except (OSError, ValueError):
+            pass
+    return ENGRAM_MCP_SERVER in names
+
+
+def _on_path(name):
+    """Is `name` an executable in a PATH entry? A manual walk, NOT shutil.which: on Windows
+    shutil.which also searches the CURRENT directory (Python 3.8 always; later versions unless
+    NoDefaultCurrentDirectoryInExePath is set), so an `engram.cmd` lying in the directory `npx`
+    ran from read as installed. The cwd is searched only when PATH itself names it: a literal `.`,
+    or (POSIX semantics) an empty entry -- an empty entry on Windows, a trailing `;`, is skipped.
+    On Windows the PATHEXT extensions are tried."""
+    if os.name == "nt":
+        pathext = os.environ.get("PATHEXT") or ".COM;.EXE;.BAT;.CMD"
+        exts = [e for e in pathext.split(os.pathsep) if e]
+        if os.path.splitext(name)[1].lower() in [e.lower() for e in exts]:
+            names = [name]
+        else:
+            names = [name + e for e in exts]
+    else:
+        names = [name]
+    for entry in os.environ.get("PATH", "").split(os.pathsep):
+        if not entry:
+            if os.name == "nt":
+                continue
+            entry = os.curdir
+        for n in names:
+            cand = os.path.join(entry, n)
+            if os.path.isfile(cand) and (os.name == "nt" or os.access(cand, os.X_OK)):
+                return True
+    return False
+
+
+def detect_extras(home, explicit_home=False):
+    """The one detection path for the install summary AND doctor. Reads external state only and
+    never raises: any error becomes {"checked": False, "error": reason}."""
+    saved = os.environ.get("CLAUDE_CONFIG_DIR")
+    try:
+        # An explicit --home names the machine to describe; a CLAUDE_CONFIG_DIR inherited from
+        # the operator's own shell points at THEIR config, so it is set aside for the probe.
+        # Without --home the target IS this machine, and the variable is honoured, exactly as
+        # the harness and qa-tools-check honour it.
+        if explicit_home and saved is not None:
+            del os.environ["CLAUDE_CONFIG_DIR"]
+        order = kit_default_qa_order()
+        eng = _extras_engine()
+        scope = os.path.join(str(home), MACHINE_SCOPE_DIR)
+        tools = [eng.resolve_qa_tool(t, (), project_root=scope, home=str(home)) for t in order]
+        # an enabled record whose installPath is gone is a stale registry entry, not a plugin
+        # Claude can load (filtered here, not in the shared engine helper)
+        installs = [(k, p) for k, p in
+                    eng.enabled_plugin_installs(str(home), cwd=scope, plugin="engram")
+                    if os.path.isdir(p)]
+        signals = {"binary": _on_path("engram"),
+                   "plugin": bool(installs),
+                   "mcp": _engram_mcp_wired(eng, home, installs)}
+        # present = USABLE from Claude: the plugin or the MCP server. The binary alone is
+        # informational -- a binary nobody wired in gives Claude no engram.
+        usable = bool(signals["plugin"] or signals["mcp"])
+        return {"checked": True,
+                "claude_config_dir": eng._claude_config_dir(str(home)),
+                "qa_tools": {"order": order, "order_source": QA_ORDER_NOTE, "tools": tools},
+                "engram": {"note": ENGRAM_NOTE, "present": usable,
+                           "signals": signals,
+                           "add_commands": list(ENGRAM_ADD_COMMANDS),
+                           "binary_note": ENGRAM_BINARY_NOTE}}
+    except (Exception, SystemExit) as exc:
+        return {"checked": False, "error": "%s: %s" % (type(exc).__name__, exc)}
+    finally:
+        if explicit_home and saved is not None:
+            os.environ["CLAUDE_CONFIG_DIR"] = saved
+
+
+def extras_lines(extras, advisory=False):
+    if not extras.get("checked") and not extras.get("planned"):
+        return ["could not check extras: %s" % extras.get("error", "unknown error")]
+    qa, engram = extras["qa_tools"], extras["engram"]
+    if extras.get("planned"):
+        return ["Extras -- would be checked after the install (--dry-run checks nothing):",
+                "  QA tools for the dev loop (%s): %s" % (qa["order_source"], ", ".join(qa["order"])),
+                "  engram (%s): %s" % (engram["note"], ", ".join(engram["checks"]))]
+    lines = ["Extras -- reported only, never installed%s:"
+             % (" (advisory: not part of doctor's verdict)" if advisory else ""),
+             "  QA tools for the dev loop (%s):" % qa["order_source"]]
+    for row in qa["tools"]:
+        src = row.get("source")
+        where = ("(%s) " % row["root"] if row.get("root") else "") + (row.get("path") or "")
+        detail = QA_SOURCE_NOTES.get(src) or where.strip()
+        lines.append("    %-14s %s%s" % (row.get("tool"), src, (" -- " + detail) if detail else ""))
+    if any(row.get("source") == "MISSING" for row in qa["tools"]):
+        lines.append("    A MISSING tool blocks the dev loop (qa-tools-check): install it as a skill or "
+                     "plugin, or declare it in defaults.qa_tools_external.")
+    sig = engram["signals"]
+    lines.append("  engram (%s): %s" % (engram["note"], "present" if engram["present"] else "missing"))
+    lines.append("    " + " | ".join("%s: %s" % (label, "yes" if sig.get(key) else "no")
+                                     for key, label in ENGRAM_CHECKS))
+    if not engram["present"]:
+        if sig.get("binary"):
+            lines.append("    " + ENGRAM_NOT_WIRED)
+        lines.append("    To add it, run these yourself (this installer never runs them):")
+        lines.extend("      " + c for c in engram["add_commands"])
+    if not sig.get("binary"):
+        lines.append("    " + engram["binary_note"])
+    return lines
+
+
+def print_extras(extras, advisory=False):
+    try:
+        lines = extras_lines(extras, advisory)
+    except Exception as exc:   # a malformed report must not fail a finished install
+        lines = ["could not check extras: %s: %s" % (type(exc).__name__, exc)]
+    for line in lines:
+        print(line)
+
+
 # statusline wiring (kit 1.46.0): the progress statusline + its Stop-hook refresher, installed
 # per-project. Commands are by NAME with forward slashes (Windows eats backslashes in the
 # statusLine command; absolute paths are brittle across machines).

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.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/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/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`.