@andresmassello/uscha 1.40.1

package/uscha-kit/CHANGELOG-1.12.0.md

@@ -0,0 +1,46 @@
+# dev-loop-kit 1.12.0 — secret-scan en gate-check (2026-07-03)
+
+Tercera mejora del backlog PragProg (M8 de `docs/analisis-pragmatic-programmer.md`;
+Topic 43 *"Stay Safe Out There — nunca commitear secretos, API keys ni
+credenciales"*). Un secreto agregado al diff bloquea como HECHO, exactamente
+igual que hoy bloquea borrar tests o bajar thresholds. Python stdlib puro.
+Smoke suite: 79/79.
+
+## La idea (facts block, guesses advise — aplicado a secretos)
+
+- **Alta precisión = BLOCKER**: clave privada PEM, AWS access key (`AKIA…`),
+  GitHub token (`ghp_`/`github_pat_`), Slack (`xox?-`), Google API key
+  (`AIza…`), y archivos contenedores de claves (`.p12/.pfx/.jks/.keystore/.key`)
+  agregados o modificados — también en modo binario (línea `Binary files`,
+  que no trae `+++`).
+- **Genérico = advisory**: literales tipo `password = "…"` y JWTs — en
+  fixtures de test abundan placeholders y bloquearlos castigaría escribir
+  tests. `--strict` los gatea.
+- Solo se escanean líneas **agregadas**: sacar un secreto del código es bueno
+  y el diff que lo saca no debe frenarse. Borrar un `.p12` tampoco bloquea
+  (el lado `b/` del diff es `/dev/null` y no matchea).
+
+## Engine (qa_ledger.py)
+
+- `_GC_SECRETS_HARD` (lista etiquetada de patrones) + `_GC_SECRET_SOFT` +
+  `_GC_KEYFILE`, cableados al loop de `cmd_gate_check`: `secrets_added` suma
+  al veredicto hard, `secret_literals` al soft. JSON expone ambos.
+- Los patrones no se auto-matchean como source (verificado): después de
+  `-----BEGIN ` en el código viene `(?:RSA`, no `PRIVATE KEY`.
+- Límite conocido (corner self-hosting): los fixtures del smoke contienen la
+  AKIA de ejemplo canónica de AWS — un gate-check del diff del PROPIO kit
+  la flaggea. Correcto: el gate no exime archivos de test a propósito
+  (un secreto en un test sigue siendo un secreto).
+
+## Smoke
+
+- **T34**: AKIA agregada → BLOCKER · PEM privado → BLOCKER · `.p12` binario
+  agregado → BLOCKER · borrado de `.p12` → CLEAN · literal password →
+  REVIEW exit 0 / `--strict` exit 1.
+
+## Diferido consciente
+
+- Entropía/base64 genérico (detectores adivinos) NO entra: violaría
+  "facts block, guesses advise" — solo patrones con lectura inequívoca
+  bloquean. El resto del backlog PragProg sigue en
+  `docs/analisis-pragmatic-programmer.md`.

package/uscha-kit/CHANGELOG-1.13.0.md

@@ -0,0 +1,33 @@
+# dev-loop-kit 1.13.0 — ledger atómico: checksum de integridad (2026-07-03)
+
+Cuarta mejora del backlog PragProg (M3 de `docs/analisis-pragmatic-programmer.md`;
+Topic 34 *"los recursos compartidos mutables incluyen ARCHIVOS"*). Todo el
+edificio "measured beats narrated" se apoya en `QA-LEDGER.json` — y hasta hoy
+ese JSON podía corromperse o mutarse en silencio. Smoke suite: 85/85.
+
+## La idea
+
+- La **escritura ya era atómica** (write-temp + `os.replace`, desde antes) —
+  lo que faltaba era el otro lado: detectar al CARGAR que el archivo quedó
+  inconsistente.
+- `_save` ahora escribe un campo `integrity` con **sha256 canónico** del
+  contenido (claves ordenadas — el hash no depende del orden del dict).
+- `_load` **verifica** el checksum cuando el campo existe: una mutación externa
+  (edición a mano, merge accidental) o una escritura parcial **bloquea** con
+  mensaje de recuperación (`git checkout -- QA-LEDGER.json`). Aceptar una
+  edición externa deliberada = borrar el campo `integrity` (acto humano
+  explícito, mismo espíritu que INV-GOLDEN-01).
+- JSON corrupto/truncado = hecho bloqueante con mensaje claro, **no un
+  traceback crudo**.
+- **Legacy**: ledgers pre-1.13.0 sin `integrity` cargan sin verificar
+  (adopción incremental, no rotura retroactiva). `init` re-inicializa sobre
+  un ledger corrupto sin leerlo.
+
+## Diferido consciente
+
+- File-lock inter-proceso (la parte "opcional" de M3): omitido — stdlib
+  portable Windows/Linux no lo da barato (`fcntl` no existe en Windows) y el
+  loop es single-writer por diseño. Si aparece un caso real de escritura
+  concurrente, se re-evalúa.
+- El baseline de `rebuild` (artefacto aparte) no lleva checksum — mismo
+  candidato si el rebuild gana peso.

package/uscha-kit/CHANGELOG-1.14.0.md

@@ -0,0 +1,42 @@
+# dev-loop-kit 1.14.0 — plateau y stop-signal en readiness (2026-07-03)
+
+Quinta mejora del backlog PragProg (M6 de `docs/analisis-pragmatic-programmer.md`;
+Topic 37 *"Listen to Your Lizard Brain"* + Topic 5 *"Know When to Stop"*).
+La convergencia per-tool existía, pero el engine nunca decía las dos cosas que
+un senior sí dice: "esto no está convergiendo — el problema es de diseño" y
+"esto ya está — cortá". **ADVISORY puro: recomienda, jamás gatea.**
+Smoke suite: 89/89.
+
+## La idea
+
+- **stall-check**: findings gateados por CICLO de agente (suma sobre las tools
+  del ciclo). Si los últimos 3 ciclos muestran la serie plana o SUBIENDO — y
+  todavía hay findings — iterar más no está acercando la solución: el engine
+  deja de sugerir implícitamente "seguí iterando" y recomienda **volver a
+  ADR / re-planear con el humano**. Una serie bajando es progreso y no dispara.
+  Con `qa_tools_order` configurado solo cuentan ciclos **COMPLETOS** (todas las
+  tools logueadas) — un ciclo a medio correr suma parcial y podría enmascarar
+  o inventar el stall (hallazgo del review fresco, aplicado).
+- **stop-signal**: todos los repos convergieron, cero caps activos y cero
+  findings gateados abiertos — no queda ningún fact bloqueante. Lo que falte
+  es deuda medible (coverage/acceptance), no findings: **candidato a cortar e
+  ir a PR**, decisión del humano.
+
+## Engine (qa_ledger.py)
+
+- `_stall_series()` / `_is_stalled()` (ventana `STALL_WINDOW = 3`, constante:
+  es un advisory, no un gate parametrizable — cf. tensión ETC/M5, deliberado).
+- `readiness`: JSON expone `advice: {stalled_repos, stop_signal}`; el texto
+  imprime ambos avisos marcados "(advisory)".
+
+## Smoke
+
+- **T36**: serie 4→5→6 dispara stall · un ciclo 4 PARCIAL no contamina la
+  serie · serie 5→3→1 (progreso) NO dispara · repo único convergido con cero
+  facts bloqueantes emite `stop_signal: true`.
+
+## Diferido consciente
+
+- El stall mide findings gateados por ciclo, no el score de readiness
+  persistido por iteración (el ledger no guarda score histórico — si algún
+  día lo guarda, el detector puede leer el KPI directo).

package/uscha-kit/CHANGELOG-1.15.0.md

@@ -0,0 +1,58 @@
+# dev-loop-kit 1.15.0 — scrub del golden master (2026-07-03)
+
+Sexta mejora del backlog PragProg (M7 de `docs/analisis-pragmatic-programmer.md`;
+Topic 41 *"no apoyar tests en cosas no confiables"* — timestamps exactos,
+ids, posiciones absolutas). Sin esto, cualquier salida del código original con
+volátiles vuelve el golden master perma-rojo — y un golden perma-rojo mata la
+credibilidad de todo el gate. Smoke suite: 97/97.
+
+## La idea
+
+- `golden.scrub.json` en el root de fixtures declara los volátiles:
+  `{"rules": [{"pattern": "<regex>", "replace": "<placeholder>"}]}`.
+- `golden-diff` enmascara AMBOS lados (received y approved) antes de comparar —
+  solo texto; el binario sigue byte a byte. El match vía scrub se reporta
+  **APARTE** (`N via scrub` + conteo de sustituciones por regla): el masking
+  jamás es invisible.
+- **Cadena de custodia**: las reglas se declaran en characterize (paso nuevo,
+  ANTES de la aprobación) y el humano las aprueba junto con los `.approved` —
+  son contrato. gate-check flaggea cualquier edición posterior a
+  `golden.scrub.json` como señal blanda SIEMPRE visible (`--strict` la gatea):
+  una regla ensanchada puede enmascarar divergencia real.
+- Archivo de scrub inválido (JSON roto, regex rota) = **exit 2 explícito** —
+  el scrub nunca se saltea en silencio.
+- Preferencia documentada: arreglar el determinismo EN LA FUENTE (checklist de
+  Phase 2 de characterize); el scrub es para lo que genuinamente no se controla.
+
+## Engine (qa_ledger.py)
+
+- `_load_scrub_rules()` / `_scrub()` + integración en `cmd_golden_diff`
+  (`matched_scrubbed`, `scrub_rules`, `scrub_substitutions` en el JSON —
+  el conteo es del lado RECEIVED; sumar ambos lados duplicaría cada volátil).
+- gate-check: lista `scrub_rules_touched` (soft) en veredicto y JSON — cubre
+  agregar, modificar y BORRAR el archivo (borrar reglas también es editarlas).
+- Shape estricta del archivo: top-level lista, key `rules` ausente o typo =
+  exit 2 — un error de forma no puede degradar a "cero reglas" en silencio.
+
+## Hardening (review fresco pre-commit, 4 hallazgos aplicados)
+
+- AttributeError cruda con lista top-level en el scrub file → exit 2 limpio.
+- `{}` sin key `rules` cargaba cero reglas en silencio → exit 2.
+- Doble conteo de sustituciones (received + approved al mismo dict) → solo
+  received.
+- Borrado de `golden.scrub.json` no se flaggeaba (el check vivía solo en
+  líneas `+`) → también en `-`.
+
+## Smoke
+
+- **T37** — respetando INV-GOLDEN-01: crear un `.approved` es un acto HUMANO
+  incluso en tests, así que el path CLEAN-vía-scrub NO se auto-testea (misma
+  disciplina que el path CLEAN byte-a-byte desde 1.3.0). Se prueba la mecánica
+  a nivel función (enmascara, cuenta, binario intacto, divergencia real no se
+  tapa) + los paths CLI sin `.approved`: scrub no fabrica aprobación (DIVERGE
+  se mantiene), scrub inválido exit 2, gate-check flaggea ediciones.
+
+## Diferido consciente
+
+- Reglas por-fixture (hoy son por root de fixtures) — si un corpus real lo
+  pide, se agrega `"glob"` opcional por regla.

package/uscha-kit/CHANGELOG-1.16.0.md

@@ -0,0 +1,55 @@
+# dev-loop-kit 1.16.0 — regression-capture: Find Bugs Once (2026-07-03)
+
+Séptima mejora del backlog PragProg (M1 de `docs/analisis-pragmatic-programmer.md`;
+Topic 51 / Tip 94 *"Find Bugs Once"* + Tip 31 *"Failing Test Before Fixing
+Code"*). Ataca el cierre narrado de findings: el agente reporta `fixed` y nadie
+pregunta **qué test reproduce el bug que dice haber arreglado**.
+Smoke suite: 106/106.
+
+## La idea (measured beats narrated, ahora sobre el CIERRE)
+
+- `regression-check --repo X [--fixed N] --diff/--from-git`: cruza los findings
+  cerrados con el diff que los arregla. Verdicts:
+  - **N/A** — nada cerrado, nada que exigir.
+  - **MEASURED** — el diff agrega/modifica líneas en el árbol de test
+    (clasificador compartido de los 9 stacks).
+  - **NARRATED** — desaparecieron findings sin tocar UN solo test. Aconseja
+    por default (exit 0 con warning); `--strict` gatea; `log-gate --kind
+    regression --verdict fail` lo persiste si el equipo decide bloquear.
+- Sin `--fixed` explícito lee la suma de `fixed` de la iteración más reciente
+  del repo en el ledger — el dato ya estaba, ahora se interroga.
+- **escape_analysis obligatoria**: resolver un `flag-blocker` ahora EXIGE
+  `--escape-analysis "<qué gate/test debió atraparlo y qué se hizo>"` —
+  la reflexión es parte del cierre, no opcional (cerrar un BLOCKER sin ella
+  es garantía de encontrarlo dos veces). Se persiste en el registro del gate.
+
+## Decisiones de diseño (documentadas, no implícitas)
+
+- La evidencia es a nivel **DIFF** y es mecánica: ¿el diff que arregla agrega
+  líneas NO VACÍAS en el árbol de test? — un hecho. El mapeo finding→test
+  específico sería adivinanza sin una convención de naming
+  (¿`test_regr_<fingerprint>`?): **diferido consciente**, el gate mide lo que
+  se puede medir sin inventar.
+- **Límite disclosed (hallazgo del review fresco, aplicado)**: es un tripwire,
+  no un juez de calidad — una línea de comentario en un test file cuenta como
+  evidencia (juzgar contenido entre 9 lenguajes sería adivinanza). Mitigación
+  honesta: las líneas en blanco NO cuentan, y las señales
+  `has_test_definition`/`has_assertion` se exponen como hechos en el JSON —
+  un MEASURED sin ninguna de las dos imprime "evidencia DÉBIL" para el ojo
+  humano. La calidad de los tests la juzga pit-check (mutation testing), no
+  este gate.
+- Advisory-first: NARRATED no bloquea por default — mismo patrón de adopción
+  incremental que acceptance trazable (1.10.0) y los advisories de 1.14.0.
+
+## Skills
+
+- `dev-loop`: tras loguear un pass con `--fixed > 0`, correr `regression-check`;
+  cierre NARRATED = escribir el test de regresión (el test que falla va ANTES
+  del fix).
+
+## Smoke
+
+- **T38**: fix sin tests → NARRATED (exit 0 advisory / `--strict` exit 1) ·
+  fix con test nuevo → MEASURED (pasa aun con `--strict`) · `--fixed 0` → N/A ·
+  lookup del `fixed` de la última iteración del ledger sin `--fixed`.
+- **T4 endurecido**: resolver un blocker sin `--escape-analysis` → rechazado.

package/uscha-kit/CHANGELOG-1.17.0.md

@@ -0,0 +1,44 @@
+# dev-loop-kit 1.17.0 — procedencia visible de umbrales (2026-07-03)
+
+Octava mejora del backlog PragProg (M5 de `docs/analisis-pragmatic-programmer.md`;
+Tip 8 *"Make Quality a Requirements Issue"* + Topic 8 *"ETC es un valor, no una
+regla"*). Resolución elegida por el humano entre tres opciones: **procedencia
+visible** — ni fiel-al-libro (advisory por default hubiera desarmado el
+anti-Goodhart) ni rechazo. Smoke suite: 111/111.
+
+## La idea (el conteo es hecho · el umbral es opinión · salvo que lo declares)
+
+- **Que el cap EXISTA es principio, no opinión**: "tests rojos ⇒ no estás
+  ready" es una definición. Los caps siguen mordiendo por default — nada se
+  afloja, ningún usuario existente ve su score subir en silencio.
+- **El NÚMERO es opinión del kit SALVO que el humano lo declare.** El acto de
+  declaración ya existía: el `dev-loop.config.json` commiteado es humano-owned.
+  Valor explícito en `config.defaults` = requerimiento; fallback a la
+  constante del engine = default del kit. Cero schema nuevo.
+- Lo que faltaba era la **etiqueta**: ahora cada umbral que muerde dice de
+  dónde vino.
+
+## Engine (qa_ledger.py)
+
+- `readiness`: el cap que muerde se etiqueta — `capped at 35: tests red —
+  umbral default del kit` vs `— umbral requerimiento (config)`. El threshold
+  de coverage se etiqueta en la línea resumen (`thr 60, declarado` /
+  `default del kit`). JSON expone `cap_source` y `thresholds_declared`.
+- `simplicity-check`: los presupuestos declarados (config o CLI) llevan `*`
+  en la tabla; sin ninguno declarado imprime el aviso "todos los presupuestos
+  son defaults del kit — opinión, no requerimiento". JSON expone
+  `budgets_declared`.
+
+## Skills
+
+- `discovery`: paso 9 nuevo en la agenda — **quality bar**: "¿qué nivel de
+  calidad BASTA acá y qué dimensiones son negociables?" con propuesta acorde
+  al perfil de riesgo (un core de pagos no es un dashboard interno). Lo que el
+  humano declara va al config — declarar ES commitear el config.
+
+## Smoke
+
+- **T39**: cap declarado (`readiness_caps.tests_red` en config) → etiqueta
+  `requerimiento (config)` en JSON y texto · sandbox sin caps declarados →
+  lista vacía · simplicity sin declarar → aviso de opinión · presupuesto por
+  CLI → listado en `budgets_declared`.

package/uscha-kit/CHANGELOG-1.18.0.md

@@ -0,0 +1,42 @@
+# dev-loop-kit 1.18.0 — phase: la FSM derivada del workflow (2026-07-03)
+
+Novena mejora del backlog PragProg (M4 de `docs/analisis-pragmatic-programmer.md`;
+Topic 29 *"Juggling the Real World"* — FSM como tabla de datos). Resuelta con
+decisión humana explícita entre tres opciones: **FSM derivada** (ni la FSM
+declarada del análisis original, ni solo-pr-gate, ni diferir).
+Smoke suite: 117/117.
+
+## La idea (measured beats narrated, aplicado a la FSM misma)
+
+- El reframe clave: una FSM donde el agente DECLARA "entro a build/qa" es
+  **estado narrado** — exactamente lo que el kit combate. Acá el estado se
+  **COMPUTA** de los hechos del ledger; no existen transiciones ilegales que
+  validar porque no hay nada que declarar.
+- Reglas de derivación (precedencia): **escalated** (escalación abierta — el
+  acto humano pendiente pisa todo) → **pr-ready** (convergencia + tests verdes
+  medidos + 0 BLOCKER/CRITICAL) → **qa** (pasos registrados sin converger) →
+  **build** (snapshots medidos, sin QA) → **plan** (ledger virgen).
+- La "tabla de estados × eventos" del análisis original se convierte en estas
+  reglas de derivación — documentadas en el código como datos, no prosa.
+
+## Engine (qa_ledger.py)
+
+- `phase --repo X` (subcomando 21): imprime el estado derivado CON su
+  evidencia. `--require pr-ready` sale 1 si los hechos no alcanzan, listando
+  exactamente qué falta ("el estado no se negocia, se construye"). JSON:
+  `{phase, evidence, required, satisfied}`.
+- `dev-loop` Phase 6: el PR se gatea con `phase --require pr-ready` ANTES de
+  abrirse — la transición ilegal "PR sin convergencia" del análisis original
+  ahora es un hecho bloqueante mecánico, que era todo el punto de M4.
+
+## Smoke
+
+- **T40**: ciclo de vida completo derivado — virgen→plan · snapshot→build ·
+  QA sin converger→qa · pr-ready con findings abiertos→exit 1 · escalación
+  abierta→escalated (pisa todo) · convergido+limpio→pr-ready.
+
+## Diferido consciente
+
+- El estado es per-repo; un estado agregado feature-level (todos los repos
+  pr-ready + integración verde) se deriva componiendo — si el dogfooding lo
+  pide como comando propio, se agrega.

package/uscha-kit/CHANGELOG-1.19.0.md

@@ -0,0 +1,41 @@
+# dev-loop-kit 1.19.0 — spikes formales: descartable por contrato (2026-07-03)
+
+Décima y ÚLTIMA mejora del backlog PragProg (M10 de
+`docs/analisis-pragmatic-programmer.md`; Tip 21 *"Prototype to Learn"* +
+Topic 37 *"It's Playtime!"*). Con esta release, **las 10 mejoras del cruce con
+The Pragmatic Programmer están resueltas** — 8 implementadas directas y 2
+resueltas con decisión humana explícita entre opciones (M5 procedencia, M4 FSM
+derivada). Convención elegida por el humano: prefijo **`spike/*`**.
+Smoke suite: 121/121.
+
+## La idea (la versión ejecutable de "make it clear this code is disposable")
+
+- Un riesgo de incertidumbre ALTA en discovery dispara la pregunta: "¿amerita
+  un spike time-boxed antes de congelar la SPEC?" (paso 10 de la agenda).
+- El spike corre en una rama `spike/*` y su ÚNICO output legítimo es un
+  **ADR con lecciones** — hechos que alimentan la SPEC, jamás código mergeable.
+- El contrato es ejecutable, estilo INV-GOLDEN-01: `phase --require pr-ready`
+  **rechaza cualquier rama `spike/*`** aunque los hechos del ledger den
+  pr-ready — "escribí el ADR y arrancá limpio en una rama normal". Sin
+  `--require` solo informa (consultar no gatea). Resuelve la tensión con
+  Stone Soup sin romper spec-first.
+
+## Engine (qa_ledger.py)
+
+- `_spike_branch()`: `git symbolic-ref --short -q HEAD` (funciona antes del
+  primer commit; detached HEAD o directorio sin git = sin veto, disclosed).
+- `phase --require pr-ready`: veto de spike ANTES del veredicto; JSON expone
+  `spike_branch`.
+
+## Smoke
+
+- **T41**: repo pr-ready por hechos PERO en `spike/*` → exit 1 con el mensaje
+  del contrato · consulta sin `--require` → informa sin gatear · rama normal
+  → pr-ready vuelve a pasar.
+
+## El backlog PragProg, cerrado
+
+M2 (1.10.0) · M9 (1.11.0) · M8 (1.12.0) · M3 (1.13.0) · M6 (1.14.0) ·
+M7 (1.15.0) · M1 (1.16.0) · M5 (1.17.0) · M4 (1.18.0) · M10 (1.19.0).
+Cada release: smoke verde → review fresco → hallazgos aplicados → triple
+sync → commit único. Lo diferido consciente de cada una vive en su CHANGELOG.

package/uscha-kit/CHANGELOG-1.2.2.md

@@ -0,0 +1,16 @@
+# dev-loop-kit 1.2.2
+
+## Fixes (simplicity-check)
+- **[BLOCKER] `--from-git` crasheaba en Windows** — `subprocess.run` sin `encoding`
+  decodificaba el diff con cp1252 y reventaba (UnicodeDecodeError → None.splitlines).
+  Fix: `encoding="utf-8", errors="replace"`.
+- **Salida en mojibake en consola Windows** — `main()` fuerza `stdout/stderr` a UTF-8.
+- **No filtraba por tipo de archivo** — medía docs/config/resources como código
+  (inflaba lines/nesting; falsos OVERBUILT). Ahora solo cuenta código
+  (`_SIMPLICITY_CODE_EXT` + `SKIP_DIRS`), y reporta cuántos archivos salteó.
+
+## Nuevo: `pit-check` (mutation testing)
+- Gate de EFECTIVIDAD de tests (coverage miente): ingesta el `mutations.xml` de PIT,
+  reporta mutation score + **test-strength** (matados/cubiertos) + hotspots.
+- Invariante **Tests efectivos** agregada a `templates/CONSTITUTION.md`.
+- Tier scheduled/incremental (PIT es caro), no inner loop.

package/uscha-kit/CHANGELOG-1.2.3.md

@@ -0,0 +1,20 @@
+# dev-loop-kit 1.2.3
+
+## Fixes (qa_ledger.py) — verificados por doble review adversarial (judgment-day, 2 rondas, 0 critical)
+- pit-check: NON_VIABLE + RUN_ERROR excluidos del denominador (antes inflaban el score y
+  podían tirar un BELOW-GATE falso). Nuevo campo `excluded`.
+- simplicity-check: parser robusto con máquina de estados `in_hunk` — una línea agregada
+  `++ x` (que en el diff aparece como `+++ x`) ya no se confunde con un header y deja de
+  perder el conteo del resto del hunk.
+- simplicity-check: skip-set más angosto (`_SIMPLICITY_SKIP`) — código en paquetes
+  `generated`/`out`/`bin`/`dist` ya no se descarta del budget.
+
+## Nuevo (CONSTITUTION.md)
+- Invariante "Integridad del gate — no gamear al que mide": un diff que debilita el aparato
+  de medición (tests/lint/thresholds) o reescribe una masa de asserts = BLOCKER; checker
+  no-correlacionado para alto blast-radius. (Osmani, "Agentic Code Review".)
+
+## Limitación conocida (documentada)
+- simplicity-check espera diffs formato git (`diff --git` por archivo, como `git diff` y
+  `--from-git`). Un `diff -u` plano de POSIX sin esos headers miscuenta archivos después
+  del primero. Usar `--from-git` o `git diff > file`.

package/uscha-kit/CHANGELOG-1.2.4.md

@@ -0,0 +1,10 @@
+# dev-loop-kit 1.2.4
+
+## Nuevo: gate-check (integridad del gate — "no gamear al que mide")
+- Comando `qa_ledger.py gate-check`: detecta si un diff DEBILITA el aparato de medición.
+  - **BLOCKER (exit 1):** tests borrados o deshabilitados, thresholds de coverage/mutation bajados.
+  - **Revisar (soft):** supresiones de lint agregadas, asserts removidos en tests. `--strict` los gatea.
+  - Lee diffs formato git (`--from-git` / `--diff` / stdin). stdlib pura.
+- Implementa en CÓDIGO la invariante "Integridad del gate" de la CONSTITUTION (antes solo texto).
+- (Osmani, "Agentic Code Review": los red-flags para revisores humanos; el detector automático
+  y el principio "el aparato no lo modifica el cambio que mide" son síntesis del kit.)

package/uscha-kit/CHANGELOG-1.2.5.md

@@ -0,0 +1,23 @@
+# dev-loop-kit 1.2.5 — destilación ("gates de hechos bloquean, adivinadores de prosa avisan")
+
+## Nuevo: golden-diff + INV-GOLDEN-01 (golden/approval testing)
+- `qa_ledger.py golden-diff`: byte-compara `*.received.*` vs `*.approved.*`. Cualquier no-match
+  o `.received` sin `.approved` = DIVERGE (exit 1). Es un HECHO, no un juicio. Nunca toca `.approved`.
+- Invariante `INV-GOLDEN-01` (CWE-440) en CONSTITUTION: en migraciones, golden capturado ANTES de
+  tocar el módulo; el golden lo captura un script sobre el código ORIGINAL, el agente no lo authorea.
+- (Del HANDOFF de golden testing — pendiente a mano: skill `characterize`, hook PreToolUse que bloquee
+  escrituras a `.approved`, `.gitattributes *.approved.* binary`, y decisión de stack del harness.)
+
+## Destilación (distinción hechos vs adivinanza)
+- `spec-check` → **ADVISORY** por defecto (heurística sobre prosa): reporta, NO bloquea. `--strict` gatea.
+- `simplicity-check` → el regex de "abstracciones" (falsos positivos con records/DTOs) sale del score y
+  del hard-cap; queda como métrica/flag informativa. Los caps numéricos (líneas/archivos/anidación) siguen gateando.
+
+## Fixes de spec-check (judgment-day Ronda 1, 2 jueces, 2 critical + 4 warnings, todos resueltos)
+- Code-fence tracking (un `# Exclusions` dentro de ```` ``` ```` ya no cuenta), setext headings,
+  checkbox vacío no cuenta como criterio, `_SC_ACCEPT` anclado (no "Success/Exit criteria"),
+  `\d` suelto ya no exime vago, stack ambiguo podado + scopeado a criterios, vagos en español sumados.
+
+## Gates: hechos (bloquean) vs prosa (avisan)
+- BLOQUEAN (leen hechos): golden-diff, pit-check, gate-check, readiness/rebuild, caps de simplicity.
+- AVISAN (heurística): spec-check, abstracciones de simplicity.

package/uscha-kit/CHANGELOG-1.2.6.md

@@ -0,0 +1,11 @@
+# dev-loop-kit 1.2.6 — fix golden-diff (judgment-day, 2 jueces, coincidencia)
+
+## Fix (cmd_golden_diff) — verificado contra los casos reproducidos por los jueces
+- **[CRITICAL] `str.replace` global** reemplazaba TODAS las ocurrencias de `.received.`:
+  con el marcador en una carpeta padre (snapshots por fecha) o dos veces en el nombre,
+  derivaba el `.approved` mal → DIVERGE falso, y en el peor caso un **FALSE CLEAN** (dejaba
+  pasar una divergencia, exit 0). Fix: `_golden_approved_path()` deriva solo del BASENAME,
+  última ocurrencia (rpartition), nunca del path del directorio.
+- **[real] directorios `*.received.*`** se escaneaban como fixtures → filtro `os.path.isfile`.
+- **[gap] `Foo.received` sin extensión** se salteaba (false CLEAN) → segundo glob `*.received`.
+- Read-only confirmado por ambos jueces: cero write/rename; el agente no puede authorear el golden.

package/uscha-kit/CHANGELOG-1.2.7.md

@@ -0,0 +1,15 @@
+# dev-loop-kit 1.2.7 — skill reverse-discovery (front brownfield)
+
+## Nuevo skill: reverse-discovery
+- Hermano brownfield de `discovery`, para migrar/modernizar un sistema EXISTENTE.
+- El inverso de discovery: el sistema ya existe y su comportamiento ES la verdad → se
+  EXTRAEN hechos, no se propone forma.
+- **Facts-only por diseño:** produce SOLO (1) un mapa del sistema (endpoints, contratos,
+  grafo de dependencias, candidatos de módulo vía análisis estático) y (2) un golden suite
+  capturado mecánicamente en los bordes. NO authorea SPEC/ADR inferidos — eso lo escribe el
+  humano leyendo los hechos; las decisiones forward de módulos van a `/adr-refine`.
+- Hereda INV-GOLDEN-01: el agente nunca toca los `.approved`.
+- Cae limpio del lado "hechos" de la línea hechos-vs-prosa: análisis estático + byte-captura,
+  cero heurística sobre prosa → nada frágil que se rompa.
+- Flujo migración: reverse-discovery → humano escribe SPEC + /adr-refine → /dev-loop
+  (golden-diff + ApplicationModules.verify() verdes) → readiness + human gate.

package/uscha-kit/CHANGELOG-1.2.8.md

@@ -0,0 +1,24 @@
+# dev-loop-kit 1.2.8 — golden testing completo (characterize + hook + gitattributes)
+
+## Nuevo skill: characterize (golden-capture)
+- Captura el golden del código ORIGINAL con inputs reales, por un harness determinístico.
+- 4 fases: harness → checklist de no-determinismo (locale es-AR obligatorio) → captura
+  (.received) → STOP para aprobación humana. NUNCA crea/edita un .approved.
+- Lo orquesta reverse-discovery en su fase 2.
+
+## Nuevo hook: hooks/block-approved-writes.ps1 (PreToolUse, INV-GOLDEN-01)
+- Bloquea mecánicamente que el agente escriba/renombre cualquier *.approved.* (Write/Edit/
+  Bash-write → exit 2). Deja pasar lecturas. Probado.
+- WIRING (pegar en settings.json — no lo puede hacer el agente por el guardrail de self-mod):
+    "hooks": { "PreToolUse": [ { "matcher": "*", "hooks": [
+      { "type": "command",
+        "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"<KIT>/hooks/block-approved-writes.ps1\"" }
+    ] } ] }
+
+## Nuevo: templates/.gitattributes
+- `*.approved.* binary` + `*.received.* binary` — line endings no generan diffs falsos
+  (crítico Windows/SQL Server). Copiar a la raíz del repo de migración.
+
+## Estado del golden testing (del HANDOFF) — AHORA completo en el kit
+- golden-diff (gate, byte-compare) ✓ · characterize (captura) ✓ · reverse-discovery (front
+  brownfield) ✓ · INV-GOLDEN-01 (CONSTITUTION) ✓ · hook PreToolUse ✓ · .gitattributes ✓

package/uscha-kit/CHANGELOG-1.2.9.md

@@ -0,0 +1,4 @@
+# dev-loop-kit 1.2.9 — documentación generalizada
+- Removidas todas las referencias a proyecto/dominio específico del CONSTITUTION template
+  y de los skills characterize/reverse-discovery (ejemplos fiscales → genéricos; locale es-AR
+  → "target locale"; money-path → "camino crítico"). El kit queda dominio-agnóstico.

package/uscha-kit/CHANGELOG-1.20.0.md

@@ -0,0 +1,29 @@
+# dev-loop-kit 1.20.0 — instalación global (2026-07-03)
+
+Release chica de instalabilidad: el kit ahora puede instalarse UNA vez en
+`~/.claude/` y quedar disponible para todos los proyectos, existentes y nuevos.
+Sin cambios de engine. Smoke suite: 121/121.
+
+## Qué cambia
+
+- **Resolución portable del engine**: `dev-loop` y `sys-doc` resuelven
+  `qa_ledger.py` primero en el proyecto (`./.claude/skills/dev-loop/`) y caen a
+  la instalación global (`~/.claude/skills/dev-loop/`) si no hay local. La
+  instalación por proyecto sigue teniendo precedencia (un proyecto puede pinnear
+  su versión del kit copiándolo local).
+- **Instalación global documentada completa** (README § Instalación, Opción B):
+  las SEIS skills (antes el snippet copiaba solo dev-loop y sys-doc — quedó de
+  cuando eran las únicas dos) + el hook `block-approved-writes.ps1` a
+  `~/.claude/hooks/` con registro en `~/.claude/settings.json`, para que
+  INV-GOLDEN-01 rija en todos los proyectos.
+- **Qué sigue siendo por-proyecto** (estado, no instalable — ahora explícito):
+  `dev-loop.config.json` (los `path` son relativos a la raíz de la run, y la
+  quality bar declarada del humano vive ahí — 1.17.0), `QA-LEDGER.json`,
+  `ACCEPTANCE.md`, y el `.gitattributes` de templates para migración.
+- Nota para la máquina donde se DESARROLLA el kit: junction/symlink por skill al
+  repo canónico en vez de copia — global siempre al día con main.
+
+## Diferido consciente
+
+- Un comando `install.sh`/`install.ps1` empaquetado: hoy son dos líneas de shell
+  documentadas; si el on-ramp real (dogfooding) muestra fricción, se mecaniza.

package/uscha-kit/CHANGELOG-1.21.0.md

@@ -0,0 +1,33 @@
+# dev-loop-kit 1.21.0 — namespace specloop-* (2026-07-03)
+
+Release de naming, decidida por el humano entre tres opciones (prefijo largo /
+prefijo corto / dejar como está): las seis skills pasan de nombres genéricos a
+**namespace `specloop-*`**. Nombres como `discovery` o `characterize` eran
+squatting del namespace global — cualquier otro kit podía pisarlos (evidencia:
+el harness ya desambiguaba proyecto-vs-global con los genéricos). Se hace AHORA
+porque es el momento más barato: antes de publicar, renombrar no rompe a nadie.
+Sin cambios de engine. Smoke suite: 121/121.
+
+## El mapa de renombres
+
+| Antes | Ahora |
+|---|---|
+| `/discovery` | `/specloop-discovery` |
+| `/adr-refine` | `/specloop-adr-refine` |
+| `/reverse-discovery` | `/specloop-reverse-discovery` |
+| `/characterize` | `/specloop-characterize` |
+| `/dev-loop` | `/specloop-devloop` |
+| `/sys-doc` | `/specloop-sysdoc` |
+
+- **El path del engine cambia** (breaking para scripts que lo hardcodeaban):
+  `.claude/skills/dev-loop/qa_ledger.py` → `.claude/skills/specloop-devloop/qa_ledger.py`.
+  El fallback global (1.20.0) apunta ahora a `~/.claude/skills/specloop-devloop/`.
+- **NO cambian**: `dev-loop-kit` (el nombre del kit), `dev-loop.config.json`
+  (el archivo de config), los subcomandos del engine, ni el schema del ledger.
+- Instalación global: re-crear los junctions/copias con los nombres nuevos
+  (los viejos quedan rotos tras el rename de directorios).
+- Sweep completo con truth-pass: SKILL.md (frontmatter + referencias cruzadas),
+  READMEs, templates/CLAUDE.md, decks ES/EN, playbooks ES/EN, onepagers,
+  pitches, skills-referencia, smoke. Los artefactos HISTÓRICOS (audits/*.json,
+  changelogs viejos, HANDOFFs de releases pasadas) NO se retro-editan —
+  documentan el estado de su época.

package/uscha-kit/CHANGELOG-1.22.0.md

@@ -0,0 +1,60 @@
+# dev-loop-kit 1.22.0 — doctor: diagnóstico de la instalación (2026-07-03)
+
+`qa_ledger.py doctor` (subcomando 22) — espíritu flutter doctor: verifica que
+spec-loop esté instalado y sano en la máquina de trabajo, Windows y Linux.
+Smoke suite: 124/124.
+
+## La idea
+
+- **El engine verifica su PROPIA instalación**: las skills viven al lado de
+  `qa_ledger.py` (sea `~/.claude/skills/` global o `.claude/skills/` del
+  proyecto), así que doctor inspecciona a sus hermanos y reporta qué modo de
+  instalación detectó.
+- **Output ASCII puro** (`[OK]` / `[ !]` / `[ X]`): es la herramienta de primer
+  contacto en máquinas vírgenes — no puede depender del encoding de la consola.
+- **Exit 1 SOLO con errores**; los avisos no fallan (un toolchain ausente en la
+  máquina puede vivir en CI). `--json` para consumo programático.
+
+## Qué chequea
+
+| Check | Nivel si falla |
+|---|---|
+| Python ≥ 3.8 · git en PATH | error |
+| Las 6 skills junto al engine, con frontmatter `name:` verificado | error |
+| Hook INV-GOLDEN-01: archivo presente · registrado en `settings.json` (PreToolUse) · intérprete powershell/pwsh disponible | aviso (cada capa faltante, con el remedio) |
+| `dev-loop.config.json` del cwd: parseable, versión, repos | error si inválido · aviso si ausente |
+| ACCEPTANCE del config: criterios + AC-IDs trazables | aviso |
+| Skills de QA de `qa_tools_order` (default code-review/judgment-day/improve) presentes en `.claude/skills` del proyecto o del usuario — el loop las orquesta sin traerlas | aviso (las built-in del harness no son detectables por filesystem, y lo dice) |
+| Ledger: carga + checksum de integridad (1.13.0) | **error** si corrupto/mutado |
+| Toolchain primario por repo type (`mvn`/`pytest`/`npm`/`go`/`cargo`/`dotnet`/`ctest`/`gradlew` del repo/`swift`/`flutter`) | aviso |
+
+## El doctor no solo diagnostica: cura
+
+Cada aviso/error lleva su **remedio accionable** — el comando o el link de
+instalación (python.org, git-scm, maven/flutter/nodejs/go/rustup/dotnet/cmake/
+gradle/swift, pwsh para el hook en Linux, y los pasos del propio kit para
+skills/hook/config faltantes). Espíritu flutter doctor completo: corrés
+`doctor`, instalás lo listado, re-corrés hasta verde.
+
+## Hardening (review fresco pre-commit, aplicado)
+
+- `startswith` sin separador final clasificaba `~/.claude/skills-evil/` como
+  instalación global → separador + `normcase` (case de drive en Windows).
+- El header humano usaba em-dash y el JSON `ensure_ascii=False` — violaba la
+  promesa ASCII → header ASCII y `ensure_ascii=True` (el doctor promete bytes
+  ASCII SIEMPRE, es la herramienta de primer contacto).
+- Detección de registro del hook por substring en la rama PreToolUse: límite
+  disclosed en el docstring (falso positivo rebuscado, dirección benigna).
+
+## Notas de plataforma
+
+- Linux: el hook es PowerShell — doctor avisa si no hay `pwsh` (instalarlo o
+  portar el twin bash, diferido consciente desde el header del .ps1).
+- Windows: junctions de instalación global se atraviesan con normalidad
+  (doctor clasifica global vs por-proyecto por el path real del engine).
+
+## Smoke
+
+- **T42**: doctor en sandbox → exit 0 con config y ACCEPTANCE leídos, 6/6
+  skills, install clasificada por-proyecto · ledger corrupto → exit 1 (la
+  integridad del ledger es error, no aviso).