@andresmassello/uscha 1.40.1 → 1.43.0

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

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.40.1",
+  "version": "1.43.0",
   "displayName": "Uscha",
   "description": "Spec-driven development for LLM coding agents: 8 skills (discovery, adr-refine, reverse-discovery, characterize, devloop, sysdoc, rubric, mirador) + a stdlib measurement engine (qa_ledger.py, 29 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": "1.40.1",
+  "version": "1.43.0",
   "description": "Uscha spec-driven development methodology for coding agents. Includes npm/npx router.",
   "author": {
     "name": "Andres Massello",

package/uscha-kit/CHANGELOG-1.40.2.md

@@ -0,0 +1,13 @@
+# uscha-kit 1.40.2
+
+## Changed
+
+- Reworked install documentation around the npm/npx path for Codex, Claude Code, and mixed-machine setups.
+- Added `uscha-kit/INSTALL.md` as the focused install guide.
+- Kept Git checkout/link mode, Claude Code plugin commands, and manual copy as secondary/debugging options with tradeoffs.
+
+## Verification
+
+- `npm view @andresmassello/uscha version`
+- `npx --yes @andresmassello/uscha@latest version --json`
+- `bash uscha-kit/tests/smoke-engine.sh`

package/uscha-kit/CHANGELOG-1.41.0.md

@@ -0,0 +1,18 @@
+# uscha-kit 1.41.0 — safety release
+
+Significant backwards-compatible release covering WU1–WU7.
+
+- **WU1:** measured `pr-ready`, fail-closed Ruff/JUnit schemas, and validated counters.
+- **WU2:** safe init, authoritative doctor, portable active Claude hook, marketplace preflight, and staged rollback.
+- **WU3:** evidence-bearing PF/SD/SCR closure, config validation, and monotonic iterations/counters.
+- **WU4:** integration readiness heterogeneous-event false-green prevention, unknown escalation repo rejection, and Spanish ADR label folding.
+- **WU5:** ADR templates use AC IDs; the resolved constitution blocker example includes `--escape-analysis`.
+- **WU6:** npm router probes usable Python >=3.8 before one installer invocation with no retry; workbench-doctor uses portable Python and the current skill roster.
+- **WU7:** complete Claude installation transaction with rollback across managed skills, hook, settings, and marker; T77 covers existing and absent marker rollback.
+- **P0 hardening:** Mirador script/DOM injection removed; structured static reports including Clippy fail closed; stale JUnit evidence cannot satisfy `pr-ready`.
+- **P1 installer hardening:** init preflights all targets and rejects symlinks; Codex restores marketplace state during rollback; hook matcher and malformed Claude settings are validated.
+- **P1 ledger hardening:** readiness configuration is validated completely and PF/SD/SCR closure is immutable after its first resolution.
+- **Documentation truth-pass:** exact 29-command reference, npx-first Codex/Claude adoption, eight-skill inventory, completed EN twins, and refreshed diagrams.
+- Smoke suite: **351/351 green**.
+
+Known boundary: Codex and Claude targets are independently transactional; `--target both` remains sequential rather than cross-target atomic.

package/uscha-kit/CHANGELOG-1.41.1.md

@@ -0,0 +1,53 @@
+# uscha-kit 1.41.1 — adversarial-review hardening (2026-07-11)
+
+An independent adversarial review of the 1.41.0 "safety hardening" release (4 parallel
+reviewers, each tasked to REFUTE the safety claims) confirmed three real defects — two of
+them in the engine's core "measured beats narrated" promise. Fixed here, each with a
+regression check that fails without the fix. Smoke suite: 355/355.
+
+## Fixes
+
+### 1 — `pr-ready` accepted a JUnit that LIES (HIGH, core-promise)
+`_junit_counts` read `tests`/`failures`/`errors` from the `<testsuite>` **attributes** and
+never reconciled them against the actual `<testcase>`/`<failure>`/`<error>` **elements**. A
+report declaring `failures="0"` while containing a real `<failure>` element read as all-green
+and could satisfy `pr-ready`. Fix: honor the child elements, fail-closed —
+`failures = max(attr, element_failures)`, same for errors. A present failure can no longer be
+attribute-declared away. Attribute-only summary suites (no `<testcase>` elements — the form
+many emitters legitimately use) keep their counts, so real adapters are unaffected.
+`qa_ledger.py:_junit_counts`. Regression: smoke **T69b**.
+
+### 2 — integration readiness trusted the single last event (MEDIUM-HIGH, core-promise)
+The integration dimension read `integ_steps[-1]`, so a trailing green test-only step masked
+an earlier FAILING integration gate (dim → 1.0). Fix: green now requires **0 open gated
+findings across the latest record per integration tool** AND the latest test event passing —
+so a failing gate is not masked, while a same-tool re-run that clears the gate is still seen.
+`qa_ledger.py:cmd_readiness`. Regression: smoke **T69c**. (The 1.41.0 CHANGELOG claimed WU4
+fixed this; the code still used `integ_steps[-1]` — the claim was inaccurate.)
+
+### 3 — Codex install rollback destroyed the pre-existing plugin (HIGH, data loss)
+`install_codex` gated its restore on `swapped` (only true after BOTH the backup-move and the
+install-move succeeded), then the `finally` deleted the backup unconditionally. If the
+`stage → plugin_root` swap failed after the original was moved to backup (a real Windows AV /
+locked-handle failure on reinstall), the restore was skipped and the `finally` deleted the
+only surviving copy — silently. Fix: gate the restore on the **backup existing** (not on
+`swapped`), and drop the backup only on SUCCESS (never in `finally`), so a failure restores
+the original and a hard interrupt leaves it intact. Mirrors the Claude path, which already did
+this. `install-uscha.py:install_codex`. Regression: smoke **T77b**. (This is exactly the
+"rollback leaves partial state" category 1.41.0 claimed to close — it closed it for Claude,
+not Codex.)
+
+## Honest limits (not fixed here, by design)
+- A JUnit `<testsuite tests="3"/>` with ZERO `<testcase>` elements is still credited as 3
+  tests. This is the same trust the engine extends to any tool-emitted summary (a coverage %
+  in a coverage report), and closing it would reject the legitimate attribute-only reports
+  many emitters produce. The defense against a **forged** bare report is the "evidence
+  captured by execution" invariant (the SKILL runs the real test command; the agent does not
+  hand-write the XML) + the human merge gate — not per-report forgery detection.
+
+## Also
+- `docs/skills-referencia.html` + `-EN.html`: stale "24 subcommands" → 29 (truth-pass).
+
+## Note on the test suite
+The installer/npm smoke checks hardcode the version string, so a version bump requires
+updating those literals (done here). A follow-up could have them read `VERSION` dynamically.

