@andresmassello/uscha 2.6.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.6.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)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "2.6.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.6.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.6.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.6.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/qa_ledger.py

@@ -2522,13 +2522,16 @@ def _sha256_file(path):
         return None
 
 
-def _enabled_plugins(home):
+def _enabled_plugins(home, cwd="."):
     """`<name>@<marketplace>` -> bool, merged from the SAME settings files doctor walks
     (user ~/.claude, project .claude, project-local; later wins per key). A missing or malformed
-    file is skipped, never raised: a broken settings file must not turn a real tool MISSING."""
+    file is skipped, never raised: a broken settings file must not turn a real tool MISSING.
+    The project files are read under `cwd` (the resolver's project root; "." for every engine
+    caller), so a machine-level caller -- the installer's extras report -- can keep the
+    directory it happens to run from out of the answer."""
     paths = [os.path.join(_claude_config_dir(home), "settings.json"),
-             os.path.join(".claude", "settings.json"),
-             os.path.join(".claude", "settings.local.json")]
+             os.path.join(cwd, ".claude", "settings.json"),
+             os.path.join(cwd, ".claude", "settings.local.json")]
     enabled = {}
     for p in paths:
         try:
@@ -2560,28 +2563,23 @@ def _installed_plugins(home):
     return plugins if isinstance(plugins, dict) else {}
 
 
-def _resolve_plugin_tool(name, home, cwd="."):
-    """Resolve `name` against INSTALLED-AND-ENABLED plugins. `name` is either bare (`review`) or
-    `<plugin>:<skill>` (the harness lists e.g. `open-code-review:review`). A plugin provides the
-    tool when `skills/<skill>/SKILL.md` or `commands/<skill>.md` exists under one of its install
-    paths (official code-review and open-code-review ship only `commands/`). Returns
-    (path, sha256) or None. A `scope: project` record is honored only when its projectPath
-    resolves to cwd (realpath BOTH sides -- the Windows 8.3 short-path gotcha); `scope: user`
-    always. Never raises on a broken registry."""
-    if ":" in name:
-        plugin_part, skill_part = name.split(":", 1)
-    else:
-        plugin_part, skill_part = "", name
-    if not skill_part:
-        return None
-    enabled = _enabled_plugins(home)
+def enabled_plugin_installs(home, cwd=".", plugin=None):
+    """[(`<name>@<marketplace>`, installPath)] for every plugin that is installed AND enabled --
+    the plugin-level half of the registry reader, shared by the QA-tool resolver below and the
+    installer's optional-extras report (ADR-052), which asks about a PLUGIN (engram), not a
+    skill, and must not push a plugin name through the skill resolver. `plugin` filters by the
+    name part before the `@`. A `scope: project` record counts only when its projectPath resolves
+    to `cwd` (realpath BOTH sides -- the Windows 8.3 short-path gotcha); `scope: user` always.
+    Both registry shapes are read (version 1 maps a key to ONE record). Never raises on a broken
+    registry: a malformed file reads as nothing installed."""
+    enabled = _enabled_plugins(home, cwd)
     installed = _installed_plugins(home)
     cwd_real = os.path.realpath(cwd)
+    out = []
     for key, records in installed.items():
         if not enabled.get(key):
             continue
-        pname = key.split("@", 1)[0]
-        if plugin_part and pname != plugin_part:
+        if plugin and key.split("@", 1)[0] != plugin:
             continue
         if isinstance(records, dict):
             records = [records]   # installed_plugins.json version 1: one record per key
@@ -2597,10 +2595,29 @@ def _resolve_plugin_tool(name, home, cwd="."):
             ipath = rec.get("installPath")
             if not ipath or not isinstance(ipath, str):
                 continue
-            for cand in (os.path.join(ipath, "skills", skill_part, "SKILL.md"),
-                         os.path.join(ipath, "commands", skill_part + ".md")):
-                if os.path.isfile(cand):
-                    return cand, _sha256_file(cand)
+            out.append((key, ipath))
+    return out
+
+
+def _resolve_plugin_tool(name, home, cwd="."):
+    """Resolve `name` against INSTALLED-AND-ENABLED plugins. `name` is either bare (`review`) or
+    `<plugin>:<skill>` (the harness lists e.g. `open-code-review:review`). A plugin provides the
+    tool when `skills/<skill>/SKILL.md` or `commands/<skill>.md` exists under one of its install
+    paths (official code-review and open-code-review ship only `commands/`). Returns
+    (path, sha256) or None. A `scope: project` record is honored only when its projectPath
+    resolves to cwd (realpath BOTH sides -- the Windows 8.3 short-path gotcha); `scope: user`
+    always. Never raises on a broken registry."""
+    if ":" in name:
+        plugin_part, skill_part = name.split(":", 1)
+    else:
+        plugin_part, skill_part = "", name
+    if not skill_part:
+        return None
+    for _key, ipath in enabled_plugin_installs(home, cwd=cwd, plugin=plugin_part or None):
+        for cand in (os.path.join(ipath, "skills", skill_part, "SKILL.md"),
+                     os.path.join(ipath, "commands", skill_part + ".md")):
+            if os.path.isfile(cand):
+                return cand, _sha256_file(cand)
     return None
 
 

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

@@ -19,7 +19,7 @@ shape.** Your job is to interrogate until there is a shared system shape, and to
 the documents as you go — not to ask the human to design the system for you.
 
 <!-- uscha:orientation-block:begin -->
-<!-- uscha kit: 2.6.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-mirador/SKILL.md

@@ -18,7 +18,7 @@ Paints the REAL state of the project at a glance. It does not narrate or estimat
 wires the JSON the engine emits into the template. Read-only.
 
 <!-- uscha:orientation-block:begin -->
-<!-- uscha kit: 2.6.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-reverse-discovery/SKILL.md

@@ -24,7 +24,7 @@ evidence-classed, content-addressed, and promoted to the contract only by a per-
 human verdict (ADR-013).**
 
 <!-- uscha:orientation-block:begin -->
-<!-- uscha kit: 2.6.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-rubric/SKILL.md

@@ -22,7 +22,7 @@ the grader — this skill just wraps the neutral prompt so Claude Code users get
 in one command. Never add Claude-specific behavior to the contract.
 
 <!-- uscha:orientation-block:begin -->
-<!-- uscha kit: 2.6.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-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.6.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.6.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,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "2.6.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, 57 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {

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

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "2.6.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.6.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`,
@@ -498,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):
 

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 2.6.0
+uscha-kit 2.7.0

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.6.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.6.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.6.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/qa_ledger.py

@@ -2522,13 +2522,16 @@ def _sha256_file(path):
         return None
 
 
-def _enabled_plugins(home):
+def _enabled_plugins(home, cwd="."):
     """`<name>@<marketplace>` -> bool, merged from the SAME settings files doctor walks
     (user ~/.claude, project .claude, project-local; later wins per key). A missing or malformed
