@andresmassello/uscha 1.40.1 → 1.43.0

package/README.md

@@ -12,13 +12,15 @@ instantiation in Claude Code, the **uscha-kit**.
 
 ```
 SpecLoop/
-├── uscha-kit/          # ★ canonical SOURCE of the kit (v1.40.1)
+??? package.json        # npm package: @andresmassello/uscha
+??? bin/uscha.js        # thin npx router to uscha-kit/install-uscha.py
+├── uscha-kit/          # ★ canonical SOURCE of the kit (v1.43.0)
 │   ├── .claude/skills/    #   8 skills: uscha-discovery · uscha-adr-refine · uscha-devloop · uscha-sysdoc
 │   │                      #             uscha-reverse-discovery · uscha-characterize · uscha-rubric · uscha-mirador
 │   ├── .claude/skills/uscha-devloop/qa_ledger.py   # evidence engine (29 subcommands, stdlib)
 │   ├── hooks/             #   PreToolUse: the agent never writes .approved (INV-GOLDEN-01)
 │   ├── templates/         #   CLAUDE.md · CONSTITUTION.md · .gitattributes · docs/adr
-│   └── CHANGELOG-*.md     #   1.2.x → 1.3.0 ("facts block, wired") → 1.4.0 (python) → 1.5.0 (node) → 1.6.0 (go) → 1.7.0 (rust+dotnet) → 1.8.0 (cpp) → 1.9.0 (gradle+swift) → 1.10.0 (traceable acceptance) → 1.11.0 (tests outside the budget) → 1.12.0 (secret-scan) → 1.13.0 (atomic ledger) → 1.14.0 (plateau/stop-signal) → 1.15.0 (golden scrub) → 1.16.0 (regression-capture) → 1.17.0 (threshold provenance) → 1.18.0 (derived FSM) → 1.19.0 (spikes — PragProg backlog CLOSED) → 1.20.0 (global install) → 1.21.0 (namespace uscha-*) → 1.22.0 (doctor) → 1.23.0 (rubric layer) → 1.24.0 (Claude Code plugin) → 1.25.0 (anti-ceremony) → 1.26.0 (waste-check REUSE-FIRST) → 1.27.0 (FTY) → 1.28.0 (measured acceptance %) → 1.29.0 (rebrand → Uscha) → 1.30.0 (dependency gate) → 1.31.0 (evidence freshness + doc-version gate) → 1.32.0 (mirador — bird's-eye view + dashboard --json) → 1.33.0 (mirador telemetry — per-model tokens/time/model + transcript extractor) → 1.34.0 (mirador: project name from config + live watch/auto-refresh) -> 1.35.0 (execution-policy routing) -> 1.36.0 (discovery-intake: production findings + spec-doubt) -> 1.37.0 (ADR experiments: visible hypotheses) -> 1.38.0 (contract closure: SCR bridge + golden labels + calibration) -> 1.39.0 (universal Codex/Claude installer) -> 1.40.1 (npm/npx router)
+│   └── CHANGELOG-*.md     #   1.2.x → 1.3.0 ("facts block, wired") → 1.4.0 (python) → 1.5.0 (node) → 1.6.0 (go) → 1.7.0 (rust+dotnet) → 1.8.0 (cpp) → 1.9.0 (gradle+swift) → 1.10.0 (traceable acceptance) → 1.11.0 (tests outside the budget) → 1.12.0 (secret-scan) → 1.13.0 (atomic ledger) → 1.14.0 (plateau/stop-signal) → 1.15.0 (golden scrub) → 1.16.0 (regression-capture) → 1.17.0 (threshold provenance) → 1.18.0 (derived FSM) → 1.19.0 (spikes — PragProg backlog CLOSED) → 1.20.0 (global install) → 1.21.0 (namespace uscha-*) → 1.22.0 (doctor) → 1.23.0 (rubric layer) → 1.24.0 (Claude Code plugin) → 1.25.0 (anti-ceremony) → 1.26.0 (waste-check REUSE-FIRST) → 1.27.0 (FTY) → 1.28.0 (measured acceptance %) → 1.29.0 (rebrand → Uscha) → 1.30.0 (dependency gate) → 1.31.0 (evidence freshness + doc-version gate) → 1.32.0 (mirador — bird's-eye view + dashboard --json) → 1.33.0 (mirador telemetry — per-model tokens/time/model + transcript extractor) → 1.34.0 (mirador: project name from config + live watch/auto-refresh) -> 1.35.0 (execution-policy routing) -> 1.36.0 (discovery-intake: production findings + spec-doubt) -> 1.37.0 (ADR experiments: visible hypotheses) -> 1.38.0 (contract closure: SCR bridge + golden labels + calibration) -> 1.39.0 (universal Codex/Claude installer) -> 1.40.0 (npm/npx router) -> 1.40.1 (npm package hygiene) -> 1.40.2 (install docs) -> 1.41.0 (safety release) -> 1.41.1 (adversarial-review hardening: JUnit/integration evidence + Codex rollback) -> 1.41.2 (mirador launch UX: self-resolving render + auto-open + honest readiness title) -> 1.41.3 (mirador live view no longer spams browser tabs) -> 1.42.0 (mirador status story: how it's going / what's blocking / what's next) -> 1.43.0 (uscha mirador verb: one command, no python)
 ├── docs/                  # published artifacts (canonical here; Downloads = snapshots)
 │   ├── uscha-claude-code-doc-FINAL.html   # long deck ES (36 slides)
 │   ├── uscha-claude-code-doc-EN.html      # long deck EN
@@ -38,9 +40,9 @@ SpecLoop/
     └── verificacion-team-pitch.json           # 3 lenses over the pitch
 ```
 