package/uscha-kit/CHANGELOG-1.41.2.md

@@ -0,0 +1,34 @@
+# uscha-kit 1.41.2 — mirador launch UX (2026-07-18)
+
+A usability release for the mirador (the bird's-eye dashboard). No engine measurement
+logic changed; this makes the mirador honest about "not ready" and trivial to launch from
+inside a running project — "nada de magia oculta". Smoke suite: 357/357.
+
+## Fixes
+
+### 1 — "NOT READY" no longer reads as "hasn't started" (readiness title)
+The mirador mapped the `NOT READY` band (score 0–49) to a fixed title `"Todavia no arranca"`
+("hasn't started yet"). But a project at, say, readiness 22 HAS started — it simply lacks
+enough **measured** evidence. The wording contradicted the score right next to it. Fix: the
+`NOT READY` title is now score-aware — `"Todavia sin evidencia medida"` only at score 0, and
+`"En construccion -- evidencia insuficiente"` above 0. The dead fixed entry was removed from
+`_MIRADOR_TITLE` so the old wording cannot reappear. `qa_ledger.py:cmd_dashboard`.
+Regression: smoke **T78**.
+
+## Launch UX
+
+### 2 — `mirador-render.py` self-resolves its siblings
+`--engine` (the `qa_ledger.py` path) and `--template` (the mirador HTML) now default to the
+renderer's **sibling** skill files. From any project you can run the renderer — or
+`/uscha-mirador` — with just `--ledger`, no long absolute paths. `mirador-render.py:main`.
+
+### 3 — the rendered mirador opens itself, and always prints where it is
+After writing `mirador.html` the renderer opens it in the default browser (best-effort:
+`os.startfile` on Windows, `open`/`xdg-open` elsewhere — never fails on headless/CI) and
+prints the **absolute path** on an `OPEN IT:` line. A new `--no-open` flag suppresses the
+auto-open; the live-watch loop (`mirador-watch.sh`/`.ps1`) and the smoke suite pass it so
+they never spawn browser tabs on every refresh. `mirador-render.py`.
+
+## Note on the test suite
+The installer/npm smoke checks still hardcode the version string, so this bump updated those
+literals (T44, T66/T67 assertions). A follow-up could have them read `VERSION` dynamically.

package/uscha-kit/CHANGELOG-1.41.3.md

@@ -0,0 +1,30 @@
+# uscha-kit 1.41.3 — mirador live-view no longer spams browser tabs (2026-07-18)
+
+A hotfix for a regression shipped in 1.41.2. Smoke suite: 358/358.
+
+## Fix
+
+### mirador-render auto-open + `--refresh` spawned a new browser tab every cycle (HIGH, regression)
+1.41.2 made `mirador-render.py` auto-open the rendered file in the browser. But the live
+second-screen view (`mirador-watch`, and any render with `--refresh N`) injects a
+`<meta http-equiv="refresh">` so a single open tab **reloads itself** every N seconds — and
+the renderer is re-invoked each cycle. Auto-opening on every invocation therefore spawned a
+**new browser tab on every refresh** (30s → a wall of tabs), making the machine unusable while
+a watch loop ran. The `--no-open` flag was not enough on its own: a watch process started
+before 1.41.2 calls the renderer without it.
+
+Fix: auto-open is now suppressed whenever `--refresh > 0` (live mode) — the meta-refresh owns
+the reload, in one tab. Auto-open remains for a genuine **one-shot** render (`/uscha-mirador`
+with no `--refresh`), and `--no-open` still suppresses it everywhere. The `OPEN IT: <abs path>`
+line is always printed, so the live view is one manual open away and never hidden.
+`mirador-render.py:main`. Regression: smoke **T79** (live → 0 opens, one-shot → 1, `--no-open`
+→ 0).
+
+Because the renderer is a fresh subprocess each cycle, a running watch loop picks up this fix
+on its **next** render with no restart — and for a link/junction skill install (the renderer
+lives in this repo), no reinstall either. A copy-mode install needs a reinstall to get the
+fixed file.
+
+## Note on the test suite
+The installer/npm smoke checks still hardcode the version string, so this bump updated those
+literals. A follow-up could have them read `VERSION` dynamically.

package/uscha-kit/CHANGELOG-1.42.0.md

@@ -0,0 +1,41 @@
+# uscha-kit 1.42.0 — the mirador answers "how's it going / what's blocking / what's next" (2026-07-18)
+
+Until now the mirador showed the project's SKELETON — the phase trail, the counters, the
+invariant names — but a real early-stage project rendered as a wall of empty-looking cards
+that left you with "sabor a nada": you could not tell, at a glance, how it was going, what was
+blocking it, or what to do next. This release makes the mirador lead with exactly those three
+answers — and every one of them is **measured**, not narrated. Smoke suite: 359/359.
+
+## The status story (hero block)
+
+A three-line block sits under the verdict, each line derived purely from fields the engine
+already emits in `dashboard --json` (no new engine logic, still model-agnostic):
+
+- **Cómo viene** — the measured sub-scores, verbatim: e.g. `coverage 0% · simplicity FAIL`.
+- **Qué lo traba** — the hard blockers, each traceable to a measured field: failing gates
+  (sub-scores reading FAIL/MISS), the readiness cap (`readiness.sub`), open discovery intake
+  (production findings / spec doubts / spec change requests), and expired/malformed ADR
+  experiments. A failing gate is NOT double-reported as its flipped CONSTITUTION invariant.
+  When nothing blocks, it says so and names the dimensions still lacking measured evidence.
+- **Qué sigue** — the active phase in the derived FSM plus its method and execution hint
+  (`tier` / `model` / `effort`), so the operator sees the next concrete move.
+
+`mirador.template.html:renderStatus`. Regression: smoke **T80**.
+
+## Empty cards earn their place
+
+Cards no longer render as dead space when a real project has nothing for them yet:
+
+- **The 6 layers of truth** (`capas`) — the engine never feeds this for a real project (it was
+  demo-only), so the whole card now HIDES when empty instead of showing an empty grid.
+- **Specifications / ADRs / QA loops** — when empty, show a one-line hint of what fills them
+  and in which phase, instead of a blank list or a bare `0/0`.
+
+## Safety
+All status/hint DOM is built with `textContent` / `createTextNode` (no `innerHTML`), so the
+1.41.0 Mirador XSS hardening still holds — smoke P0-A (script-context escaping, no HTML sinks)
+stays green.
+
+## Note on the test suite
+The installer/npm smoke checks still hardcode the version string, so this bump updated those
+literals. A follow-up could have them read `VERSION` dynamically.

package/uscha-kit/CHANGELOG-1.43.0.md

@@ -0,0 +1,37 @@
+# uscha-kit 1.43.0 — `uscha mirador`: one command, no python, no paths (2026-07-18)
+
+Adoption fix. Bringing up the mirador for a running project meant typing
+`python <long-skill-path>/mirador-render.py --ledger QA-LEDGER.json` — friction that pushed
+users away. The kit already had an npm/npx router (`bin/uscha.js`) forwarding to
+`install-uscha.py`; it was missing one verb. Smoke suite: 361/361.
+
+## New: the `mirador` verb
+
+From the root of any project that has a `QA-LEDGER.json`:
+
+```
+uscha mirador                        # render + open the dashboard
+uscha mirador --watch                # live second-screen view (auto-refresh, one tab)
+npx @andresmassello/uscha mirador    # same, zero install
+```
+
+No python, no paths, no flags required. The verb:
+- resolves the renderer inside the kit (either skill-tree layout), which self-resolves its own
+  engine + template siblings;
+- defaults the ledger to the `QA-LEDGER.json` convention in the current directory
+  (`--ledger` to point elsewhere);
+- one-shot renders and opens the file; `--watch` opens ONE self-reloading tab and re-renders
+  every `--interval` seconds (default 30) WITHOUT re-opening — no browser-tab spam (honors the
+  1.41.3 live-mode rule);
+- fails clearly (exit 1) when the ledger is missing, instead of a stack trace.
+
+`install-uscha.py:cmd_mirador` (exposed through the existing `bin/uscha.js` router).
+Regression: smoke **T81**.
+
+## Docs
+`INSTALL.md` gains a "See the dashboard (mirador)" section; the uscha-mirador `SKILL.md`
+leads its human/terminal path with `uscha mirador`.
+
+## Note on the test suite
+The installer/npm smoke checks still hardcode the version string, so this bump updated those
+literals. A follow-up could have them read `VERSION` dynamically.

package/uscha-kit/INSTALL.md

@@ -0,0 +1,120 @@
+# Install Uscha
+
+Uscha installs as a machine-level helper for coding agents. The recommended path
+is npm/npx because it works the same on a fresh Codex or Claude Code machine.
+
+## Quick path
+
+### Codex Desktop
+
+```bash
+npx --yes @andresmassello/uscha@latest version
+npx --yes @andresmassello/uscha@latest install --target codex --dry-run
+npx --yes @andresmassello/uscha@latest install --target codex
+npx --yes @andresmassello/uscha@latest doctor --target codex
+```
+
+Then restart Codex or open a new thread. The installer registers Uscha as a
+personal local plugin under `~/plugins/uscha` and updates
+`~/.agents/plugins/marketplace.json`. It preflights that marketplace before replacing the plugin tree and writes the install marker last.
+
+### Claude Code
+
+```bash
+npx --yes @andresmassello/uscha@latest install --target claude --dry-run
+npx --yes @andresmassello/uscha@latest install --target claude
+npx --yes @andresmassello/uscha@latest doctor --target claude
+```
+
+This installs the `uscha-*` skills and registers a portable Python `PreToolUse` hook under `~/.claude` while preserving unrelated `settings.json` entries. Restart or reload Claude Code after installing.
+
+### Same machine uses both
+
+```bash
+npx --yes @andresmassello/uscha@latest install --target both --dry-run
+npx --yes @andresmassello/uscha@latest install --target both
+npx --yes @andresmassello/uscha@latest doctor --target both
+```
+
+## Prepare a project repo
+
+After the machine install, initialize each project where Uscha should govern the
+workflow:
+
+```bash
+npx --yes @andresmassello/uscha@latest init --repo . --dry-run
+npx --yes @andresmassello/uscha@latest init --repo .
+# Existing differing files are preserved; use --force only to replace them deliberately.
+npx --yes @andresmassello/uscha@latest init --repo . --force
+```
+
+`init` exits nonzero and reports conflicts for differing `uscha.config.json`, `CLAUDE.md`, `CONSTITUTION.md`, or `.gitattributes`; `--dry-run` performs the same conflict check without writing.
+
+Project state stays in the project: `uscha.config.json`, `QA-LEDGER.json`,
+`ACCEPTANCE.md`, and approved golden fixtures when used.
+
+## See the dashboard (mirador)
+
+From the root of any project that has a `QA-LEDGER.json`, one command renders the mirador and
+opens it — no python, no paths:
+
+```bash
+npx --yes @andresmassello/uscha@latest mirador           # one glance: render + open
+npx --yes @andresmassello/uscha@latest mirador --watch   # live second-screen view (auto-refresh)
+```
+
+It defaults to the `QA-LEDGER.json` convention in the current directory (pass `--ledger` to
+point elsewhere) and prints the absolute path it wrote. `--watch` re-renders every `--interval`
+seconds (default 30) into one self-reloading tab.
+
+## Requirements
+
+| Requirement | Why |
+|-------------|-----|
+| Node.js + npm | Runs the universal `npx` entrypoint. |
+| Python 3.8+ | Runs the canonical stdlib installer and engine. |
+| Git | Used by the method and by project setup checks. |
+| Codex Desktop and/or Claude Code | The agent runtime you want to install Uscha into. |
+
+No `pip install` is required. The engine is Python stdlib-only.
+
+## Other install options
+
+| Option | Use when | Tradeoff |
+|--------|----------|----------|
+| `npx @andresmassello/uscha@latest ...` | Normal install/update on any machine. | Requires npm registry access. |
+| Git checkout + `python uscha-kit/install-uscha.py ...` | Developing Uscha itself or testing unreleased changes. | You must clone/pull the repo yourself. |
+| `--mode link` from a checkout | This machine develops the kit and installed skills should follow local edits. | Links are great for development, risky for normal users. |
+| Claude Code plugin commands | You specifically want Claude Code's native plugin flow. | Codex still needs the npm/git installer path. |
+| Manual copy | Debugging the installer. | Easy to drift; not recommended for adoption. |
+
+Development checkout example:
+
+```bash
+git clone https://github.com/andresmassello/uscha.git
+cd uscha
+python uscha-kit/install-uscha.py install --target both --mode link --dry-run
+python uscha-kit/install-uscha.py install --target both --mode link
+```
+
+Claude Code plugin option:
+
+```text
+/plugin marketplace add andresmassello/uscha
+/plugin install uscha@uscha
+```
+
+## Update and verify
+
+```bash
+npm view @andresmassello/uscha version
+npx --yes @andresmassello/uscha@latest version
+npx --yes @andresmassello/uscha@latest install --target both
+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.
+
+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:** v1.40.1 <!-- uscha:version -->
+**Kit version:** v1.43.0 <!-- uscha:version -->
 
 Spec-driven orchestrator + multi-repo QA for Claude Code, with a deterministic ledger.
 **Eight skills** (`uscha-discovery`, `uscha-adr-refine`, `uscha-devloop`, `uscha-sysdoc`, `uscha-reverse-discovery`,
@@ -14,6 +14,8 @@ changes (a one-liner runs build+test and that's it).
 
 ```
 uscha-kit/
+?? INSTALL.md                   # install guide: npx, Codex, Claude Code, alternatives
+?? install-uscha.py             # canonical installer used by npm/npx
 ├─ uscha.config.json            # config: repos, thresholds, commands
 ├─ hooks/
 │  └─ block-approved-writes.ps1    # PreToolUse: the agent CANNOT write .approved (INV-GOLDEN-01)
@@ -128,8 +130,11 @@ BEFORE touching anything.
   | test count  | `cargo nextest run` + copy (see note)              | `reports/junit.xml` (wrapped JUnit supported) |
   | clippy      | `cargo clippy --message-format=json > reports/clippy.json` | `reports/clippy.json` (JSONL: error→HIGH · warning→MEDIUM · `code:null` compile-error→HIGH; summaries without span ignored) |
 
-  `ingest-gate` with explicit `--clippy` or by type. The inline `#[cfg(test)]` tests
-  count as prod LOC (documented limitation); `tests/` = integration.
+  `ingest-gate` with explicit `--clippy` or by type. Its JSONL evidence is fail-closed:
+  each nonblank line must be a UTF-8 Cargo JSON object with a string `reason`; malformed
+  records or malformed compiler diagnostics are rejected before ledger mutation. An empty
+  file plus valid Cargo summaries and span-less diagnostic summaries remain clean/noise.
+  The inline `#[cfg(test)]` tests count as prod LOC (documented limitation); `tests/` = integration.
   **Watch out for junit**: nextest does NOT emit JUnit by default — you have to enable it in
   `.config/nextest.toml` (`[profile.default.junit] path = "junit.xml"`) and the file
   lands in `target/nextest/default/junit.xml`; copy it to `reports/junit.xml`
@@ -164,6 +169,13 @@ BEFORE touching anything.
   Bazel/make) belongs to the per-repo adapter — the kit only requires that the reports exist.
   `cmake-build-*` (any CLion profile) and `_deps` are excluded from the LOC.
 