-    file is skipped, never raised: a broken settings file must not turn a real tool MISSING."""
+    file is skipped, never raised: a broken settings file must not turn a real tool MISSING.
+    The project files are read under `cwd` (the resolver's project root; "." for every engine
+    caller), so a machine-level caller -- the installer's extras report -- can keep the
+    directory it happens to run from out of the answer."""
     paths = [os.path.join(_claude_config_dir(home), "settings.json"),
-             os.path.join(".claude", "settings.json"),
-             os.path.join(".claude", "settings.local.json")]
+             os.path.join(cwd, ".claude", "settings.json"),
+             os.path.join(cwd, ".claude", "settings.local.json")]
     enabled = {}
     for p in paths:
         try:
@@ -2560,28 +2563,23 @@ def _installed_plugins(home):
     return plugins if isinstance(plugins, dict) else {}
 
 
-def _resolve_plugin_tool(name, home, cwd="."):
-    """Resolve `name` against INSTALLED-AND-ENABLED plugins. `name` is either bare (`review`) or
-    `<plugin>:<skill>` (the harness lists e.g. `open-code-review:review`). A plugin provides the
-    tool when `skills/<skill>/SKILL.md` or `commands/<skill>.md` exists under one of its install
-    paths (official code-review and open-code-review ship only `commands/`). Returns
-    (path, sha256) or None. A `scope: project` record is honored only when its projectPath
-    resolves to cwd (realpath BOTH sides -- the Windows 8.3 short-path gotcha); `scope: user`
-    always. Never raises on a broken registry."""
-    if ":" in name:
-        plugin_part, skill_part = name.split(":", 1)
-    else:
-        plugin_part, skill_part = "", name
-    if not skill_part:
-        return None
-    enabled = _enabled_plugins(home)
+def enabled_plugin_installs(home, cwd=".", plugin=None):
+    """[(`<name>@<marketplace>`, installPath)] for every plugin that is installed AND enabled --
+    the plugin-level half of the registry reader, shared by the QA-tool resolver below and the
+    installer's optional-extras report (ADR-052), which asks about a PLUGIN (engram), not a
+    skill, and must not push a plugin name through the skill resolver. `plugin` filters by the
+    name part before the `@`. A `scope: project` record counts only when its projectPath resolves
+    to `cwd` (realpath BOTH sides -- the Windows 8.3 short-path gotcha); `scope: user` always.
+    Both registry shapes are read (version 1 maps a key to ONE record). Never raises on a broken
+    registry: a malformed file reads as nothing installed."""
+    enabled = _enabled_plugins(home, cwd)
     installed = _installed_plugins(home)
     cwd_real = os.path.realpath(cwd)
