@trycore/spec-build-harness 0.1.0

package/hooks/build-harness.json

@@ -0,0 +1,61 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/load-build-state.sh\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/gitflow-guard.sh\""
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/stack-guard.sh\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/lint-typecheck.sh\""
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/coherence-flag.sh\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/build-gate-check.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/internal/skills/auditar-arnes/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: auditar-arnes
+description: Skill INTERNA (no se distribuye al consumidor). Audita el propio paquete del arnés cada 3-6 meses — poda de instrucciones obsoletas, validación de herramientas nativas que vuelvan redundante un hook/agente, re-sincronización de convenciones (schema ↔ agentes ↔ skills), y verificación de agnosticismo. Equivale a la cadencia de GOVERNANCE.md.
+---
+
+# Auditar el arnés de construcción (mantenimiento del paquete)
+
+Skill de **mantenedor**, no de consumidor. Vive en `internal/skills/` y se incluye en el
+paquete npm (`files[]`) pero **NO** la instala el CLI ni la expone el plugin — solo se usa
+trabajando sobre el repo del propio paquete.
+
+## Cadencia (cada 3-6 meses)
+
+1. **Poda de instrucciones**: borrar reglas que el modelo nuevo ya maneja nativamente
+   (las instrucciones obsoletas limitan a modelos más capaces). Revisar agentes y references.
+2. **Validación de herramientas**: ¿hay modos nativos (LSP, MCP nuevos) que vuelvan redundante
+   un hook o un agente? Si sí, retirarlo.
+3. **Coherencia de convenciones**: que `state/build-state.schema.json`, los agentes y las skills
+   sigan alineados (mismos nombres de gate/fase).
+4. **Agnosticismo**: correr `bash scripts/check-agnostic.sh` y `bash scripts/check-state-clean.sh`;
+   confirmar que `docs/examples/` sigue siendo el único lugar con vocabulario de dominio.
+5. **Sincronía de versión**: `bash scripts/check-version-sync.sh` (VERSION / package.json / plugin.json).
+
+## Procedimiento
+
+- Trabaja en rama (`chore/auditoria-arnes-YYYY-MM`), PR al cierre (el arnés se gobierna a sí mismo).
+- Registra decisiones de poda/cambio en `GOVERNANCE.md` (bitácora).
+- Si cambias el schema de estado, los nombres de gate/fase o la política de hooks, actualiza
+  en bloque agentes + skills + schema para no fragmentar convenciones.

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@trycore/spec-build-harness",
+  "version": "0.1.0",
+  "description": "Arnés agéntico de construcción de Trycore para Claude Code: pipeline de dos loops (slice por épica + release gate) con gates de calidad, estado compartido y OpenSpec. Compañero de @trycore/spec-product-flow. Agnóstico al proyecto.",
+  "type": "module",
+  "bin": {
+    "trycore-build": "./dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    ".claude-plugin/",
+    "agents/",
+    "commands/",
+    "skills/",
+    "hooks/",
+    "config/",
+    "state/",
+    "templates/",
+    "internal/",
+    "docs/",
+    "scripts/",
+    "METODOLOGIA.md",
+    "GOVERNANCE.md",
+    "VERSION",
+    "README.md",
+    "INSTALL.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build && bash scripts/check-version-sync.sh && bash scripts/check-agnostic.sh && bash scripts/check-state-clean.sh",
+    "test:smoke": "bash scripts/smoke-test.sh"
+  },
+  "keywords": [
+    "claude-code",
+    "build-harness",
+    "openspec",
+    "tdd",
+    "gitflow",
+    "quality-gates",
+    "release-gate",
+    "agentic",
+    "two-loop",
+    "trycore"
+  ],
+  "homepage": "https://github.com/trycore-co/trycore-spec-build-harness",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trycore-co/trycore-spec-build-harness.git"
+  },
+  "bugs": {
+    "url": "https://github.com/trycore-co/trycore-spec-build-harness/issues"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  }
+}