+  **Text-report boundary:** mypy, tsc, and clang-tidy ingest only their recognized diagnostic
+  lines. Their legitimate clean/noise forms include status/success text, tool summaries, and
+  (for clang-tidy) passed-through compiler output, so a nonempty unmatched line is not safely
+  distinguishable from a clean report. The kit deliberately does **not** invent fail-closed
+  heuristics for those text formats; use their structured output where a fail-closed schema is
+  required.
+
   Kotlin/JVM with Gradle (`type: gradle`, kit 1.9.0) — **Kotlin over Maven already
   works with `type: maven`** (`.kt` has always counted; JaCoCo/Surefire don't
   distinguish JVM language). This type is for the common Gradle case:
@@ -206,76 +218,34 @@ BEFORE touching anything.
 
 ## Installation
 
-**Preferred public install (kit 1.40.1): use npm/npx.** The npm package is a
-thin router over the canonical Python installer, so adoption is easy without
-duplicating installer logic. You need Node/npm for this path and Python 3.8+ for
-the underlying installer.
-
-Codex-only machine:
-
-```bash
-npx @andresmassello/uscha@latest version
-npx @andresmassello/uscha@latest install --target codex --dry-run
-npx @andresmassello/uscha@latest install --target codex
-npx @andresmassello/uscha@latest doctor --target codex
-```
-
-Machine used by both Codex and Claude:
+**Recommended path: npm/npx.** Use the same installer for Codex, Claude Code,
+or both. Full guide: [`INSTALL.md`](INSTALL.md).
 
 ```bash
-npx @andresmassello/uscha@latest install --target both --dry-run
-npx @andresmassello/uscha@latest install --target both
-npx @andresmassello/uscha@latest doctor --target both
+npx --yes @andresmassello/uscha@latest version
+npx --yes @andresmassello/uscha@latest install --target codex --dry-run
+npx --yes @andresmassello/uscha@latest install --target codex
+npx --yes @andresmassello/uscha@latest doctor --target codex
 ```
 