-## Status (2026-07-05)
+## Status (2026-07-10)
 
-- **Kit v1.40.1** <!-- uscha:version --> — the fact-gates are WIRED into the engine (1.3.0: `log-gate`,
+- **Kit v1.43.0** <!-- uscha:version --> — the fact-gates are WIRED into the engine (1.3.0: `log-gate`,
   `flag-blocker`, `resolve-escalation`; UNMEASURED; per-tool convergence with a veto from
   the measured snapshot) and the engine measures **Python** repos (1.4.0: pytest/Cobertura + ruff +
   mypy) **TypeScript/JS** (1.5.0: lcov + jest-junit + eslint + tsc) **Go** (1.6.0: native cover
@@ -62,13 +64,13 @@ SpecLoop/
   headline — M5). **Derived FSM** (1.18.0: `phase` computes the workflow state
   from the ledger's facts, never declared; the PR is gated with `--require
   pr-ready` — M4). **Formal spikes** (1.19.0: a `spike/*` branch never passes the PR
-  gate; the legitimate output is an ADR with lessons — M10). **Execution policy routing** (1.35.0: phase-level methodology/model/effort metadata for the operator and Mirador, not readiness scoring). **Discovery intake** (1.36.0: production findings + spec-doubt/SPEC-WRONG enter the ledger and reopen discovery instead of disappearing into narration). **ADR experiments** (1.37.0: `Status: Experiment` is visible/advisory in dashboard/Mirador with feedback/review metadata, not a readiness score). **Contract closure** (1.38.0: structured `spec-change-request`, golden intended vs observed-accidental labels, and post-merge calibration metrics). **Universal installer** (1.39.0: one machine installer for Codex plugin adoption and Claude global install, with dry-run/doctor/version checks). **npm/npx router** (1.40.1: `@andresmassello/uscha` exposes `uscha`/`uscha-kit` and delegates to the canonical Python installer). Smoke suite 224/224 green.
+  gate; the legitimate output is an ADR with lessons — M10). **Execution policy routing** (1.35.0: phase-level methodology/model/effort metadata for the operator and Mirador, not readiness scoring). **Discovery intake** (1.36.0: production findings + spec-doubt/SPEC-WRONG enter the ledger and reopen discovery instead of disappearing into narration). **ADR experiments** (1.37.0: `Status: Experiment` is visible/advisory in dashboard/Mirador with feedback/review metadata, not a readiness score). **Contract closure** (1.38.0: structured `spec-change-request`, golden intended vs observed-accidental labels, and post-merge calibration metrics). **Universal installer** (1.39.0: one machine installer for Codex plugin adoption and Claude global install, with dry-run/doctor/version checks). **npm/npx router** (1.40.0: `@andresmassello/uscha` exposes `uscha`/`uscha-kit` and delegates to the canonical Python installer). **Safety release** (1.41.0: WU1–WU7 plus post-audit P0/P1 hardening for evidence freshness, fail-closed reports, Mirador safety, installer transactions, ledger integrity, and current documentation). Smoke suite 361/361 green.
   **The PragProg backlog is CLOSED: 10 of 10** (see
   `docs/analisis-pragmatic-programmer.md`).
   License: MIT. The principle "facts block, guesses advise" is an enforced property,
   not a slogan.
 - **Docs** — passed through truth-pass against the real engine: every claim describes what
-  v1.40.1 does; the references appendix has **fetch-verified links** to the 10
+  v1.41.0 does; the references appendix has **fetch-verified links** to the 10
   sources. Status convention in the docs: `in the kit` / `new` / `proposal`.
 - **In progress** — dogfooding on a real case (pilot project, Python): the 1.4.0 adapter unblocked it;
   what remains is the read-only dry-run (criterion 2 of the python-adapter HANDOFF) and the on-ramp.
@@ -76,17 +78,23 @@ SpecLoop/
   profiles).
 
 
-## Install from npm/npx
+## Install
+
+Recommended for Codex and Claude Code:
 
 ```bash
-npx @andresmassello/uscha@latest install --target codex
-npx @andresmassello/uscha@latest doctor --target codex
-# or both Codex + Claude:
-npx @andresmassello/uscha@latest install --target both
+npx --yes @andresmassello/uscha@latest install --target codex
+npx --yes @andresmassello/uscha@latest doctor --target codex
+# or both Codex + Claude Code:
+npx --yes @andresmassello/uscha@latest install --target both
+npx --yes @andresmassello/uscha@latest doctor --target both
 ```
 
-The npm package is only a router. The canonical installer remains
-`uscha-kit/install-uscha.py`, and Python 3.8+ is still required on the target machine.
+Full install guide: [`uscha-kit/INSTALL.md`](uscha-kit/INSTALL.md).
+
+The npm package is only a thin router. The canonical installer remains
+`uscha-kit/install-uscha.py`, and Python 3.8+ is still required on the target
+machine.
 
 ## How the kit is re-packaged
 

package/bin/uscha.js

@@ -8,17 +8,29 @@ const candidates = process.platform === 'win32'
   ? [ ['python', []], ['py', ['-3']] ]
   : [ ['python3', []], ['python', []] ];
 
+function supportsPython38(command, prefix) {
+  const result = spawnSync(command, [...prefix, '--version'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.error || result.status !== 0) return false;
+
+  const output = `${result.stdout || ''}\n${result.stderr || ''}`;
+  const match = output.match(/Python\s+(\d+)\.(\d+)/i);
+  return match !== null && (Number(match[1]) > 3
+    || (Number(match[1]) === 3 && Number(match[2]) >= 8));
+}
+
 let lastError = null;
-for (const [cmd, prefix] of candidates) {
-  const result = spawnSync(cmd, [...prefix, script, ...args], { stdio: 'inherit' });
-  if (!result.error) {
-    process.exit(result.status === null ? 1 : result.status);
-  }
-  if (result.error.code !== 'ENOENT') {
+for (const [command, prefix] of candidates) {
+  if (!supportsPython38(command, prefix)) continue;
+
+  const result = spawnSync(command, [...prefix, script, ...args], { stdio: 'inherit' });
+  if (result.error) {
     lastError = result.error;
     break;
   }
-  lastError = result.error;
+  process.exit(result.status === null ? 1 : result.status);
 }
 
 console.error('[uscha] Python 3.8+ is required but was not found in PATH.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "1.40.1",
+  "version": "1.43.0",
   "description": "Uscha installer for Codex and Claude coding-agent workflows.",
   "bin": {
     "uscha": "bin/uscha.js",

package/uscha-kit/.claude/skills/uscha-adr-refine/SKILL.md

@@ -124,8 +124,8 @@ ADR where it could later be "traded away"):
 ```markdown
 # Acceptance — <feature>
 ## Definition of Done
-- [ ] <verifiable criterion>
-- [ ] …
+- [ ] AC-01 — <verifiable criterion>
+- [ ] AC-02 — <verifiable criterion>
 ## How we measure success
 - <objective metric: p95, cost, zero orphans, …>
 ## Out of scope

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

@@ -418,7 +418,9 @@ BLOCKER/CRITICAL open → ≤65, unresolved escalation → ≤75 (held until
 `resolve-escalation` — a recorded event, not an implication). A `CONSTITUTION.md`
 breach does NOT reach the engine by itself: **you MUST log it** —
 `flag-blocker --repo <REPO> --kind constitution --note "<invariant breached>"` — and
-once logged it caps readiness ≤65 and blocks convergence until `--resolve`. Bands:
+once logged it caps readiness ≤65 and blocks convergence until resolved with
+`flag-blocker --repo <REPO> --kind constitution --resolve --escape-analysis
+"Added a regression test for the invariant."`. Bands:
 <50 NOT READY, 50–79 IN PROGRESS, 80–94 RELEASE CANDIDATE, 95–100 READY.
 
 **Acceptance traceability (the DOMINANT dimension — kit 1.10.0).** Each ACCEPTANCE