package/scripts/check-agnostic.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# check-agnostic.sh — guardia anti-contaminación del build harness.
+# Verifica que el contenido distribuido NO mencione dominios de cliente ni el dominio KYC.
+# IMPORTANTE: docs/examples/ está EXCLUIDO a propósito — ahí viven los ejemplos KYC legítimos.
+#
+# Salida 0 si limpio, 1 si encuentra violaciones. Corre en prepublishOnly.
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DENYLIST="$REPO_ROOT/scripts/denylist.txt"
+
+if [[ ! -f "$DENYLIST" ]]; then
+  echo "✗ No se encuentra denylist en $DENYLIST" >&2
+  exit 2
+fi
+
+# Patrón regex con word boundaries desde la denylist (evita falsos positivos por substring).
+PATTERN=""
+while IFS= read -r line; do
+  [[ -z "$line" || "$line" =~ ^[[:space:]]*# ]] && continue
+  esc=$(printf '%s' "$line" | sed 's/[][\/.^$*+?(){}|]/\\&/g')
+  if [[ -z "$PATTERN" ]]; then
+    PATTERN="\\b${esc}\\b"
+  else
+    PATTERN="${PATTERN}|\\b${esc}\\b"
+  fi
+done < "$DENYLIST"
+
+if [[ -z "$PATTERN" ]]; then
+  echo "ℹ denylist vacía, nada que verificar."
+  exit 0
+fi
+
+echo "▶ check-agnostic: buscando menciones de clientes / dominio KYC en el contenido distribuido…"
+echo "  (docs/examples/ excluido a propósito — pack de ejemplos)"
+echo ""
+
+VIOLATIONS=()
+
+# Solo lo que DEBE quedar agnóstico. NO incluye docs/examples/ (pack KYC legítimo).
+TARGETS=(
+  "$REPO_ROOT/agents"
+  "$REPO_ROOT/commands"
+  "$REPO_ROOT/skills"
+  "$REPO_ROOT/hooks"
+  "$REPO_ROOT/config"
+  "$REPO_ROOT/state"
+  "$REPO_ROOT/templates"
+  "$REPO_ROOT/internal"
+  "$REPO_ROOT/docs/customization"
+  "$REPO_ROOT/METODOLOGIA.md"
+  "$REPO_ROOT/README.md"
+  "$REPO_ROOT/INSTALL.md"
+  "$REPO_ROOT/GOVERNANCE.md"
+  "$REPO_ROOT/.claude-plugin"
+)
+
+for target in "${TARGETS[@]}"; do
+  [[ -e "$target" ]] || continue
+  hits=$(grep -riEn -- "$PATTERN" "$target" 2>/dev/null \
+    --include='*.md' --include='*.json' --include='*.sh' \
+    --exclude-dir='node_modules' || true)
+  if [[ -n "$hits" ]]; then
+    VIOLATIONS+=("$hits")
+  fi
+done
+
+if [[ ${#VIOLATIONS[@]} -eq 0 ]]; then
+  echo "✓ Contenido limpio. Cero menciones de clientes / dominio KYC."
+  exit 0
+else
+  echo "✗ Violaciones detectadas:"
+  echo ""
+  for v in "${VIOLATIONS[@]}"; do
+    echo "$v"
+  done
+  echo ""
+  echo "Generaliza el contenido (o mueve el ejemplo concreto a docs/examples/) antes de publicar."
+  exit 1
+fi

package/scripts/check-state-clean.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# check-state-clean.sh — impide filtrar estado vivo de cliente en la publicación [C1].
+# Falla (exit 1) si:
+#   - existe state/build-state.json (estado vivo) o state/newman-*.json en el repo del paquete
+#   - existe algún waiver concreto (waivers/*.md que no sea template)
+#   - build-state.template.json trae history[]/releases[] NO vacíos
+# Corre en prepublishOnly.
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+FAIL=0
+
+# 1) Estado vivo no debe existir en el paquete
+for f in "$REPO_ROOT/state/build-state.json"; do
+  if [[ -f "$f" ]]; then
+    echo "✗ Estado vivo presente en el paquete: $f (debe ser solo build-state.template.json)" >&2
+    FAIL=1
+  fi
+done
+if compgen -G "$REPO_ROOT/state/newman-*.json" > /dev/null; then
+  echo "✗ Artefacto de test vivo presente: state/newman-*.json" >&2
+  FAIL=1
+fi
+
+# 2) Waivers concretos (solo se distribuye el template bajo templates/waivers/)
+if [[ -d "$REPO_ROOT/waivers" ]]; then
+  echo "✗ Carpeta waivers/ con contenido de cliente presente (usa templates/waivers/WAIVER.template.md)" >&2
+  FAIL=1
+fi
+
+# 3) El template de estado debe nacer VACÍO
+TMPL="$REPO_ROOT/state/build-state.template.json"
+if [[ -f "$TMPL" ]] && command -v node >/dev/null 2>&1; then
+  EMPTY=$(node -e "const s=require('$TMPL'); process.stdout.write(String((s.history||[]).length===0 && (s.releases||[]).length===0 && !s.active_slice))" 2>/dev/null)
+  if [[ "$EMPTY" != "true" ]]; then
+    echo "✗ state/build-state.template.json no está vacío (history/releases/active_slice deben venir vacíos)" >&2
+    FAIL=1
+  fi
+fi
+
+if [[ "$FAIL" -eq 0 ]]; then
+  echo "✓ Sin estado vivo en el paquete. Listo para publicar."
+  exit 0
+fi
+echo "" >&2
+echo "✗ check-state-clean: corrige lo anterior antes de publicar." >&2
+exit 1

package/scripts/check-version-sync.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# check-version-sync.sh — valida que las 3 fuentes de versión coincidan.
+#
+# Fuentes auditadas:
+#   - VERSION
+#   - package.json#version
+#   - .claude-plugin/plugin.json#version
+#
+# Salida 0 si las 3 son iguales, 1 si hay drift.
+# Se ejecuta automáticamente vía `npm run prepublishOnly`.
+# Uso manual: bash scripts/check-version-sync.sh
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+VERSION_FILE="$REPO_ROOT/VERSION"
+PKG_FILE="$REPO_ROOT/package.json"
+PLUGIN_FILE="$REPO_ROOT/.claude-plugin/plugin.json"
+
+# Verificación de existencia
+for f in "$VERSION_FILE" "$PKG_FILE" "$PLUGIN_FILE"; do
+  if [ ! -f "$f" ]; then
+    echo "✗ No se encuentra: $f" >&2
+    exit 2
+  fi
+done
+
+V_FILE=$(tr -d '[:space:]' < "$VERSION_FILE")
+V_PKG=$(node -e "console.log(require('$PKG_FILE').version)" 2>/dev/null)
+V_PLUGIN=$(node -e "console.log(require('$PLUGIN_FILE').version)" 2>/dev/null)
+
+if [ -z "$V_PKG" ] || [ -z "$V_PLUGIN" ]; then
+  echo "✗ No se pudo leer la versión de uno de los archivos JSON. ¿Node disponible?" >&2
+  exit 2
+fi
+
+echo "▶ check-version-sync:"
+printf "  VERSION:                          %s\n" "$V_FILE"
+printf "  package.json#version:             %s\n" "$V_PKG"
+printf "  .claude-plugin/plugin.json#version: %s\n" "$V_PLUGIN"
+
+if [ "$V_FILE" = "$V_PKG" ] && [ "$V_PKG" = "$V_PLUGIN" ]; then
+  echo "✓ Las 3 versiones están sincronizadas: $V_FILE"
+  exit 0
+fi
+
+echo "" >&2
+echo "✗ Drift detectado. Las 3 fuentes deben coincidir antes de publicar." >&2
+echo "  Para arreglar: ajusta los archivos al mismo valor de semver." >&2
+exit 1

package/scripts/denylist.txt

@@ -0,0 +1,30 @@
+# denylist.txt — términos que NUNCA deben aparecer en el contenido distribuido del arnés
+# (agents/skills/hooks/config/templates/…). docs/examples/ está EXCLUIDO del check.
+# Uno por línea; líneas con # se ignoran. El check usa word-boundaries case-insensitive.
+# Regla: SOLO identificadores de cliente y vocabulario de DOMINIO concreto — nunca
+# sustantivos genéricos (p.ej. NO incluir "scoring", "google-genai", "better-sqlite3":
+# darían falsos positivos en ejemplos pedagógicos neutros).
+
+# Clientes Trycore
+CISA
+ICBF
+SAE
+Cruz Roja
+Bienestar Familiar
+DIAN
+
+# Proyectos identificables
+inmuebles-cisa
+propuesta-cruz-roja
+docfly
+operator-ms-project
+show-room
+showroom
+
+# Dominio KYC concreto (debe vivir solo en docs/examples/)
+KYC
+cédula
+cedula
+Gemini
+GEMINI_API_KEY
+validacion-documental

package/skills/building-a-slice/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: building-a-slice
+description: Use when building, continuing, or shipping a product epic (EP-XXX) end to end — drives the fast inner-loop pipeline (DoR → OpenSpec change linked to its epic → TDD → journey-smoke → api/data → reduced DoD → PR+archive → ask for Release Gate) using the build-state.json file to synchronize agents. Heavy reviews (security/design/UX/three-way coherence/architecture/integration) run once per release in the releasing-a-version skill, not per epic. The epic is the build unit; the HUs it covers are its internal scope. Delegates to opsx:* for changes and superpowers:test-driven-development for TDD; never reimplements them.
+---
+
+# Construir un slice (épica EP-XXX) — Build
+
+Workflow maestro de **construcción**. Extiende la discovery de Trycore (que termina en flows)
+hacia el código. **Orquesta y delega**: el motor de changes es `opsx:*`, el motor de tests es
+`superpowers:test-driven-development`. Esta skill NO los reimplementa: los secuencia y registra
+el avance en el estado.
+
+> **Unidad de construcción: la épica (`EP-XXX`).** Un slice = una épica = un OpenSpec change = una
+> rama = un PR. Las HU de la épica (que siguen viviendo en `docs/04-historias/`) son el **alcance
+> interno** del change y se listan en `active_slice.hus[]`. Construir por HU suelta es sobre-ingeniería.
+
+## Principio de operación
+- **Una sola fuente de verdad**: `.claude/state/build-state.json` (schema + protocolo en
+  `.claude/state/README.md`). Lee antes de actuar; escribe una vez por transición.
+- **Secuencial**: un slice activo a la vez. Un gate no se salta.
+- **Divulgación progresiva**: carga el `references/<tema>.md` solo cuando la fase lo necesita.
+- **Delega en subagentes** para revisión pesada (devuelven síntesis, protegen el contexto).
+
+## Dos loops
+
+Esta skill conduce el **inner loop** (rápido, por épica, sin subagentes pesados). Las revisiones
+profundas (seguridad, diseño, UX, coherencia triple, arquitectura, integración) **NO** corren por
+épica: corren **una vez por release** en la skill `releasing-a-version` (outer loop). Objetivo del
+inner loop: **≤ ~20 min por épica** y producto que **camina end-to-end en todo momento**.
+
+> **Regla del esqueleto que camina.** El **primer** slice de una release construye el journey
+> completo más delgado posible (de la 1ª a la última actividad del backbone del Story Map), aunque
+> cada paso sea un stub. Cada épica posterior **engorda** un paso de ese esqueleto y mantiene el
+> `journey_smoke` verde. Nunca se construyen capas horizontales aisladas que "se juntan al final".
+
+## Pipeline — inner loop (carga la referencia indicada en cada paso)
+
+| Fase | Acción | Delega en | Gate | Referencia |
+|---|---|---|---|---|
+| 1 · dor | Validar Definition of Ready | `dor-dod-gatekeeper` | `dor` | `dor.md` |
+| 2 · change | `opsx:new` + bloque `## Trazabilidad`; validar enlace (barato) | `opsx:new`, `change-epic-coherence` | `coherence_link` | `link-change-epic.md` |
+| 3 · tdd | red → green → refactor | `superpowers:test-driven-development` | `tdd` | — |
+| 4 · smoke | Recorrer el journey-hasta-aquí end-to-end | skill `verify` / `run` (+ MCP chrome-devtools) | `journey_smoke` | `mcp-map.md` |
+| 5 · api/data | contratos + consistencia (si aplican al slice) | `api-contract-tester`, `data-consistency-checker` | `api`,`data` | `newman-tests.md`, `data-consistency.md` |
+| 6 · dod | Definition of Done (por slice, reducido) | `dor-dod-gatekeeper` | `dod` | `dod.md` |
+| 7 · pr | Abrir PR + archivar change en el mismo PR | `opsx:archive`, `opsx:sync` | — | `gitflow.md` |
+| 8 · release? | Preguntar si correr el Release Gate ahora | usuario (default computado) | — | abajo |
+
+Los gates `stack`, `security`, `smell`, `ux` y la coherencia triple completa **ya no se cierran
+aquí**: pertenecen al Release Gate. Las **deps** siguen vigiladas en tiempo real por el hook
+`stack-guard.sh`; lint/tsc/gitflow por sus hooks.
+
+MCP/LSP por gate: ver `references/mcp-map.md`. Protocolo de estado: `references/state-protocol.md`.
+
+## Fase 8 · ¿Release Gate ahora? (default computado, humano decide)
+
+Tras archivar la épica, **pregunta al usuario** si correr el Release Gate, con un **default
+calculado** desde las líneas de release del Story Map (`docs/02-user-story-map/`):
+
+- Si la épica **cierra una línea de release** (todas las épicas de esa línea ya están en
+  `history[]`) → default **"Sí, correr `releasing-a-version` ahora"**.
+- Si no la cierra → default **"Continuar a la siguiente épica"**. Excepción (*nudge*): si hay
+  **≥ 2 épicas** archivadas desde el último entry de `releases[]`, recomienda correrlo igual.
+
+El usuario siempre puede sobreescribir el default. Si acepta, invoca la skill
+**`releasing-a-version`** sobre la release correspondiente.
+
+## Cómo empezar
+1. Pregunta/identifica la **épica** objetivo (`EP-XXX` en `docs/03-backlog/epicas.md`) y reúne las
+   **HU que cubre** (las que tienen `epica: EP-XXX` en `docs/04-historias/`) → poblarán `hus[]`.
+2. Lee `build-state.json`. Si hay `active_slice`, retoma su primer gate abierto; si es `null`,
+   arranca en **dor**.
+3. Invoca al `build-orchestrator` para conducir el pipeline, o ejecuta fase a fase tú mismo
+   respetando los gates.
+
+## Reglas duras
+- Si `harness_phase` = `authoring` (sin `package.json`), puedes hacer dor + change, pero
+  los gates de código (tdd, journey_smoke, api, data) NO se cierran hasta scaffoldear.
+- El enlace change↔épica va en `## Trazabilidad` del `proposal.md`, **nunca** en frontmatter YAML
+  (rompe `openspec validate`). Ver `link-change-epic.md`.
+- Integración solo por **PR** a `main` (el hook `gitflow-guard.sh` bloquea commits/push directos).
+- Si una regla aquí contradice la metodología Trycore (`METODOLOGIA.md`), **gana la metodología**.

package/skills/building-a-slice/references/data-consistency.md

@@ -0,0 +1,34 @@
+# Consistencia de datos — frontera externa + capa de decisión
+
+Guía que aplica `data-consistency-checker`. Dos dominios de datos: el **JSON de esquema fijo** que
+devuelve el servicio externo/IA de la frontera (la "capa de servicios externos") y el **cálculo
+determinista de la capa de decisión del dominio**.
+
+Los nombres concretos de campos, las decisiones de alto impacto, los umbrales y los casos borde se
+leen del bloque de dominio del CLAUDE.md del consumidor / del PRD del consumidor (ruta declarada en
+`stack-allowlist.json#source`). Esta guía describe los **patrones de invariante**, no valores de un
+dominio específico. (Para una instanciación concreta de referencia, ver
+`docs/examples/reference/data-consistency.example.md`.)
+
+## Esquema de la frontera (servicio externo/IA → JSON de esquema fijo)
+- **Validación dura contra esquema** (p. ej. zod) a la salida del servicio: trata toda salida externa/IA como **entrada no confiable**. Malformado = rechazo controlado, no propagación a la capa de decisión.
+- **Tipos/unidades** consistentes (montos numéricos, fechas ISO 8601, identificadores normalizados), según las reglas del dominio del consumidor.
+- **Campos ausentes** explícitos (`null`/opcional) — nunca valores fantasma o defaults silenciosos.
+- **Idempotencia**: re-procesar la misma entrada produce el mismo JSON (salvo cambios de prompt/contrato versionados).
+
+## Capa de decisión del dominio (determinista, sin IA)
+- **Determinismo**: misma entrada → mismo resultado y misma clasificación, ejecutado N veces. Sin `Math.random`, sin reloj, sin IA en el cálculo.
+- **Rango y constantes versionadas**: el resultado está acotado y la clasificación pertenece al conjunto de **las decisiones de alto impacto del dominio** (ejemplo concreto en el domain-pack del consumidor), según **umbrales versionados** (config, no literales dispersos en el código).
+- **Explicabilidad**: Σ(drivers por factor) reconstruye exactamente el total (cuadra al céntimo/punto); el resultado es trazable a sus contribuyentes.
+- **Consistencia cruzada**: las comparaciones entre fuentes/registros (campos de identidad u otros declarados por el consumidor) son consistentes y las discrepancias se atribuyen a la fuente correcta.
+
+## Tipos de prueba a exigir
+1. **Schema tests**: fixtures válidos pasan; inválidos (campo faltante, tipo erróneo, valor negativo donde no aplica) fallan con error claro.
+2. **Determinismo**: ejecutar la capa de decisión K veces sobre el mismo input → resultado idéntico.
+3. **Property-based** (recomendado): para inputs generados, el resultado permanece en rango y la suma de drivers cuadra.
+4. **Casos límite**: entradas vacías, valores negativos donde no deberían existir, variantes de texto con acentos/typos, valores en cero, entradas ilegibles. Los casos concretos se derivan del PRD/CLAUDE.md del consumidor.
+5. **No-persistencia de datos regulados/PII**: verificar que el cálculo no escribe datos sensibles / PII regulados crudos (los que el consumidor declara en el bloque de dominio de su CLAUDE.md o su PRD) a la capa de persistencia/`localStorage`/logs.
+
+## Veredicto → gate
+Todas las invariantes ✓ con evidencia (test/`archivo:línea`) → `gates.data: true`. Alguna ✗ →
+`false` + el test o fix faltante.

package/skills/building-a-slice/references/dod.md

@@ -0,0 +1,25 @@
+# Definition of Done (DoD) — checklist de salida **por slice** (inner loop)
+
+Un slice (épica) **no se archiva ni se mergea** hasta cumplir TODO esto. Lo valida
+`dor-dod-gatekeeper` leyendo los gates de `build-state.json`. Es el DoD **reducido**: las revisiones
+pesadas (seguridad, diseño, UX, coherencia triple, arquitectura, integración) **no** se piden aquí
+— se piden una vez por release en el **Release Gate** (`release-dod.md` de la skill
+`releasing-a-version`).
+
+- [ ] **`tdd`** — cada escenario AC (G/W/T) de **cada HU de la épica** tiene test; ciclo red→green→refactor completo; suite verde.
+- [ ] **`journey_smoke`** — la app arranca y el **journey-hasta-aquí** (backbone del Story Map cubierto hasta esta épica) **se recorre end-to-end** sin romperse. Se verifica con la skill `verify`/`run` (+ MCP `chrome-devtools` si la app corre). El esqueleto que camina sigue caminando.
+- [ ] **`coherence_link`** — `change-epic-coherence` confirma el enlace change↔épica (bloque `## Trazabilidad`, `openspec validate` ok). Es el chequeo **barato**; la trazabilidad triple completa va al Release Gate.
+- [ ] **`data`** — `data-consistency-checker` valida invariantes de datos (salida de servicios externos validada contra esquema antes de alimentar la capa de decisión determinista del dominio) (si el slice toca datos).
+- [ ] **`api`** — `api-contract-tester` (Newman) 100% verde (o `null` si el slice no tiene endpoints).
+- [ ] **OpenSpec**: todas las tasks `[x]`; el archive del change va **en el mismo PR** (no PR aparte).
+- [ ] **Docs/trazabilidad**: back-ref del change añadida en la épica y en cada HU de `hus[]`.
+- [ ] **Hooks verdes (automáticos, no son gates de agente)**: `lint-typecheck.sh` (lint + chequeo de tipos del stack declarado), `stack-guard.sh` (deps en allowlist según la sección de requisitos técnicos del PRD del consumidor, ruta declarada en `stack-allowlist.json#source`), `gitflow-guard.sh` (rama `feature/*`, sin commits directos a `main`).
+
+**Todo ✓** → `gates.dod: true`; se hace `opsx:archive` + se abre/mergea el PR. **Algo ✗** → listar
+gates abiertos y devolver al `build-orchestrator`.
+
+> **Lo que NO se valida aquí (va al Release Gate, `releasing-a-version`):** `security`, `smell`
+> (diseño), `ux` (Krug), `coherence` (trazabilidad triple completa) y `stack_arch` (arquitectura
+> según el contrato de stack del PRD del consumidor: servicios externos/IA en la frontera declarada
+> server-side, capa de decisión determinista del dominio sin IA). Las **deps** sí se vigilan por
+> slice, pero vía el hook `stack-guard.sh`, no vía subagente.

package/skills/building-a-slice/references/dor.md

@@ -0,0 +1,17 @@
+# Definition of Ready (DoR) — checklist de entrada
+
+Una **épica** (`EP-XXX`) **no entra a construcción** hasta cumplir TODO esto. La unidad del slice es
+la épica; lo de abajo aplica a la épica y a **cada HU** que cubre (`hus[]`). Lo valida `dor-dod-gatekeeper`.
+
+- [ ] **Épica válida**: `EP-XXX` existe en `docs/03-backlog/epicas.md` con trazabilidad a objetivos del PRD.
+- [ ] **HU enumeradas**: la épica tiene ≥1 HU; todas las que entran se listan en `hus[]`.
+- [ ] **Frontmatter completo** en cada `docs/04-historias/HU-XXX.md`: `id, titulo, epica, prioridad, complejidad, estado` y `estado: lista`.
+- [ ] **AC en Given/When/Then** por HU: 3–5 escenarios, con **happy + error + edge** (regla dura Trycore).
+- [ ] **INVEST** por HU: pasa los 6 criterios (Independent, Negotiable, Valuable, Estimable, Small, Testable). Ante duda, invocar `invest-validator`.
+- [ ] **Dependencias resueltas**: las épicas/HU de las que depende están archivadas (`history[]`) o explícitamente no bloquean.
+- [ ] **Cabe en el stack** del PRD §7 (no requiere tecnología fuera de `stack-allowlist.json`).
+- [ ] **Datos de prueba disponibles** o identificables (p.ej. los datos de ejemplo / fixtures sintéticos del dominio del consumidor).
+
+**Si todo ✓** → `dor-dod-gatekeeper` abre `active_slice` en `build-state.json` con `epica`, `hus[]`,
+`phase: dor`, `gates.dor: true` y el resto en `false` (`ux`/`api` en `null` si la épica no toca UI/endpoints).
+**Si algo ✗** → no se abre el slice; se reporta qué falta y se vuelve a discovery (Trycore).

package/skills/building-a-slice/references/gitflow.md

@@ -0,0 +1,30 @@
+# GitHub Flow (estricto) — Build
+
+Modelo de ramas **GitHub Flow**: `main` siempre desplegable; todo cambio nace en una rama corta y
+se integra **solo por Pull Request** con checks verdes. El hook `gitflow-guard.sh` lo hace cumplir
+de forma determinista (bloquea commit/push directo a `main` y ramas no tipadas).
+
+## Ciclo por slice
+```bash
+git switch main && git pull --ff-only          # parte de main al día
+git switch -c feature/<slug>                    # rama tipada: feature/* | fix/* | chore/*
+# ... TDD + gates (estado en build-state.json) ...
+git add -A && git commit -m "<tipo>: <mensaje>" # commit en la rama feature (nunca en main)
+git push -u origin feature/<slug>               # push de la rama feature (nunca a main)
+gh pr create --base main --head feature/<slug> --fill   # integración por PR
+```
+
+## Convenciones
+- **Rama**: `feature/<slug-kebab>` (nuevo valor), `fix/<slug>` (corrección), `chore/<slug>` (infra/docs).
+  Una rama por **épica** (= un slice): `feature/ep-003-pricing-engine`.
+- **Commits**: Conventional Commits (`feat:`, `fix:`, `test:`, `refactor:`, `chore:`, `docs:`).
+- **PR**: título claro, descripción enlazando la épica, sus HU (`hus[]`) y el OpenSpec change; checks
+  (lint, types, tests, newman) en verde antes de merge; squash recomendado.
+
+## Qué bloquea `gitflow-guard.sh`
+- `git commit` estando en `main`/`master`. → crea una rama feature.
+- `git commit` desde una rama que no es `feature/*|fix/*|chore/*`.
+- `git push` apuntando a `main`/`master`. → abre un PR.
+
+> No es GitFlow clásico: **no hay `develop` ni `release/*`**. Una sola línea estable (`main`) +
+> ramas cortas + PR.

package/skills/building-a-slice/references/krug-ux.md

@@ -0,0 +1,27 @@
+# Usabilidad según Steve Krug ("Don't Make Me Think")
+
+Heurísticas que aplica `ux-krug-reviewer` a slices con UI. Objetivo: que el usuario operador del producto opere
+sin fricción cognitiva.
+
+## Las leyes de Krug
+1. **Primera ley — "No me hagas pensar".** Todo lo autoevidente; si no, autoexplicativo. Cero acertijos.
+2. **No usamos la web, la escaneamos.** Diseña para el vistazo: jerarquía visual, encabezados,
+   fragmentos cortos, lo importante arriba/grande.
+3. **Elegimos la primera opción razonable (satisficing).** No obligues a comparar; ofrece caminos obvios.
+4. **"Omite las palabras innecesarias".** Recorta el ruido textual a la mitad; luego otra vez.
+5. **Convención sobre creatividad.** Botones que parecen botones, enlaces que parecen enlaces,
+   navegación donde se espera.
+6. **Haz obvio lo clicable** y da feedback inmediato (hover, loading, disabled, foco).
+
+## Aplicado a decisiones de alto impacto
+- La **decisión de alto impacto del dominio** (ejemplo concreto en el domain-pack del consumidor) y su **resultado con su banda/clasificación** deben leerse de un vistazo.
+- Los **drivers o factores que justifican el resultado**: visibles y comprensibles sin abrir documentación.
+- Las **inconsistencias o discrepancias detectadas**: resaltadas y atribuidas a su origen correcto, sin ambigüedad.
+- Estados explícitos: **cargando, vacío, error, sin permisos**; nunca una pantalla muda.
+- Recuperación de error con mensaje accionable (qué pasó y qué hacer), sin filtrar datos sensibles / PII regulados ni stack traces.
+
+## Medir, no opinar (cuando la app corre)
+Usa el MCP **chrome-devtools**:
+- `take_snapshot` → inspecciona el árbol de accesibilidad (roles, labels, foco).
+- `lighthouse_audit` → puntuaciones de Accessibility / Best Practices; adjunta fallos concretos.
+Reporta hallazgos como BLOQUEANTE / RECOMENDADO / NIT con la pantalla y el fix.

package/skills/building-a-slice/references/link-change-epic.md

@@ -0,0 +1,34 @@
+# Enlace OpenSpec change ↔ épica + HU cubiertas (bloque de Trazabilidad)
+
+Cada OpenSpec change corresponde a **una épica** (la unidad de construcción) y declara las
+**historia(s)** que cubre. Este enlace es el puente entre la discovery de Trycore (`docs/`) y la
+construcción (`openspec/`). Lo valida `change-epic-coherence`.
+
+## Dónde y cómo
+En el **cuerpo markdown** del `openspec/changes/<name>/proposal.md`, añade una sección al final:
+
+```markdown
+## Trazabilidad
+- Épica: EP-003
+- Historias: HU-010, HU-011, HU-012
+- Discovery: docs/03-backlog/epicas.md#ep-003
+```
+
+> ⚠️ **NO** lo pongas en frontmatter YAML del proposal: OpenSpec valida la estructura del change
+> con `openspec validate --strict` y un frontmatter ajeno puede romperla. El bloque markdown es seguro.
+
+## Reglas
+1. **Exactamente una épica** por change = la unidad del slice (un change no cruza épicas). Si
+   necesitas dos épicas, son dos slices/changes distintos.
+2. **Las HU de esa épica** que entran en el alcance (las de `hus[]`). Cada `HU-XXX` debe existir y
+   su `epica:` debe coincidir con la EP. La lista de `Historias:` debe igualar a `hus[]`.
+3. **Nombre del change**: kebab-case basado en la épica, p.ej. `ep-003-pricing-engine`.
+4. **Back-reference**: al archivar, añade la nota `> OpenSpec change: ep-003-pricing-engine` en la
+   épica (`docs/03-backlog/epicas.md`) y en cada HU de `hus[]` (cierra el enlace bidireccional
+   Trycore↔OpenSpec).
+
+## Validación
+```bash
+openspec validate "<name>" --type change --strict --json
+```
+El agente `change-epic-coherence` corre esto + comprueba existencia de EP/HU + coherencia de alcance.