-**Repo checkout install still works and is preferred when developing the kit
-itself.** One interface, two adapters: Codex gets a personal local plugin
-(`~/plugins/uscha` + `~/.agents/plugins/marketplace.json`), Claude gets global
-skills/hooks under `~/.claude`. Use `--dry-run` first on every new machine.
+For a machine used by both Codex and Claude Code:
 
 ```bash
-python uscha-kit/install-uscha.py version
-python uscha-kit/install-uscha.py install --target codex --dry-run
-python uscha-kit/install-uscha.py install --target codex
-python uscha-kit/install-uscha.py doctor --target codex
+npx --yes @andresmassello/uscha@latest install --target both --dry-run
+npx --yes @andresmassello/uscha@latest install --target both
+npx --yes @andresmassello/uscha@latest doctor --target both
 ```
 
-For the machine where you DEVELOP the kit, use links instead of copies so the
-installed skills follow the canonical repo after `git pull`:
+Use a Git checkout only when developing Uscha itself or testing unreleased
+changes:
 
 ```bash
 python uscha-kit/install-uscha.py install --target both --mode link --dry-run
 python uscha-kit/install-uscha.py install --target both --mode link
 ```
 
-Prepare a repo after the machine install:
-
-```bash
-npx @andresmassello/uscha@latest init --repo <repo> --dry-run
-npx @andresmassello/uscha@latest init --repo <repo>
-# or from a checkout:
-python uscha-kit/install-uscha.py init --repo <repo>
-```
-
-What remains PER PROJECT (state, not installable): `uscha.config.json` in the
-repo root where you run the run (the `path` values are relative to there ? and your declared
-quality bar lives there), the `QA-LEDGER.json`, the `ACCEPTANCE.md`, and for migration
-work the `.gitattributes` from `templates/` (`*.approved.* binary`).
-
-**Legacy/manual install** still works: copy `.claude/` and `uscha.config.json`
-per project, or copy the `uscha-*` skills to `~/.claude/skills/`. Prefer the
-installer unless you are debugging the installer itself.
-
-**Claude Code plugin** remains available for Claude Code users:
-
-```
-/plugin marketplace add andresmassello/uscha
-/plugin install uscha@uscha
-```
-
-Updates: `/plugin update uscha@uscha` for Claude Code plugin installs,
-`npx @andresmassello/uscha@latest install ...` for npm installs, or rerun
-`install-uscha.py install ...` from a repo checkout.
+Claude Code's native plugin flow remains available for Claude-only users, but
+`npx` is the universal path and also covers Codex.
 
 
 
