@andresmassello/uscha 1.40.1

package/uscha-kit/.claude/skills/uscha-mirador/telemetry-extract.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""telemetry-extract.py -- vendor telemetry for the mirador (uscha-kit 1.33.0).
+
+Parses a Claude Code session transcript (*.jsonl) and appends ONE line to the
+telemetry sidecar (.uscha/telemetry.jsonl) summarizing that session's token and
+wall-time cost, broken down by model.
+
+This is VENDOR telemetry (Claude Code), NOT engine measurement. It lives in the
+mirador skill (the vendor adapter), NEVER in qa_ledger.py -- the engine stays
+model-agnostic and never sees a token. The mirador shows this in a segregated
+strip; it is never gated and never feeds readiness (measured beats narrated).
+
+Usage:
+  python3 telemetry-extract.py <transcript.jsonl> [--sidecar .uscha/telemetry.jsonl] [--note "..."]
+
+Best-effort: unknown/older transcript schemas degrade (missing fields -> 0/None),
+never crash. If no usage data is found, nothing is appended.
+"""
+import argparse
+import json
+import os
+import sys
+from datetime import datetime
+
+
+def _ts(v):
+    if not v:
+        return None
+    try:
+        return datetime.fromisoformat(str(v).replace("Z", "+00:00"))
+    except (ValueError, TypeError):
+        return None
+
+
+def extract(transcript_path):
+    """Returns (by_model: {model: [tin, tout]}, t_min, t_max, seen: bool)."""
+    by_model = {}
+    t_min = t_max = None
+    seen = False
+    with open(transcript_path, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except ValueError:
+                continue
+            ts = _ts(rec.get("timestamp"))
+            if ts:
+                t_min = ts if (t_min is None or ts < t_min) else t_min
+                t_max = ts if (t_max is None or ts > t_max) else t_max
+            msg = rec.get("message") or {}
+            usage = msg.get("usage")
+            if not isinstance(usage, dict):
+                continue
+            model = msg.get("model") or rec.get("model") or "unknown"
+            tin = ((usage.get("input_tokens") or 0)
+                   + (usage.get("cache_read_input_tokens") or 0)
+                   + (usage.get("cache_creation_input_tokens") or 0))
+            tout = usage.get("output_tokens") or 0
+            if tin == 0 and tout == 0:
+                continue
+            agg = by_model.setdefault(model, [0, 0])
+            agg[0] += tin
+            agg[1] += tout
+            seen = True
+    return by_model, t_min, t_max, seen
+
+
+def main():
+    ap = argparse.ArgumentParser(description="append a Claude Code session's token/time cost to the mirador telemetry sidecar")
+    ap.add_argument("transcript", help="path to a Claude Code session transcript (*.jsonl)")
+    ap.add_argument("--sidecar", default=os.path.join(".uscha", "telemetry.jsonl"),
+                    help="append-only telemetry file (default: .uscha/telemetry.jsonl)")
+    ap.add_argument("--session", default=None,
+                    help="session key for idempotent upsert (default: transcript basename); "
+                         "re-running replaces this session's line instead of appending -- "
+                         "so a watch/refresh loop does not inflate the totals")
+    ap.add_argument("--note", default=None, help="optional label for this session line")
+    args = ap.parse_args()
+
+    by_model, t_min, t_max, seen = extract(args.transcript)
+    if not seen:
+        print("[telemetry-extract] no usage data found -- nothing appended", file=sys.stderr)
+        return 0
+
+    bm = [{"model": m, "tokens_in": v[0], "tokens_out": v[1]}
+          for m, v in sorted(by_model.items())]
+    total_in = sum(v["tokens_in"] for v in bm)
+    total_out = sum(v["tokens_out"] for v in bm)
+    ms = int((t_max - t_min).total_seconds() * 1000) if (t_min and t_max) else None
+    at = t_max.isoformat() if t_max else None
+    rec = {
+        "at": at,
+        "model": bm[0]["model"] if len(bm) == 1 else "+".join(v["model"] for v in bm),
+        "tokens_in": total_in, "tokens_out": total_out, "ms": ms,
+        "by_model": bm,
+    }
+    session = args.session or os.path.basename(args.transcript)
+    rec["session"] = session
+    if args.note:
+        rec["note"] = args.note
+
+    os.makedirs(os.path.dirname(args.sidecar) or ".", exist_ok=True)
+    # upsert by session: re-running (watch mode) REPLACES this session's line instead of
+    # appending a duplicate -> a refresh loop never inflates the aggregated totals.
+    kept = []
+    if os.path.isfile(args.sidecar):
+        for line in open(args.sidecar, encoding="utf-8"):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                prev = json.loads(line)
+            except ValueError:
+                continue
+            if prev.get("session") != session:
+                kept.append(prev)
+    kept.append(rec)
+    with open(args.sidecar, "w", encoding="utf-8") as f:
+        for r in kept:
+            f.write(json.dumps(r, ensure_ascii=False) + "\n")
+    print(f"[telemetry-extract] {session}: {total_in} in / {total_out} out "
+          f"across {len(bm)} model(s) -> {args.sidecar} (upsert)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,116 @@
+---
+name: uscha-reverse-discovery
+description: >
+  Brownfield front of the methodology, for migrating/modernizing an EXISTING system. The
+  inverse of discovery: the system already exists and its behavior IS the truth, so you
+  EXTRACT facts instead of proposing shape. Produce ONLY facts — a system map (endpoints,
+  contracts, dependency graph, module candidates via static analysis) and a golden suite
+  captured mechanically at the boundaries. NEVER author an inferred SPEC or ADR of the old
+  system; the human writes those reading your facts. Invoke for "reverse-discovery",
+  "migrar/modernizar este sistema", "caracterizar el sistema viejo antes de tocarlo".
+allowed-tools: Read, Write, Glob, Grep, Bash
+disable-model-invocation: false
+---
+
+# reverse-discovery — extract the facts of an existing system before migrating it
+
+`uscha-discovery` is greenfield: you only have an idea, so you PROPOSE the shape. This is the
+opposite. The system already runs; its observable behavior is the ground truth. **You do
+not invent anything — you characterize what is already there, as facts.**
+
+## The one non-negotiable: produce ONLY facts
+
+A system map (from static analysis) and a golden suite (byte-captured) are FACTS —
+verifiable, not opinions. **You do NOT author a SPEC of "what it does" or ADRs of "why it
+is built this way."** Those are inference, and if the agent writes them it encodes its own
+(mis)reading of the code — the exact blind spot the golden exists to counter. The golden
+is field truth; a SPEC the agent writes about legacy code is a claim. So this skill emits
+facts, and the human infers meaning from them.
+
+If you catch yourself writing a requirement or a rationale, stop: that belongs to the human
+(and to `/uscha-adr-refine` for the FORWARD decisions), not here.
+
+## Phase 1 — Map (fact)
+
+Static analysis only. Extract, and write to `SYSTEM-MAP.md`:
+- **Boundaries**: every public endpoint / operation / message topic, with its contract
+  (request/response schema, status codes, idempotency where observable).
+- **Dependency graph**: who calls whom (service→service, module→module, DB, external APIs).
+  Flag cycles and hubs.
+- **Module candidates**: current package/service structure and natural seams (this is
+  observation of the CURRENT layout, NOT a proposal for the new one).
+Everything here must be traceable to code. No "this seems to…", no guessed intent.
+
+## Phase 2 — Characterize (fact)
+
+Capture the golden at the system boundaries by running the ORIGINAL code with REAL inputs.
+Delegate to the `uscha-characterize` skill; if it is not installed, follow its contract inline:
+- Write a deterministic capture harness (you MAY author the harness).
+- Normalize every non-determinism source before serializing: timestamps, seeds, map/set
+  iteration order, GUIDs/auto-increment, concurrency, **the target locale**, and use
+  deterministic serialization (sorted keys, fixed float precision, explicit encoding).
+- Run the capture → `.received`. **STOP.** Return control to the human to review and
+  approve the `.approved`.
+- **You NEVER create, rename, or edit a `.approved` file** (INV-GOLDEN-01). It is field
+  truth; only a human approves it.
+- Corpus in order of value: real/recorded production inputs → hand-built edge cases →
+  inputs of past bugs. A boundary whose corpus does not exercise its known branches is
+  marked **PARTIAL**, never covered.
+
+## Phase 3 — Summary (facts, no opinion)
+
+Write `DISCOVERY-SUMMARY.md`: the system map + the golden coverage report (which boundaries
+are captured and approved, which are PARTIAL and why). This is the fact base the human reads
+to write the migration SPEC. Do not editorialize.
+
+## What you do NOT do (the human's job)
+
+- Do NOT write a SPEC of the old system's behavior — the golden IS the executable spec.
+- Do NOT write ADRs of the old system's implicit decisions.
+- Do NOT decide the NEW structure (module boundaries, shared kernel, sync vs events). Those
+  are forward decisions → `/uscha-adr-refine`.
+
+## Guardrails
+
+- `.approved` files are sacred and human-approved; the agent is mechanically forbidden from
+  writing them (a `PreToolUse` hook on `**/*.approved.*` should enforce it).
+- `.gitattributes`: `*.approved.* binary` (line endings must not create false diffs).
+- Corpus insufficient → PARTIAL. Never claim coverage you did not exercise.
+
+## Convergence — finish when
+
+The map is complete (every boundary and dependency accounted for, or explicitly marked
+unknown), the golden is captured and **human-approved**, and the coverage report states
+what is covered vs PARTIAL. State plainly that the facts are ready, then hand off.
+
+## Handoff
+
+> "Read SYSTEM-MAP.md and DISCOVERY-SUMMARY.md, and inspect the approved golden. These are
+> FACTS about the current system. Now write the migration SPEC — behavior == golden,
+> structure == the new module boundaries — and take the partition decisions via /uscha-adr-refine.
+> Do not treat any of my output as a requirement or a rationale; those are yours to decide."
+
+Flow (migration): `uscha-reverse-discovery` (facts) → human writes SPEC + `/uscha-adr-refine` (forward
+module decisions) → `/uscha-devloop` (restructure; `golden-diff` + `ApplicationModules.verify()`
+stay green the whole way) → readiness + human gate.
+
+## Relationship to the other skills
+
+- **discovery** (greenfield): you PROPOSE the shape from an idea. **reverse-discovery**
+  (brownfield): you EXTRACT facts from a running system. Opposite direction, opposite trust
+  model.
+- **characterize**: the golden-capture sub-step this skill orchestrates in Phase 2.
+- **adr-refine**: where the FORWARD decisions (the new module boundaries) are taken — this
+  skill deliberately does not.
+
+## Why this skill is safe by construction
+
+It lives entirely on the FACTS side of the facts-vs-prose line: static analysis and
+byte-capture, both verifiable. Unlike a prose-heuristic gate, there is no interpretation to
+get wrong — so there is nothing fragile to break. If a step would require guessing, it has
+left this skill's scope.
+
+## Tracked-markdown protocol
+
+If `SYSTEM-MAP.md` / `DISCOVERY-SUMMARY.md` already exist and are tracked, ask for the
+current version before overwriting — never silently replace real progress.

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

@@ -0,0 +1,79 @@
+---
+name: uscha-rubric
+description: >
+  Grade the change against the versioned RUBRIC.md (the ACCEPTANCE of the
+  non-testable: conventions, error-handling sanity, API ergonomics, doc quality)
+  and ingest the verdict into the ledger. This skill is a THIN ADAPTER for
+  Claude Code: the portable core is templates/rubric-grader-prompt.md (works on
+  Codex, Gemini CLI, Cursor, raw API, or a human) + the vendor-neutral JSON
+  contract that `qa_ledger.py rubric-ingest` validates. Advisory by default;
+  gates only when the human declares it. Invoke for "grade the rubric",
+  "evaluá la rúbrica", "rubric pass".
+allowed-tools: Read, Write, Glob, Grep, Bash
+disable-model-invocation: false
+---
+
+# uscha-rubric — grade the non-testable against versioned criteria (adapter)
+
+**Architecture note (read this first).** You are the Claude Code ADAPTER of a
+vendor-neutral layer. The core is: `RUBRIC.md` (versioned criteria) + the JSON
+contract + `qa_ledger.py rubric-ingest` (stdlib, runs anywhere). ANY runner can be
+the grader — this skill just wraps the neutral prompt so Claude Code users get it
+in one command. Never add Claude-specific behavior to the contract.
+
+## Protocol
+
+1. **Locate the rubric**: `defaults.rubric.file` in `uscha.config.json`, else
+   `./RUBRIC.md`. If absent, offer to create one from `templates/RUBRIC.md` and STOP
+   (the criteria are the human's to approve — propose, don't impose).
+2. **Validate structure first** (facts block):
+
+```bash
+QL="./.claude/skills/uscha-devloop/qa_ledger.py"
+[ -f "$QL" ] || QL="$HOME/.codex/skills/uscha-devloop/qa_ledger.py"
+[ -f "$QL" ] || QL="$HOME/plugins/uscha/skills/uscha-devloop/qa_ledger.py"
+[ -f "$QL" ] || QL="$HOME/.claude/skills/uscha-devloop/qa_ledger.py"
+python3 $QL spec-check --rubric RUBRIC.md    # exit 1 = fix the rubric before grading
+```
+
+3. **Grade with ISOLATED context** — follow `templates/rubric-grader-prompt.md` to
+   the letter: read ONLY the diff + RUBRIC.md (not the maker's reasoning, not the PR
+   body). For every criterion emit `pass|fail`; **evidence `file:line` is mandatory
+   for any verdict that affects the score** (a positive's pass, a negative's fail) —
+   without it the engine discards the verdict. Anchors calibrate you; when in doubt,
+   fail (the optimist bias is the failure mode this layer exists to counter).
+4. **Write the contract JSON** to `reports/rubric-grade.json`:
+
+```json
+{"criteria": [{"id": "RB-01", "verdict": "pass",
+               "evidence": "src/x.py:42 — ...", "note": "..."}]}
+```
+
+5. **Ingest** (the ledger validates IDs, applies evidence-or-nothing, computes the
+   weighted score vs threshold, and persists — advisory by default):
+
+```bash
+python3 $QL rubric-ingest --repo <REPO> --report reports/rubric-grade.json \
+  --iteration <N>            # add --gate ONLY if the human declared it
+```
+
+A below-threshold score with the gate declared (config `defaults.rubric.gate: true`
+or `--gate`) blocks convergence and caps readiness ≤65 through the existing ledger
+plumbing. Without the declaration it advises — never silently escalate it yourself.
+
+## Non-negotiables
+
+- **Maker ≠ grader**: never grade a change you authored in this same context. Run
+  the grade in a fresh/isolated pass (that separation is the entire value).
+- **Evidence-or-nothing**: a verdict without a `file:line` citation does not count —
+  the engine enforces it, you comply with it.
+- The rubric file is the HUMAN's criterion: propose edits, never rewrite it silently
+  (tracked-markdown protocol applies).
+- This layer never replaces the hard gates (tests, golden, gate-check, simplicity):
+  it is the structured-guess layer — facts block, guesses advise.
+
+## Relationship to the other skills
+
+- `uscha-devloop` runs this in Phase 3b alongside gate-check when a rubric exists.
+- `uscha-discovery` / `uscha-adr-refine` are where the human's quality criteria
+  crystallize — a RUBRIC.md can be drafted there (step: quality bar).

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

@@ -0,0 +1,88 @@
+---
+name: uscha-sysdoc
+description: >
+  Generate a single self-contained, navigable HTML deck (PowerPoint-style, keyboard +
+  click navigation) documenting a system in two parallel tracks: a commercial/CEO view
+  and a technical view. Pulls real metrics from QA-LEDGER.json, includes inline SVG
+  diagrams, dark control-room aesthetic. Invoke for "document this system",
+  "make the system deck", "commercial + tech doc". Pairs with the dev-loop skill.
+allowed-tools: Read, Write, Glob, Grep, Bash
+disable-model-invocation: false
+---
+
+# sys-doc — two-view system deck generator
+
+Produce ONE self-contained `.html` file (no external assets, no CDN, no localStorage)
+that reads like a slide deck and documents the system on two tracks the reader can
+switch between at any time:
+
+- **Commercial / CEO track** — what the system does, the value, the risk posture, the
+  status. No code. Plain business language. Money/time/reliability framing.
+- **Technical track** — architecture, modules, data flow, contracts, QA results,
+  coverage, known deferred issues.
+
+## Inputs
+
+1. **Metrics (authoritative):** run the ledger summary and use its numbers verbatim —
+   never invent figures.
+
+```bash
+QL="./.claude/skills/uscha-devloop/qa_ledger.py"                      # instalacion por proyecto
+[ -f "$QL" ] || QL="$HOME/.codex/skills/uscha-devloop/qa_ledger.py"   # Codex raw-skills install
+[ -f "$QL" ] || QL="$HOME/plugins/uscha/skills/uscha-devloop/qa_ledger.py"  # Codex plugin install
+[ -f "$QL" ] || QL="$HOME/.claude/skills/uscha-devloop/qa_ledger.py"  # Claude global install
+python3 $QL summary --json > /tmp/qa-summary.json
+python3 $QL readiness --json > /tmp/qa-readiness.json
+```
+
+   From the summary use: `total_steps`, `by_tool`, `by_repo`, `aggregate`, `escalations`.
+   From readiness use: `score`, `status`, `cap_reason`, `dimensions`, `acceptance`,
+   `by_repo`. Render readiness as a **semaphore widget** at the top of slide 5 and as a
+   per-repo readiness column on the technical QA slide: green ≥80, amber 50–79, red <50,
+   and always print the `cap_reason` when a hard cap is active.
+
+2. **System understanding:** read the ADR/PLAN, CLAUDE.md, module layout, and key
+   contracts to describe architecture and value. If no ledger exists, ask whether to
+   proceed without QA metrics (the deck still works, just without the QA section).
+
+3. **Tracked-markdown protocol:** the HTML output itself is not tracked markdown, so
+   generate freely. But if asked to also update a tracked `.md`, ask for its current
+   version first.
+
+## Structure (each is one navigable slide)
+
+1. **Title** — system name, one-line purpose, date, run id.
+2. **Track switcher** — persistent toggle: Commercial ⇄ Technical (affects which
+   slides/sections show; default Commercial).
+3. Commercial: **What it does** (plain language, the job it removes).
+4. Commercial: **Value & status** (what's done, what's in flight, risk posture).
+5. Commercial: **Quality at a glance** — coverage %, tests count, a simple
+   "issues found and resolved" readout from `by_tool`. No jargon.
+6. Technical: **Architecture** — inline SVG: modules/repos as boxes, data flow as
+   arrows, external systems (DB, external APIs, devices) distinct.
+7. Technical: **Key contracts / interfaces** — the seams between repos/modules.
+8. Technical: **QA results** — per-tool table (reported / fixed / %fixed / deferred /
+   suppressed), coverage per repo, tests/kLOC, escalations list.
+9. Technical: **Deferred issues** — summarize `ISSUES-DEFERRED.md` honestly.
+10. **Smoke checklist** — the manual verification steps.
+
+## Build constraints
+
+- Single `.html`, all CSS/JS inline. Works opened directly from disk and deployable to
+  Cloudflare Pages / S3 as-is.
+- **No localStorage / sessionStorage** (won't run in some sandboxes). Hold nav state in
+  JS variables only.
+- Navigation: arrow keys (← →), on-screen prev/next, a slide index/dots, and Esc for an
+  overview grid. Slide counter visible.
+- Diagrams are hand-authored inline `<svg>` using `currentColor`/CSS variables so they
+  theme with the deck. No raster images, no external diagram libs.
+- Aesthetic: dark control-room (deep neutral background, one accent, high-contrast
+  mono for technical figures), but keep the Commercial track clean and uncluttered.
+- Accessible: semantic headings, `aria-label`s on nav controls, visible focus, contrast
+  AA. Readable when printed (print stylesheet flattens slides to a linear document).
+
+## Output
+
+Write to `docs/system-deck.html` (or the path the human gives). Then state the file
+path and the two or three things the reader should look at first. Do not paste the HTML
+into chat — present the file.

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

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "uscha",
+  "version": "1.40.1",
+  "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": {
+    "name": "Andres Massello",
+    "url": "https://github.com/andresmassello"
+  },
+  "homepage": "https://github.com/andresmassello/uscha",
+  "repository": "https://github.com/andresmassello/uscha",
+  "license": "MIT",
+  "keywords": [
+    "spec-driven",
+    "qa",
+    "gates",
+    "golden-testing",
+    "readiness",
+    "methodology"
+  ],
+  "skills": "./.claude/skills/",
+  "hooks": "./hooks/hooks.json"
+}

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

@@ -0,0 +1,37 @@
+{
+  "name": "uscha",
+  "version": "1.40.1",
+  "description": "Uscha spec-driven development methodology for coding agents. Includes npm/npx router.",
+  "author": {
+    "name": "Andres Massello",
+    "url": "https://github.com/andresmassello"
+  },
+  "homepage": "https://github.com/andresmassello/uscha",
+  "repository": "https://github.com/andresmassello/uscha",
+  "license": "MIT",
+  "keywords": [
+    "spec-driven",
+    "qa",
+    "gates",
+    "golden-testing",
+    "readiness"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Uscha",
+    "shortDescription": "Spec-driven development with fact gates and readiness.",
+    "longDescription": "Uscha installs discovery, ADR, characterization, devloop, rubric, sysdoc and Mirador skills plus the qa_ledger.py evidence engine.",
+    "developerName": "Andres Massello",
+    "category": "Productivity",
+    "capabilities": [
+      "Write",
+      "Interactive"
+    ],
+    "defaultPrompt": [
+      "Run Uscha discovery for this feature.",
+      "Use Uscha devloop to verify this change.",
+      "Show the Uscha readiness for this repo."
+    ],
+    "brandColor": "#7C3AED"
+  }
+}

package/uscha-kit/CHANGELOG-1.10.0.md

@@ -0,0 +1,84 @@
+# dev-loop-kit 1.10.0 — acceptance trazable: AC-n cierra por testcase MEDIDO (2026-07-02)
+
+Primera mejora del backlog PragProg (M2 de `docs/analisis-pragmatic-programmer.md`;
+Topic 50 "Do What Works" + la anécdota Jeffries/Sudoku + Tip 94 "Find Bugs Once").
+Ataca el modo de falla típico del agente: **pulir la métrica sin acercarse a la
+solución**. El readiness deja de estar dominado por coverage/tests-verdes y pasa a
+estar dominado por **criterios de aceptación cerrados con evidencia medida**.
+Smoke suite: 68/68.
+
+## La idea (measured beats narrated, ahora a nivel CRITERIO)
+
+- Cada criterio de `ACCEPTANCE.md` lleva un ID estable: `- [ ] AC-01 — cuando X
+  entonces Y`.
+- Un criterio cierra **MEDIDO** solo cuando existe ≥1 testcase VERDE cuyo nombre
+  lleva el tag (`test_ac1_x`, `testAC01X`, `"AC-01: ..."`) en los reportes JUnit
+  que el engine ya ingiere — y **ningún** testcase taggeado en rojo (evidencia
+  roja veta: fail-closed).
+- El checkbox es RELATO; el testcase es HECHO. Un `[x]` sin test verde se
+  reporta como `narrated_only` y NO cierra.
+
+## Engine (qa_ledger.py)
+
+- `_parse_acceptance_items()`: parser de checkboxes con ID opcional; IDs
+  normalizados por número (`AC-01 == AC_1 == ac1` — los nombres de test de
+  python/go no admiten `-`).
+- `_ac_tags()`: scan de NOMBRES de testcase en los reportes JUnit por type
+  (reusa el selector de ubicaciones vía `_junit_report_files()`, extraído para
+  no duplicar la lista — surefire/gradle per-clase, junit-family, dual-file
+  swift; flutter no emite JUnit → sus criterios no cierran medido, documentado).
+  Boundaries explícitos en el regex del tag: `\b` NO sirve (`_` es word char y
+  `test_ac1` quedaría invisible); soporta separador no-alfanumérico y camelCase.
+- `readiness`: nueva dimensión **acceptance** (dominante, peso 30) = criterios
+  cerrados medidos / criterios totales (un criterio sin ID no puede cerrar →
+  cuenta como abierto). Pesos default rebalanceados:
+  acceptance 30 · adr 15 · coverage 15 · static 20 · convergencia 10 ·
+  integración 10 — el techo a coverage/verde es el anti-Goodhart. JSON expone
+  `traceable/ids/measured_closed/narrated_only/measured_unchecked/untagged`;
+  warnings en texto para narrated-only y sin-IDs.
+- **Fallback legacy**: ACCEPTANCE sin ningún AC-ID → la dimensión cae al ratio
+  de checkboxes con warning (adopción incremental, no rotura retroactiva).
+- `spec-check --acceptance ACCEPTANCE.md`: la trazabilidad es estructura =
+  FACT → bloquea: archivo ausente, cero criterios, CERO criterios trazables,
+  IDs duplicados (normalizados). Criterios sueltos sin ID = advisory. Puede
+  correr solo (sin `--spec`).
+
+## Skills / docs
+
+- `discovery`: ACCEPTANCE se genera con AC-NN secuenciales, nunca reusados;
+  cada criterio pensado para ser cubrible por un test con nombre.
+- `dev-loop`: al escribir los tests de un criterio, el tag AC-n va en el nombre
+  del test; `spec-check --acceptance` al arrancar.
+
+## Hardening (review fresco pre-commit, 10 hallazgos aplicados)
+
+- `_ac_tags`: el tag ahora lee SOLO el nombre del testcase (nunca classname) —
+  un módulo/clase que matchea "ACn" por coincidencia (`test_ac3_flow.py`) ya no
+  contamina los OTROS tests del mismo archivo.
+- `_AC_ID`: tolera IDs markdown-formateados (`**AC-01**`, `` `AC-01` ``) — antes
+  degradaban en silencio a `id=None` y toda la trazabilidad caía a legacy.
+- `readiness`: IDs duplicados en ACCEPTANCE cuentan **una sola vez** (antes un
+  test verde podía cerrar "medido" tantos criterios como copias del ID).
+- `readiness`: config pre-1.10.0 con `readiness_weights` explícitos que no
+  conocían `acceptance` ya no la reciben inyectada por default — se excluye
+  (peso 0) con warning hasta que el usuario la agregue o taggee AC-IDs (si no,
+  duplicaba el peso de `adr` en silencio).
+- `readiness`: `--section` sin match ahora avisa (`0 criterios en scope`) en
+  vez de zonear en silencio adr+acceptance.
+- `readiness`: ledger sin `config.repos` ya no crashea (KeyError) — usa
+  `.get("repos", [])` como el resto del comando.
+- `spec-check --acceptance`: pipear un SPEC por stdin junto con `--acceptance`
+  ya no se descarta en silencio — se lee stdin salvo modo interactivo puro
+  acceptance-only.
+- `spec-check --acceptance --strict`: los criterios sin AC-ID ahora gatean
+  `--strict` (antes el verdict imprimía "OK" con advisories pendientes).
+- Documentado (no resuelto): reportes JUnit stale de maven/gradle pueden
+  vetear/cerrar un AC sin evidencia vigente — mismo límite que
+  `junit_test_count`, ahora con blast radius mayor. Mitigación real (mtime +
+  correlación con el árbol de fuentes) diferida.
+
+## Diferido consciente
+
+- El resto del backlog PragProg (M1 regression-capture, M3 ledger atómico,
+  M8 secret-scan, M9 tests fuera del presupuesto de simplicity, etc.) sigue en
+  `docs/analisis-pragmatic-programmer.md` — una mejora por release.

package/uscha-kit/CHANGELOG-1.11.0.md

@@ -0,0 +1,67 @@
+# dev-loop-kit 1.11.0 — tests fuera del presupuesto de simplicity (2026-07-03)
+
+Segunda mejora del backlog PragProg (M9 de `docs/analisis-pragmatic-programmer.md`;
+Topic 51: *"un buen proyecto puede tener MÁS código de test que de producción, y
+vale la pena"*). Elimina un **incentivo perverso activo**: el simplicity-check
+contaba las líneas de test junto a las de producción contra un único presupuesto —
+el gate castigaba escribir tests y empujaba al agente a testear menos para pasar.
+Smoke suite: 73/73.
+
+## La idea
+
+- Escribir tests **nunca** acerca un diff a OVERBUILT. Los archivos de test se
+  detectan, se cuentan y se **reportan aparte** (`test_lines_added`,
+  `test_files_changed`) — pero no gatean ninguna dimensión del score.
+- La otra dirección ya estaba protegida: **borrar** tests lo bloquea gate-check.
+  Con esto el incentivo queda alineado en ambas direcciones.
+
+## Engine (qa_ledger.py)
+
+- `_is_simplicity_test_file()`: clasificador type-agnóstico (el diff no trae
+  `repo_type`) — unión de las convenciones de los 9 stacks: dirs
+  `test/tests/__tests__/Tests/*.Tests`, source sets Gradle (`src/*Test/`),
+  `test_*.py`, `*_test.go`, `*.test.ts`/`*.spec.js` (multi-dot incluido),
+  `*Test.java`/`*Tests.cs` CamelCase **case-sensitive** — `backtest.cpp` /
+  `protest.cc` siguen contando como producción (misma trampa que ya evitan
+  dotnet/cpp en `_is_test_path`).
+- Dirección de fallo benigna y documentada: un falso positivo solo EXIME del
+  presupuesto — nunca bloquea ni borra nada.
+- `_simplicity_metrics()`: tercer estado de conteo (`prod`/`test`/fuera);
+  las líneas de test no alimentan `lines_added`, `net_lines`, `files_changed`,
+  `max_nesting`, `max_hunk_added` ni abstracciones. Output humano: línea
+  informativa "tests FUERA del presupuesto: +N líneas en M archivo(s)".
+
+## Smoke
+
+- **T32**: diff sintético 6 líneas prod + 302 de test → el presupuesto ve 6/1;
+  batería del clasificador (9 convenciones positivas + backtest/protest/Engine
+  negativas).
+- **T31** (edges 1.10.0, deuda del release anterior): batería de falsos
+  positivos del tag regex (`HVAC2`, `mac1`, `track12` no taggean), classname
+  jamás taggea, y semántica flaky de surefire (`<flakyFailure>` que pasó tras
+  retry = verde; `<failure>`+`<rerunFailure>` = rojo, veta).
+
+## Hardening (review fresco pre-commit)
+
+- El review detectó que gate-check tenía SU PROPIO clasificador de tests
+  (`_gc_is_test_file`) más débil: no reconocía `foo_test.go` (Go),
+  `*.Tests/*.cs` (dotnet), `*.spec.tsx` ni `__tests__/` — así que "borrar
+  tests lo bloquea gate-check" era overclaim para 4+ stacks. Fix: unión
+  fail-closed — gate-check reusa el clasificador compartido de los 9 stacks
+  MÁS sus sufijos legacy; solo se AMPLÍA qué cuenta como test, ningún path
+  antes protegido se desprotege.
+- `_GC_TESTDEF` ampliado con las definiciones de test que faltaban:
+  `func TestX` (Go), `[Fact]`/`[Theory]` (xunit), `#[test]` (rust),
+  `it(`/`test(`/`describe(` (js) — seguro porque TESTDEF solo se evalúa
+  dentro de archivos ya clasificados como test.
+- Smoke **T33**: borrado de tests Go/dotnet/JS → BLOCKER (antes invisible).
+- Corrección truth-pass en `dev-loop-kit/README.md`: los pesos documentados
+  de simplicity (`diff_size 30, nesting 25, abstraction 20...`) no coincidían
+  con el engine (`35/30/20/8/7`, abstraction advisory sin peso) — drift
+  pre-existente, alineado acá.
+
+## Diferido consciente
+
+- El resto del backlog PragProg (M1 regression-capture, M3 ledger atómico,
+  M8 secret-scan, etc.) sigue en `docs/analisis-pragmatic-programmer.md` —
+  una mejora por release.