+    out = []
     for key, records in installed.items():
         if not enabled.get(key):
             continue
-        pname = key.split("@", 1)[0]
-        if plugin_part and pname != plugin_part:
+        if plugin and key.split("@", 1)[0] != plugin:
             continue
         if isinstance(records, dict):
             records = [records]   # installed_plugins.json version 1: one record per key
@@ -2597,10 +2595,29 @@ def _resolve_plugin_tool(name, home, cwd="."):
             ipath = rec.get("installPath")
             if not ipath or not isinstance(ipath, str):
                 continue
-            for cand in (os.path.join(ipath, "skills", skill_part, "SKILL.md"),
-                         os.path.join(ipath, "commands", skill_part + ".md")):
-                if os.path.isfile(cand):
-                    return cand, _sha256_file(cand)
+            out.append((key, ipath))
+    return out
+
+
+def _resolve_plugin_tool(name, home, cwd="."):
+    """Resolve `name` against INSTALLED-AND-ENABLED plugins. `name` is either bare (`review`) or
+    `<plugin>:<skill>` (the harness lists e.g. `open-code-review:review`). A plugin provides the
+    tool when `skills/<skill>/SKILL.md` or `commands/<skill>.md` exists under one of its install
+    paths (official code-review and open-code-review ship only `commands/`). Returns
+    (path, sha256) or None. A `scope: project` record is honored only when its projectPath
+    resolves to cwd (realpath BOTH sides -- the Windows 8.3 short-path gotcha); `scope: user`
+    always. Never raises on a broken registry."""
+    if ":" in name:
+        plugin_part, skill_part = name.split(":", 1)
+    else:
+        plugin_part, skill_part = "", name
+    if not skill_part:
+        return None
+    for _key, ipath in enabled_plugin_installs(home, cwd=cwd, plugin=plugin_part or None):
+        for cand in (os.path.join(ipath, "skills", skill_part, "SKILL.md"),
+                     os.path.join(ipath, "commands", skill_part + ".md")):
+            if os.path.isfile(cand):
+                return cand, _sha256_file(cand)
     return None
 
 

package/uscha-kit/skills/uscha-discovery/SKILL.md

@@ -19,7 +19,7 @@ shape.** Your job is to interrogate until there is a shared system shape, and to
 the documents as you go — not to ask the human to design the system for you.
 
 <!-- uscha:orientation-block:begin -->
-<!-- uscha kit: 2.6.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-mirador/SKILL.md

@@ -18,7 +18,7 @@ Paints the REAL state of the project at a glance. It does not narrate or estimat
 wires the JSON the engine emits into the template. Read-only.
 
 <!-- uscha:orientation-block:begin -->
-<!-- uscha kit: 2.6.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/skills/uscha-reverse-discovery/SKILL.md

@@ -24,7 +24,7 @@ evidence-classed, content-addressed, and promoted to the contract only by a per-
 human verdict (ADR-013).**
 
 <!-- uscha:orientation-block:begin -->
-<!-- uscha kit: 2.6.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-rubric/SKILL.md

@@ -22,7 +22,7 @@ the grader — this skill just wraps the neutral prompt so Claude Code users get
 in one command. Never add Claude-specific behavior to the contract.
 
 <!-- uscha:orientation-block:begin -->
-<!-- uscha kit: 2.6.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-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.6.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/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.6.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/uscha.config.json

@@ -1,6 +1,6 @@
 {
   "_comment": "COMPREHENSIVE REFERENCE, not a project config. Every knob the engine and the skills understand, at the kit's own value, so a human can read what can be declared. `uscha init` does NOT copy this file: it GENERATES a minimal project config, because a copied default is an explicit declaration and an explicit declaration outranks the preset named by defaults.risk_profile (ADR-001, as amended). Copy a block from here into your project only when you mean to override the engine default or the preset. NOTE: no version string may be written into this comment -- the release script requires exactly one occurrence of the version in this file (I3), and a second one refuses the next release.",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,