@@ -327,7 +297,7 @@ claude --add-dir ../backend-api --add-dir ../mobile-app
 Inside Claude Code, invoke the orchestrator (with the ADR/PLAN ready or ask it for one):
 
 ```
-/dev-loop
+/uscha-devloop
 ```
 
 The skill handles the phases on its own: plan → coverage gate → (characterization if needed)
@@ -367,7 +337,7 @@ result, not on effort spent**:
 
 ```bash
 python3 $QL readiness --acceptance ACCEPTANCE.md
-python3 $QL readiness --json            # consumed by sys-doc (traffic-light widget)
+python3 $QL readiness --json            # consumed by uscha-sysdoc (traffic-light widget)
 python3 $QL execution-policy --phase qa  # one-line methodology/model/effort routing
 python3 $QL production-finding --repo backend-api --severity HIGH --title "..." --evidence "..."
 python3 $QL spec-doubt --repo backend-api --kind spec-wrong --note "..." --evidence "..."
@@ -411,7 +381,7 @@ python3 $QL rebuild --mode baseline --config uscha.config.json   # → REBUILD-B
 #    SPEC/ADR/ACCEPTANCE, PRESERVING the tests, and run the suite.
 # 3) score the regenerated tree against the baseline
 python3 $QL rebuild --mode compare --baseline REBUILD-BASELINE.json   # exit 0 = COVERS
-python3 $QL rebuild --mode compare --baseline REBUILD-BASELINE.json --json   # consumed by sys-doc
+python3 $QL rebuild --mode compare --baseline REBUILD-BASELINE.json --json   # consumed by uscha-sysdoc
 ```
 
 - Dimensions/weights: tests 60, acceptance 20, coverage 15, surface 5. The dominant signal
@@ -428,7 +398,7 @@ The **Simplicity** invariant of the CONSTITUTION made a deterministic gate: it s
 ```bash
 git diff --unified=0 <base> | python3 $QL simplicity-check --config uscha.config.json
 python3 $QL simplicity-check --from-git --base main            # uses git for you
-python3 $QL simplicity-check --diff changes.diff --json        # consumed by sys-doc / CI
+python3 $QL simplicity-check --diff changes.diff --json        # consumed by uscha-sysdoc / CI
 ```
 
 - Dimensions/weights: diff_size 35, nesting 30, net_growth 20, fan_out 8, blob 7
@@ -443,10 +413,11 @@ python3 $QL simplicity-check --diff changes.diff --json        # consumed by sys
 
 ## Ledger subcommands
 
-`doctor · init · snapshot · check-coverage · log-step · ingest-gate · log-gate · flag-blocker ·
-converged · oscillation · escalate · resolve-escalation · summary · readiness · execution-policy · production-finding · spec-doubt · rebuild ·
-simplicity-check · pit-check · gate-check · spec-check · golden-diff · regression-check ·
-phase · rubric-ingest · doctor` — each with `--help`.
+`doctor - rubric-ingest - init - snapshot - check-coverage - log-step - ingest-gate - phase -
+converged - oscillation - escalate - resolve-escalation - log-gate - flag-blocker -
+production-finding - spec-doubt - spec-change-request - regression-check - summary - readiness -
+execution-policy - dashboard - rebuild - simplicity-check - waste-check - pit-check - gate-check -
+spec-check - golden-diff` - the exact current `qa_ledger.py` parser surface; each supports `--help`.
 
 The **fact gates** (golden-diff, gate-check, pit-check, simplicity) are PERSISTED with
 `log-gate`: a fail blocks convergence and caps readiness ≤65 via the ledger. A CONSTITUTION
@@ -493,5 +464,5 @@ Inside Claude Code, ask it:
 List the active rules from CLAUDE.md and the available skills.
 ```
 
-The protocol rules and the commands /uscha-discovery /uscha-adr-refine
-/uscha-devloop /uscha-sysdoc should appear. (For the machine's toolchain: `bash uscha-kit/workbench-doctor.sh`.)
+The protocol rules and the commands `/uscha-discovery`, `/uscha-adr-refine`,
+`/uscha-devloop`, and `/uscha-sysdoc` should appear. (For the machine's toolchain: `bash uscha-kit/workbench-doctor.sh`.)

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.40.1
+uscha-kit 1.43.0

package/uscha-kit/WORKBENCH.md

@@ -18,11 +18,23 @@ 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** | `discovery`, `adr-refine`, `dev-loop`, `sys-doc` | copiados a `~/.claude/skills/` |
+| **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 de QA** | `code-review`, `judgment-day`, `improve` | tus skills globales (el dev-loop los **orquesta**, no los trae) |
 
 ---
 
+## Camino feliz: instalar Uscha con npx
+
+Uscha instala los skills y la configuracion para Codex, Claude Code o ambos:
+
+```bash
+npx --yes @andresmassello/uscha@latest version
+npx --yes @andresmassello/uscha@latest install --target both
+npx --yes @andresmassello/uscha@latest doctor --target both
+```
+
+`--target codex` o `--target claude` limita la instalacion a un solo entorno. Este es el camino recomendado y portable.
+
 ## 2. Instalar Claude Code
 
 **Native installer (recomendado — no requiere Node, se auto-actualiza):**
@@ -87,6 +99,8 @@ gh auth login          # habilita gh repo create / gh pr
 
 ## 5. Instalar los skills del kit
 
+**Manual, avanzado/legacy (solo Claude Code; preferi `npx` arriba):**
+
 **Global (todos los repos):**
 
 ```bash
@@ -102,14 +116,14 @@ cp -r uscha-kit/.claude/skills  <repo>/.claude/
 cp uscha-kit/uscha.config.json  <repo>/      # config en la raíz del repo
 ```
 
-**Verificar:** abrí `claude` y mirá `/help` — deberían aparecer `/discovery`,
-`/adr-refine`, `/dev-loop`, `/sys-doc`. O `ls ~/.claude/skills`.
+**Verificar:** abra `claude` y mire `/help`: deberian aparecer `/uscha-discovery`,
+`/uscha-adr-refine`, `/uscha-devloop`, `/uscha-sysdoc` y las otras cuatro skills del kit. O `ls ~/.claude/skills`.
 
 ---
 
 ## 6. Los skills de QA externos (dependencia)
 
-El `dev-loop` **orquesta** `code-review` / `judgment-day` / `improve` — **no los empaqueta**.
+El `uscha-devloop` **orquesta** `code-review` / `judgment-day` / `improve` — **no los empaqueta**.
 Tienen que estar en `~/.claude/skills/` (tus skills globales). Si usás otros nombres,
 editá `qa_tools_order` en `uscha.config.json`. Si no los tenés, el loop no encuentra
 las tools de juicio (igual corre el static gate determinístico).
@@ -173,6 +187,6 @@ claude whoami           # cuenta autenticada
 - [ ] `python3 --version` ≥ 3.8
 - [ ] git configurado (`user.name` / `user.email`)
 - [ ] `gh auth login` hecho (si vas a abrir PRs)
-- [ ] `/discovery` `/adr-refine` `/dev-loop` `/sys-doc` aparecen en `/help`
+- [ ] `/uscha-discovery` `/uscha-adr-refine` `/uscha-devloop` `/uscha-sysdoc` aparecen en `/help`
 - [ ] `code-review` / `judgment-day` / `improve` presentes (o `qa_tools_order` ajustado)
 - [ ] `uscha.config.json` en la raíz del repo