@trycore/spec-build-harness 0.2.0 → 0.4.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "trycore-spec-build-harness",
   "displayName": "Trycore — Spec & Build Harness",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Arnés de construcción de dos loops (slice por épica + release gate) para Claude Code, con gates de calidad, estado compartido y OpenSpec. Compañero de @trycore/spec-product-flow. Agnóstico al proyecto.",
   "author": {
     "name": "Trycore",

package/GOVERNANCE.md

@@ -1,6 +1,6 @@
 # Gobernanza del arnés de construcción `.claude`
 
-Versión: ver `.claude/.build-harness-version` (`1.0.0`). El arnés es **soporte cognitivo vivo**:
+Versión del paquete: ver `.claude/.build-harness-version`. El arnés es **soporte cognitivo vivo**:
 evoluciona con el modelo y el proyecto. No es "instalar y olvidar".
 
 ## Componentes y dueño
@@ -9,14 +9,15 @@ evoluciona con el modelo y el proyecto. No es "instalar y olvidar".
 | Contexto | sección Construcción de CLAUDE.md, `openspec/project.md` | raíz / `openspec/` |
 | Estado | `build-state.json` (+schema, README) | `.claude/state/` |
 | Agentes | 10 agentes de build | `.claude/agents/build/` |
-| Hooks | settings.json + 6 scripts | `.claude/settings.json`, `.claude/hooks/build/` |
-| Skill | `building-a-slice` + 10 references | `.claude/skills/building-a-slice/` |
+| Hooks | settings.json + 8 scripts | `.claude/settings.json`, `.claude/hooks/build/` |
+| Skill | `building-a-slice` (+10 refs) · `building-a-micro-change` (carril ligero de mantenimiento) | `.claude/skills/` |
 | Config | allowlist de stack | `.claude/config/stack-allowlist.json` |
 
 ## Fases de activación (`harness_phase`)
 - **authoring** (actual): aún no hay `package.json`. Activos: `gitflow-guard`, `load-build-state`,
   `coherence-flag`; agentes de coherencia/stack/DoR/DoD operan sobre texto. Los hooks de
-  lint/typecheck/stack(package.json)/tests están **armados** pero inertes (`[ -f package.json ] || exit 0`).
+  lint/typecheck/stack(package.json)/tests están **armados** pero inertes (`[ -f package.json ] || exit 0`);
+  `scaffold-guard` permite (sin slice en fases de código que bloquear) y `reflect-nudge` calla (sin historial que reflexionar).
 - **active**: al aparecer `package.json`, `load-build-state.sh` cambia la fase y los hooks armados
   empiezan a disparar solos. Sin intervención manual.
 
@@ -40,6 +41,16 @@ Editar `stack-allowlist.json` SOLO si la sección de requisitos técnicos del PR
 ### Bitácora de excepciones de stack
 - _(vacío)_ — registrar fecha, dependencia, justificación y aprobador.
 
+## Bitácora de cambios de metodología
+Cambios a la política de construcción (unidad de trabajo, gates, DoR/DoD). Aprueba el DRI; van por PR.
+
+- **2026-06-02 · v0.4.0** — Carril `building-a-micro-change` + DoR proporcional. El mantenimiento que
+  no es producto nuevo (typo, bump de dep permitida, copy/config/docs, fix de pocas líneas) deja de
+  modelarse como épica y usa un carril ligero (`fix/*`|`chore/*` → PR, sin `active_slice`), con
+  límites duros que lo escalan a épica (dep nueva, API nueva, lógica de dominio/datos). El DoR escala
+  el nº de escenarios G/W/T con `complejidad` en vez de exigir 3–5 fijos. La regla "épica = unidad"
+  se mantiene intacta para producto. Origen: auditoría del arnés vs. crítica de sobre-configuración.
+
 ## Extensiones futuras (no implementadas)
 - **Construcción en paralelo** de slices con `superpowers:using-git-worktrees` + orquestación
   multi-worktree (hoy el modelo es **secuencial** por decisión de proyecto). El `build-state.json`

package/INSTALL.md

@@ -11,7 +11,7 @@ Es el **compañero** de [`@trycore/spec-product-flow`](https://www.npmjs.com/pac
 | CLI (bin) | `trycore-build` |
 | Plugin | `trycore-spec-build-harness` |
 | Marketplace | `trycore-build` |
-| Versión | `0.1.0` |
+| Versión | `0.3.0` |
 
 Hay **dos canales** de instalación: el **CLI npm** (canónico, recomendado para operar en un
 proyecto) y el **plugin nativo** de Claude Code (conveniencia a nivel usuario). Lee el
@@ -28,7 +28,7 @@ npm install -g @trycore/spec-build-harness
 Esto expone el binario `trycore-build`. Comprueba la versión:
 
 ```bash
-trycore-build --version    # → 0.1.0
+trycore-build --version    # → 0.3.0
 trycore-build --help
 ```
 
@@ -85,9 +85,9 @@ Qué hace `init`:
 1. **Verifica requisitos duros** (a menos que uses `--skip-doctor`).
 2. **Siembra los assets** en rutas nativas de Claude Code:
    - `.claude/agents/build/` — 10 agentes.
-   - `.claude/commands/opsx/` (10 comandos `/opsx:*`) y `.claude/commands/build/` (`/build:onboard`).
+   - `.claude/commands/opsx/` (10 comandos `/opsx:*`) y `.claude/commands/build/` (`/build:onboard`, `/build:reflect`).
    - `.claude/skills/` — 12 skills (`building-a-slice`, `releasing-a-version`, `openspec-*`).
-   - `.claude/hooks/build/` — 6 hooks bash.
+   - `.claude/hooks/build/` — 8 hooks bash.
 3. **Siembra el estado**: `state/build-state.schema.json` y `state/README.md` se versionan;
    `state/build-state.json` se siembra **vacío y nunca se sobrescribe** (va al `.gitignore`).
 4. **Siembra `config/stack-allowlist.json`** (artefacto del consumidor; lo puebla `/build:onboard`).
@@ -184,6 +184,11 @@ Qué resuelve:
 
 Si un punto no aplica, se registra explícitamente "no aplica" (no se deja como `{{...}}`).
 
+> **Durante la construcción** (no en la instalación), el comando `/build:reflect` captura las
+> convenciones aprendidas de cada slice cerrado en el bloque `trycore-build-learnings` de
+> `CLAUDE.md` —con tu aprobación— y lo **sugiere** el hook `reflect-nudge.sh` al cerrar sesión.
+> Detalle en `docs/commands.md`.
+
 ---
 
 ## 5. Alternativa: plugin nativo (con caveat de canales)
@@ -228,7 +233,7 @@ Ambos paquetes coexisten en el mismo `.claude/` **sin colisión**, porque usan *
 
 | | Discovery — `spec-product-flow` | Construcción — `spec-build-harness` |
 |---|---|---|
-| Comandos | `/trycore:*` | `/opsx:*` + `/build:onboard` |
+| Comandos | `/trycore:*` | `/opsx:*` + `/build:onboard` + `/build:reflect` |
 | Marca de versión | `.trycore-version` | `.build-harness-version` |
 | Bloque en `CLAUDE.md` | `<!-- BEGIN trycore-vertical -->` | `<!-- BEGIN trycore-build-harness -->` |
 

package/METODOLOGIA.md

@@ -28,7 +28,7 @@ Ambos paquetes **coexisten en el mismo `.claude/` sin colisión**, con namespace
 
 | Eje | Discovery (`spec-product-flow`) | Construcción (`spec-build-harness`) |
 |---|---|---|
-| Comandos | `trycore/` (`/trycore:*`) | `opsx/` + `build/` (`/opsx:*`, `/build:onboard`) |
+| Comandos | `trycore/` (`/trycore:*`) | `opsx/` + `build/` (`/opsx:*`, `/build:onboard`, `/build:reflect`) |
 | Sentinela de versión | `.trycore-version` | `.build-harness-version` |
 | Bloque en `CLAUDE.md` | `<!-- BEGIN trycore-vertical -->` | `<!-- BEGIN trycore-build-harness -->` |
 
@@ -90,6 +90,15 @@ Consecuencia operativa: **la unidad de construcción es la épica, no la HU suel
 épica = un OpenSpec change = una rama = un PR. Las HU que cubre la épica son su *alcance interno* y
 se listan en `active_slice.hus[]`. Construir por HU individual es sobre-ingeniería.
 
+> **Carril micro-change (mantenimiento).** Esta regla rige la **construcción de producto**. El
+> **mantenimiento** que no es capacidad nueva —un typo, un ajuste de copy/config/docs, un bump de
+> dependencia ya permitida, o un fix de pocas líneas sin nueva capacidad— **no se modela como
+> épica**: usa el carril ligero de la skill `building-a-micro-change` (`fix/*`|`chore/*` → cambio →
+> PR, sin abrir `active_slice`). No es una excepción a la regla, sino mantenimiento fuera de su
+> alcance. **Límites duros:** si el cambio añade una dependencia nueva, crea un endpoint/API nuevo, o
+> toca lógica de dominio o el modelo/invariantes de datos, **deja de ser micro-change** y se escala a
+> épica. Ante la duda, es una épica.
+
 ---
 
 ## 3. Pipeline del inner loop, fase por fase (con sus gates)
@@ -117,7 +126,10 @@ Una épica **no entra a construcción** hasta cumplir todo (lo valida `dor-dod-g
 - 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`) con `estado: lista`.
-- AC en Given/When/Then por HU: 3–5 escenarios con happy + error + edge.
+- AC en Given/When/Then por HU, **proporcional a `complejidad`** (cubre los modos de fallo que
+  *realmente existen*, no una cuota fija): `trivial`/baja → **1–2** (happy + error/edge crítico si
+  existe); `media` → **3** (happy + error + edge); `alta` → **3–5** (cobertura completa). Si existe
+  rama de error/edge, debe tener su escenario.
 - Cada HU pasa los 6 criterios **INVEST**.
 - Dependencias resueltas (las épicas/HU de las que depende están en `history[]` o no bloquean).
 - Cabe en el stack del PRD (no requiere tecnología fuera de `stack-allowlist.json`).
@@ -351,8 +363,10 @@ El arnés **no escribe** en `docs/`; cuando una HU no cumple DoR, devuelve el tr
 
 ## 10. Reglas duras (resumen)
 
-1. La **épica** es la unidad de construcción: un slice = una épica = un change = una rama = un PR.
-   Las HU son alcance interno (`hus[]`).
+1. La **épica** es la unidad de construcción de **producto**: un slice = una épica = un change = una
+   rama = un PR. Las HU son alcance interno (`hus[]`). El **mantenimiento** que no es producto nuevo
+   (typo, bump, copy, infra/docs, fix de pocas líneas) usa el carril `building-a-micro-change`, fuera
+   de esta regla; cruzar un límite duro (dep nueva, API nueva, dominio/datos) lo escala a épica.
 2. El **esqueleto que camina** nunca deja de caminar: nada de capas horizontales que se juntan al
    final; `journey_smoke` verde en cada épica.
 3. **Dos loops sin duplicación**: gates baratos por épica (inner), gates pesados una vez por release

package/README.md

@@ -45,7 +45,7 @@ trycore-build init
 | `trycore-build update` | Refresca assets y schema tras `npm update -g`. No pisa estado ni allowlist. |
 | `trycore-build status` | Muestra el estado de la instalación y la fase activa del arnés. |
 | `trycore-build uninstall` | Quita el arnés. **Preserva** `.claude/state/` y `.claude/config/`. |
-| `trycore-build doctor` | Verifica requisitos externos (`openspec`/`python3`/`git`), hooks ejecutables y canales. |
+| `trycore-build doctor` | Verifica requisitos externos (`openspec`/`python3`/`git`), hooks ejecutables y canales; reporta slices sin reflexionar y sugiere **LSP** en stacks tipados. |
 
 Flags de `init`: `--copy` (copiar en vez de symlinkear), `--yes` (no interactivo), `--skip-doctor`, `--force-init`, `--stack <deps>`, `--pkg-manager <pm>`, `--runtime <semver>`, `--prd-path <path>`.
 
@@ -59,7 +59,7 @@ El arnés modela la construcción como dos ciclos anidados, cada uno con su skil
 DoR → OpenSpec change → TDD → journey-smoke → api/data → DoD → PR + archive
 ```
 
-Por cada épica del backlog: se valida el **Definition of Ready**, se abre un *change* en OpenSpec, se desarrolla con **TDD**, se corre el smoke del journey, se verifican contratos de API y consistencia de datos, se valida el **Definition of Done** y se cierra con PR + archivado del change.
+Por cada épica del backlog: se valida el **Definition of Ready**, se abre un *change* en OpenSpec, se desarrolla con **TDD**, se corre el smoke del journey, se verifican contratos de API y consistencia de datos, se valida el **Definition of Done** y se cierra con PR + archivado del change. Tras archivar, `/build:reflect` puede capturar las convenciones aprendidas del slice (**ciclo autocorrectivo**, opcional; lo sugiere el hook `reflect-nudge.sh`).
 
 ### Outer loop — `releasing-a-version` (una vez por release)
 
@@ -70,6 +70,7 @@ Gate de release que corre **una sola vez por versión** sobre el conjunto de sli
 | Command | Propósito |
 |---|---|
 | `/build:onboard` | Onboarding capa 2: lee el PRD, pregunta por PII/IA/determinismo/secretos, resuelve `{{placeholders}}` y escribe la auto-memory. |
+| `/build:reflect` | Reflexión post-slice: tras archivar, propone convenciones aprendidas / errores recurrentes al bloque `trycore-build-learnings` de `CLAUDE.md` (tras tu aprobación) y marca el slice como reflexionado. |
 | `/opsx:explore` | Explora el dominio / specs antes de abrir un change. |
 | `/opsx:new` | Crea un nuevo OpenSpec change. |
 | `/opsx:continue` | Retoma un change en curso. |
@@ -91,9 +92,9 @@ trycore-spec-build-harness/
 ├── agents/build/              ← 10 agentes revisores (segunda opinión, contexto limpio)
 ├── commands/
 │   ├── opsx/                  ← 10 comandos /opsx:* (ciclo OpenSpec)
-│   └── build/                 ← /build:onboard
+│   └── build/                 ← /build:onboard, /build:reflect
 ├── skills/                    ← 12 skills (building-a-slice, releasing-a-version, 10 openspec-*)
-├── hooks/build/               ← 6 hooks bash (gate-check, gitflow-guard, stack-guard, …)
+├── hooks/build/               ← 8 hooks bash (gate-check, reflect-nudge, scaffold-guard, gitflow-guard, stack-guard, …)
 ├── state/                     ← máquina de estado: build-state.json + schema + README
 ├── config/                    ← stack-allowlist.template.json (artefacto del consumidor)
 ├── src/ + dist/               ← CLI trycore-build (init/update/status/uninstall/doctor)
@@ -123,7 +124,9 @@ El core no menciona ningún dominio de cliente. Toda parametrización entra por
 
 ## Roadmap
 
-- ✅ **v0.1.0 (actual)** — arnés de dos loops (`building-a-slice` + `releasing-a-version`), 10 agentes, comandos `/opsx:*` + `/build:onboard`, 12 skills, 6 hooks, máquina de estado `build-state.json`, allowlist de stack, CLI `trycore-build` (init/update/status/uninstall/doctor) y plugin nativo. Compañero de `@trycore/spec-product-flow`.
+- ✅ **v0.1.0** — arnés de dos loops (`building-a-slice` + `releasing-a-version`), 10 agentes, comandos `/opsx:*` + `/build:onboard`, 12 skills, 6 hooks, máquina de estado `build-state.json`, allowlist de stack, CLI `trycore-build` (init/update/status/uninstall/doctor) y plugin nativo. Compañero de `@trycore/spec-product-flow`.
+- ✅ **v0.2.0** — scaffold como "Paso 1 fundamental": gate de proyecto `scaffold.confirmed` (confirmación **explícita**, no auto), Fase 0 en `building-a-slice`, criterio duro de DoR y hook `scaffold-guard.sh`. El arnés **exige** el scaffold pero **no lo genera**.
+- ✅ **v0.3.0 (actual)** — **ciclo autocorrectivo** (hook `reflect-nudge.sh` + comando `/build:reflect`: propone convenciones aprendidas al bloque `trycore-build-learnings` de `CLAUDE.md` tras tu aprobación; campos `reflected`/`reflected_at`) y **LSP opt-in** (`docs/customization/lsp-extensions.md` + sugerencia en `doctor` para stacks tipados). Total: **8 hooks**; comandos `/opsx:*` + `/build:onboard` + `/build:reflect`.
 
 ## Licencia
 

package/VERSION

@@ -1 +1 @@
-0.2.0
+0.4.0

package/agents/build/dor-dod-gatekeeper.md

@@ -23,7 +23,9 @@ cumplen; lista cada una con ✓/✗:
 2. Tiene **al menos una HU** asociada y todas se enumeran en `hus[]`.
 3. **Cada HU** de la épica: frontmatter YAML completo (`id, titulo, epica, prioridad, complejidad,
    estado`) y `estado: lista`.
-4. **Cada HU**: AC en formato **Given/When/Then**, 3–5 escenarios con happy + error + edge.
+4. **Cada HU**: AC en formato **Given/When/Then**, **proporcional a `complejidad`** (`trivial`/baja →
+   1–2; `media` → 3; `alta` → 3–5), cubriendo los modos de fallo que existen (happy + error/edge
+   reales). No exijas 3–5 a una HU trivial; sí exige el escenario de toda rama de error/edge que exista.
 5. **Cada HU** pasa los 6 criterios **INVEST** (si dudas, invoca al agente `invest-validator`).
 6. Dependencias declaradas (otras épicas/HU) están en `history[]` del estado o marcadas done.
 7. El alcance de la épica cabe en el stack declarado del PRD (allowlist) (no exige tecnología fuera de la allowlist).

package/commands/build/reflect.md

@@ -0,0 +1,163 @@
+---
+name: "BUILD: Reflect"
+description: Reflexión post-slice (ciclo autocorrectivo). Tras cerrar/archivar un slice, detecta convenciones aprendidas y errores recurrentes, PROPONE viñetas para el bloque de aprendizajes de CLAUDE.md (se aplican SOLO con tu aprobación) y estampa el slice como reflexionado. Lo dispara el hook reflect-nudge.sh, pero puedes invocarlo cuando quieras.
+category: Workflow
+tags: [reflexion, conocimiento, ciclo-autocorrectivo, build-harness, trycore]
+---
+
+Captura el **conocimiento tribal** de un slice recién cerrado antes de que se pierda. Un hook bash no
+puede razonar qué se aprendió; **tú (el modelo) sí**. Tu trabajo: detectar convención nueva o error
+recurrente, **proponérselo al usuario**, y —solo con su aprobación— escribirlo al bloque
+`trycore-build-learnings` de `CLAUDE.md`. Nunca escribes sin confirmación.
+
+Esta es la mejora del **pilar "ciclo autocorrectivo"**: el hook `reflect-nudge.sh` (evento `Stop`)
+solo **sugiere** ejecutar esto cuando hay slices archivados sin reflexionar; el razonamiento vive
+aquí, en el modelo.
+
+---
+
+## Preflight
+
+```bash
+test -f .claude/.build-harness-version || echo "NOT_INSTALLED"
+command -v python3 >/dev/null 2>&1 || echo "NO_PYTHON3"
+```
+
+**Si `NOT_INSTALLED`:**
+
+> Este proyecto no tiene el arnés de construcción instalado. Ejecuta primero `trycore-build init`.
+
+Stop aquí si no está instalado o si falta `python3`.
+
+---
+
+## Fase 1: Identificar slices sin reflexionar
+
+Lee `.claude/state/build-state.json` y filtra las entradas de `history[]` con `reflected != true`:
+
+```bash
+python3 - <<'PY'
+import json
+d = json.load(open(".claude/state/build-state.json"))
+pend = [h for h in (d.get("history") or []) if h.get("reflected") is not True]
+for h in pend:
+    print(h.get("epica"), "·", h.get("openspec_change"), "·", h.get("branch"), "·", ",".join(h.get("hus") or []))
+print("TOTAL", len(pend))
+PY
+```
+
+**Si `TOTAL 0`:** informa "No hay slices pendientes de reflexión ✅" y termina. No inventes trabajo.
+
+Si hay varios, procésalos **de uno en uno** (el más reciente primero), o pregunta al usuario cuál.
+
+---
+
+## Fase 2: Recolectar señal del slice
+
+Para el slice elegido, reúne evidencia **real** (no especules):
+
+1. **El change OpenSpec**: `openspec show <openspec_change>` y/o los archivos del change
+   (proposal/tasks). ¿Qué se decidió y qué tasks costaron más?
+2. **El diff de la rama**: `git log --oneline <branch>` y `git diff main...<branch> --stat` (si la
+   rama o sus commits existen). ¿Qué patrón de código se repitió? ¿Qué se reescribió varias veces?
+3. **La sesión actual**: qué hooks se dispararon más de una vez (p.ej. `stack-guard.sh`,
+   `gitflow-guard.sh`, `lint-typecheck.sh`), qué gates retrocedieron, qué correcciones se repitieron.
+
+Con esa evidencia, detecta **0–3** aprendizajes candidatos, de estas categorías:
+
+- **Convención nueva**: un patrón de código/estructura/nombrado que se repitió y conviene fijar para
+  el equipo (ej. "los handlers validan en el borde con el esquema X antes de tocar el dominio").
+- **Error recurrente**: algo que un gate o hook atrapó >1 vez y vale la pena prevenir
+  (ej. "recordar correr migraciones antes del journey-smoke").
+- **Fricción del propio arnés**: si el aprendizaje es sobre el arnés (un gate confuso, un paso que
+  sobra), NO lo escribas a CLAUDE.md — anótalo como candidato para `internal/skills/auditar-arnes`
+  y dilo al usuario.
+
+Si no hay nada que valga la pena fijar, es válido **no proponer aprendizajes** (solo estampar, Fase 5).
+
+---
+
+## Fase 3: Proponer (con aprobación explícita)
+
+Por **cada** aprendizaje candidato, usa **AskUserQuestion** para que el usuario lo apruebe, edite o
+descarte. Presenta cada uno como una **viñeta concreta y accionable**, lista para CLAUDE.md. Ejemplo
+de opciones: "Agregar tal cual" (Recomendado) · "Editar" · "Descartar".
+
+**Reglas:**
+- Una viñeta = una convención. Concreta, verificable, en presente imperativo. Nada vago.
+- No propongas conocimiento que ya está en el bloque (léelo antes). No dupliques.
+- Si un aprendizaje es **personal/cross-proyecto** (no de equipo), ofrécelo para **auto-memory**
+  (`type: project`/`user`) en vez de CLAUDE.md — pregunta cuál destino.
+
+---
+
+## Fase 4: Aplicar SOLO lo aprobado al bloque de aprendizajes
+
+Para las viñetas aprobadas, **inserta** (no reemplaces) dentro del bloque marcado de `CLAUDE.md`,
+**justo antes** de `<!-- END trycore-build-learnings -->`:
+
+```markdown
+- (EP-XXX) <viñeta aprobada>
+```
+
+- Prefija cada viñeta con la épica del slice `(EP-XXX)` para trazabilidad.
+- **NO toques nada fuera del bloque** `trycore-build-learnings`. En particular, NO modifiques el
+  bloque `trycore-build-harness` ni sus `{{placeholders}}` de dominio (eso es de `/build:onboard`).
+- Si el bloque `trycore-build-learnings` no existe (instalación vieja), pide correr
+  `trycore-build update` antes de continuar.
+- Las viñetas son cambio de equipo: se revisan en PR como cualquier otra línea de `CLAUDE.md`.
+
+---
+
+## Fase 5: Estampar el slice como reflexionado
+
+Marca el/los slice(s) procesado(s) en `history[]` para que el nudge calle. Usa la hora UTC real:
+
+```bash
+NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+python3 - "$NOW" "<openspec_change>" <<'PY'
+import json, sys
+now, change = sys.argv[1], sys.argv[2]
+p = ".claude/state/build-state.json"
+d = json.load(open(p))
+for h in d.get("history") or []:
+    if h.get("openspec_change") == change:
+        h["reflected"] = True
+        h["reflected_at"] = now
+json.dump(d, open(p, "w"), indent=2, ensure_ascii=False)
+print("estampado:", change)
+PY
+```
+
+Estampa **aunque no haya habido aprendizajes** (reflexionar y no encontrar nada también cierra el
+ciclo). Repite por cada slice procesado.
+
+---
+
+## Fase 6: Confirmación
+
+```
+## ✓ Reflexión completada
+
+Slice:        <EP-XXX> (<openspec_change>)
+Aprendizajes: <N agregados a CLAUDE.md> · <M a auto-memory> · <0 si solo se estampó>
+Estampado:    reflected=true
+
+Pendientes de reflexión restantes: <K>
+```
+
+Si quedan slices pendientes (`K > 0`), ofrece continuar con el siguiente.
+
+---
+
+## Guardrails
+
+- **Aprobación explícita siempre.** Nunca escribes a CLAUDE.md sin que el usuario apruebe cada
+  viñeta. Espeja la regla del scaffold: el arnés propone, el humano confirma.
+- **Evidencia, no invención.** Cada aprendizaje sale del change/diff/sesión reales. Si no hay
+  evidencia, no propongas.
+- **No reescribas.** Inserta viñetas; jamás borres ni reemplaces aprendizajes previos del equipo.
+- **No toques el paquete.** No modifiques agentes/skills/hooks del arnés (eso es mantenimiento, ver
+  `internal/skills/auditar-arnes`).
+- **Estampa siempre** al terminar, para no re-molestar con el mismo slice.
+- Si algo aquí contradice `METODOLOGIA.md`, **gana la metodología**.

package/dist/commands/doctor.js

@@ -66,6 +66,11 @@ export async function doctor(opts) {
             const st = JSON.parse(fs.readFileSync(t.stateFile, 'utf8'));
             const confirmed = st?.scaffold?.confirmed === true;
             console.log(`Scaffold (Paso 1): ${confirmed ? '✓ confirmado' : '✗ pendiente — confírmalo en building-a-slice (Fase 0) antes de fases de código'}`);
+            const hist = Array.isArray(st?.history) ? st.history : [];
+            const pend = hist.filter((h) => h?.reflected !== true).length;
+            if (pend > 0) {
+                console.log(`Reflexión:         ${pend} slice(s) archivado(s) sin reflexionar — ejecuta /build:reflect`);
+            }
         }
         catch {
             console.log('Scaffold (Paso 1): ⚠ build-state.json malformado');
@@ -83,6 +88,14 @@ export async function doctor(opts) {
         console.log('  Si además instalaste el plugin nativo, la cadena de comando es idéntica:');
         console.log('  Claude Code deduplica y el hook dispara UNA vez. No requiere acción.');
     }
+    // Sugerencia LSP para stacks tipados (informativa, NO es requisito) [pilar LSP]
+    const typed = detectTypedStack(targetDir);
+    if (typed) {
+        console.log('');
+        console.log(`ℹ Stack tipado detectado (${typed}). Considera activar LSP para precisión`);
+        console.log('  semántica (seguir símbolos/referencias como un compilador, mejor ROI que grep');
+        console.log('  en código tipado) — ver docs/customization/lsp-extensions.md');
+    }
     console.log('═══════════════════════════════════════');
     if (dep.missingHard.length > 0) {
         console.error(`\n✗ Faltan requisitos duros: ${dep.missingHard.join(', ')}. Instálalos antes de operar el arnés.`);
@@ -90,3 +103,25 @@ export async function doctor(opts) {
     }
     console.log('\n✓ Requisitos satisfechos.');
 }
+/** Señales de stack tipado donde LSP rinde (informativo; nunca un requisito). */
+function detectTypedStack(dir) {
+    const direct = [
+        ['pom.xml', 'Java/Maven'],
+        ['build.gradle', 'Java/Gradle'],
+        ['build.gradle.kts', 'Kotlin/Gradle'],
+        ['composer.json', 'PHP/Composer'],
+        ['tsconfig.json', 'TypeScript'],
+    ];
+    for (const [f, label] of direct) {
+        if (fs.existsSync(path.join(dir, f)))
+            return label;
+    }
+    try {
+        if (fs.readdirSync(dir).some((e) => e.endsWith('.csproj') || e.endsWith('.sln')))
+            return 'C#/.NET';
+    }
+    catch {
+        /* dir ilegible: sin sugerencia */
+    }
+    return null;
+}

package/dist/commands/init.js

@@ -15,6 +15,8 @@ import { captureStack, renderAllowlist } from '../lib/stack-prompt.js';
 import { checkDeps } from './doctor.js';
 const BEGIN = '<!-- BEGIN trycore-build-harness ';
 const END = '<!-- END trycore-build-harness -->';
+const LEARN_BEGIN = '<!-- BEGIN trycore-build-learnings -->';
+const LEARN_END = '<!-- END trycore-build-learnings -->';
 const GI_BEGIN = '# ── trycore-build-harness (auto)';
 const GI_END = '# ── /trycore-build-harness';
 export async function init(opts) {
@@ -87,20 +89,41 @@ function syncClaudeMdBlock(targetDir, version) {
     const template = fs
         .readFileSync(ASSETS.templateClaudeMd, 'utf8')
         .replace(/\{\{BUILD_HARNESS_VERSION\}\}/g, version);
-    const lines = template.split('\n');
-    const b = lines.findIndex((l) => l.includes(BEGIN));
-    const e = lines.findIndex((l) => l.includes(END));
-    if (b === -1 || e === -1)
-        throw new Error('CLAUDE.md.template sin markers BEGIN/END trycore-build-harness');
-    const blockContent = lines.slice(b, e + 1).join('\n');
+    // CLAUDE.md nuevo: el template completo ya incluye ambos bloques (arnés + aprendizajes).
     if (!fs.existsSync(t.claudeMd)) {
         fs.writeFileSync(t.claudeMd, template, 'utf8');
         console.log('  ✓ CLAUDE.md creado desde template');
+        return;
+    }
+    // Bloque del arnés: siempre upsert (refresca versión/contenido en cada init/update).
+    const harnessBlock = extractBlock(template, BEGIN, END);
+    const action = upsertMarkedBlock({ beginMarker: BEGIN, endMarker: END, blockContent: harnessBlock, filePath: t.claudeMd });
+    console.log(`  ✓ Bloque trycore-build-harness ${action === 'replaced' ? 'actualizado' : 'anexado'} en CLAUDE.md`);
+    // Bloque de aprendizajes: SOLO sembrar si falta. NUNCA reemplazar — un update no debe
+    // borrar las convenciones que /build:reflect acumuló.
+    const current = fs.readFileSync(t.claudeMd, 'utf8');
+    if (!current.includes(LEARN_BEGIN)) {
+        const learnBlock = extractBlock(template, LEARN_BEGIN, LEARN_END);
+        upsertMarkedBlock({ beginMarker: LEARN_BEGIN, endMarker: LEARN_END, blockContent: learnBlock, filePath: t.claudeMd });
+        console.log('  ✓ Bloque trycore-build-learnings sembrado en CLAUDE.md');
     }
-    else {
-        const action = upsertMarkedBlock({ beginMarker: BEGIN, endMarker: END, blockContent, filePath: t.claudeMd });
-        console.log(`  ✓ Bloque trycore-build-harness ${action === 'replaced' ? 'actualizado' : 'anexado'} en CLAUDE.md`);
+}
+/** Extrae el bloque [begin..end] inclusive de un texto (para sembrar desde el template). */
+function extractBlock(template, begin, end) {
+    const lines = template.split('\n');
+    const b = lines.findIndex((l) => l.includes(begin));
+    if (b === -1)
+        throw new Error(`CLAUDE.md.template sin marker de inicio: ${begin}`);
+    let e = -1;
+    for (let i = b; i < lines.length; i++) {
+        if (lines[i].includes(end)) {
+            e = i;
+            break;
+        }
     }
+    if (e === -1)
+        throw new Error(`CLAUDE.md.template sin marker de fin: ${end}`);
+    return lines.slice(b, e + 1).join('\n');
 }
 function syncGitignoreBlock(targetDir, mode) {
     const t = targetPaths(targetDir);

package/dist/commands/status.js

@@ -51,6 +51,10 @@ export async function status(opts) {
                 console.log('  Slice activo: ninguno');
             }
             console.log(`  Historial:  ${(st.history ?? []).length} slice(s) · Releases: ${(st.releases ?? []).length}`);
+            const sinReflexionar = (st.history ?? []).filter((h) => h?.reflected !== true).length;
+            if (sinReflexionar > 0) {
+                console.log(`  Sin reflexionar: ${sinReflexionar} slice(s) — ejecuta /build:reflect`);
+            }
         }
         catch {
             console.log('  ⚠ build-state.json malformado');

package/dist/commands/uninstall.js

@@ -30,8 +30,9 @@ export async function uninstall(opts) {
     // 2) Marca de versión
     if (fs.existsSync(t.versionFile))
         fs.rmSync(t.versionFile, { force: true });
-    // 3) Bloques marcados
+    // 3) Bloques marcados (arnés + aprendizajes + .gitignore)
     removeMarkedBlock(t.claudeMd, BEGIN, END);
+    removeMarkedBlock(t.claudeMd, LEARN_BEGIN, LEARN_END);
     removeMarkedBlock(t.gitignore, GI_BEGIN, GI_END);
     // 4) Hooks + permisos del arnés en settings.json (por cadena exacta)
     removeHarnessSettings(t.settingsFile);
@@ -40,6 +41,8 @@ export async function uninstall(opts) {
 }
 const BEGIN = '<!-- BEGIN trycore-build-harness ';
 const END = '<!-- END trycore-build-harness -->';
+const LEARN_BEGIN = '<!-- BEGIN trycore-build-learnings -->';
+const LEARN_END = '<!-- END trycore-build-learnings -->';
 const GI_BEGIN = '# ── trycore-build-harness (auto)';
 const GI_END = '# ── /trycore-build-harness';
 function isSymlink(p) {

package/dist/lib/settings-merge.js

@@ -20,7 +20,7 @@ const HOOK_SPECS = [
     { event: 'PreToolUse', matcher: 'Bash', scripts: ['gitflow-guard.sh'] },
     { event: 'PreToolUse', matcher: 'Write|Edit|MultiEdit', scripts: ['stack-guard.sh', 'scaffold-guard.sh'] },
     { event: 'PostToolUse', matcher: 'Write|Edit|MultiEdit', scripts: ['lint-typecheck.sh', 'coherence-flag.sh'] },
-    { event: 'Stop', matcher: '.*', scripts: ['build-gate-check.sh'] },
+    { event: 'Stop', matcher: '.*', scripts: ['build-gate-check.sh', 'reflect-nudge.sh'] },
 ];
 /** Permisos MÍNIMOS y enumerados [H11]. Nunca permisos amplios (mcp__*, additionalDirectories…). */
 const MIN_PERMISSIONS = [

package/docs/commands.md

@@ -2,8 +2,8 @@
 
 Esta referencia cubre los **dos planos de operación** del arnés de construcción:
 
-1. El **CLI `trycore-build`** (binario Node, paquete `@trycore/spec-build-harness` v0.1.0) — instala, actualiza, diagnostica y desinstala el arnés en el proyecto consumidor. Captura el **stack mecánico**.
-2. Los **slash commands de Claude Code** (`/opsx:*` + `/build:onboard`) — operan el pipeline de dos loops y resuelven la parametrización **semántica** del dominio.
+1. El **CLI `trycore-build`** (binario Node, paquete `@trycore/spec-build-harness` v0.3.0) — instala, actualiza, diagnostica y desinstala el arnés en el proyecto consumidor. Captura el **stack mecánico**.
+2. Los **slash commands de Claude Code** (`/opsx:*` + `/build:onboard` + `/build:reflect`) — operan el pipeline de dos loops, resuelven la parametrización **semántica** del dominio y capturan el conocimiento aprendido por slice.
 
 > **División de responsabilidades del onboarding (dos capas).** Un binario Node **no puede** escribir la auto-memory de Claude. Por eso `trycore-build init` siembra archivos y captura el stack mecánico (lenguaje/deps, package manager, runtime, ruta del PRD), y el slash command `/build:onboard` —ejecutado por Claude— lee el PRD, pregunta por PII / capa de servicios externos-IA / capa determinista / secretos / decisiones de alto impacto, resuelve los `{{placeholders}}` del bloque marcado de `CLAUDE.md` y escribe la auto-memory.
 
@@ -52,7 +52,7 @@ Solo `init` y `update` aceptan flags. `status`, `uninstall` y `doctor` toman ún
 
 ## 2. Slash commands de Claude Code
 
-El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y `.claude/commands/build/` → `/build:onboard`.
+El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y `.claude/commands/build/` → `/build:onboard` y `/build:reflect`.
 
 ### `/opsx:*` — pipeline OpenSpec
 
@@ -75,6 +75,12 @@ El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y
 |---|---|
 | `/build:onboard` | Parametriza el dominio del arnés: capa de servicios externos/IA, lógica determinista, PII, secretos y decisiones de alto impacto. Lee el PRD, pregunta vía AskUserQuestion, rellena el bloque marcado de `CLAUDE.md` y escribe la auto-memory. **Complementa** a `trycore-build init` (que ya sembró archivos y el stack mecánico). |
 
+### `/build:reflect` — reflexión post-slice (ciclo autocorrectivo)
+
+| Slash command | Propósito |
+|---|---|
+| `/build:reflect` | Tras archivar un slice, detecta **convenciones aprendidas** / errores recurrentes (a partir del change, el diff y la sesión) y **propone** viñetas para el bloque `trycore-build-learnings` de `CLAUDE.md`; las aplica **solo tras tu aprobación** y estampa el slice como reflexionado (`reflected: true`). Lo **sugiere** el hook `reflect-nudge.sh` al cerrar sesión, pero puedes invocarlo cuando quieras. No toca el bloque de dominio ni sus `{{placeholders}}` (eso es de `/build:onboard`). |
+
 ---
 
 ## 3. Caveat de canales (CLI vs. plugin)
@@ -84,7 +90,7 @@ El arnés se distribuye por **dos canales** que coexisten, pero **namespacean di
 | Aspecto | Canal **CLI** (canónico) | Canal **Plugin** nativo |
 |---|---|---|
 | Instalación | `npm i -g @trycore/spec-build-harness` → `trycore-build init` | `/plugin marketplace add <repo-github>` → `/plugin install trycore-spec-build-harness@trycore-build` |
-| Namespace de comandos | Por subcarpeta: `/opsx:*` y `/build:onboard` | Por nombre del plugin: `/trycore-spec-build-harness:*` (por diseño de Claude Code) |
+| Namespace de comandos | Por subcarpeta: `/opsx:*`, `/build:onboard` y `/build:reflect` | Por nombre del plugin: `/trycore-spec-build-harness:*` (por diseño de Claude Code) |
 | Referencia a agentes | Por su nombre (p. ej. `build-orchestrator`) | Bajo el nombre del plugin |
 | Cross-references internas | ✔ Escritas para este canal (skills invocan `/opsx:*`, agentes por nombre) | Pueden no resolver según están escritas |
 | Recomendación | **Usar este canal para operar un proyecto** | Conveniencia a nivel usuario |

package/docs/customization/lsp-extensions.md

@@ -0,0 +1,90 @@
+# Extensión LSP del arnés (opt-in, agnóstico)
+
+> Guía de personalización para **consumidores** de `@trycore/spec-build-harness`. Explica cómo
+> aprovechar **LSP** (Language Server Protocol) para que Claude Code navegue tu código con
+> **precisión de símbolo** en vez de búsqueda de texto. **Todo lo de aquí es opcional.** El core es
+> 100 % agnóstico: ningún gate, skill ni agente **depende** de LSP. Sin LSP, el arnés funciona igual
+> navegando con `grep`/`glob` + lectura dirigida.
+
+## TL;DR
+
+- **LSP = precisión de compilador** para Claude Code: seguir la definición exacta de un símbolo,
+  distinguir homónimos, listar referencias cruzadas. En monorepos tipados, `grep` devuelve ruido y
+  falsos positivos; LSP no.
+- **Mayor ROI en lenguajes tipados**: Java/Kotlin, C#, C/C++, PHP, TypeScript. `trycore-build doctor`
+  detecta señales de estos stacks y **sugiere** activarlo (es una nota informativa, **no** un
+  requisito).
+- **Complementa, no reemplaza** a MCP: LSP es precisión **intra-repo** (símbolos del código); MCP es
+  conectividad a sistemas **externos** (Jira, BD, telemetría). Ver `mcp-extensions.md`.
+- Regla de oro: **opt-in**. Lo habilitas **tú** en tu entorno; el arnés solo lo recomienda donde
+  rinde.
+
+## Por qué LSP y no solo `grep`
+
+El arnés define cada gate por su **resultado verificable**, no por la herramienta que lo produce
+(misma filosofía que las extensiones MCP). Pero la fase de **exploración/navegación** del código —que
+alimenta a los agentes de coherencia, diseño y arquitectura— mejora drásticamente con precisión
+semántica:
+
+| Tarea de navegación | Con `grep`/`glob` | Con LSP habilitado |
+|---|---|---|
+| "¿Dónde se define este método?" | Coincidencias de texto; homónimos mezclados. | La **definición exacta**, sin ruido. |
+| "¿Quién usa este símbolo?" | Falsos positivos (comentarios, strings, nombres parecidos). | Referencias **reales** del compilador. |
+| "Trazar símbolo → test" | Lectura manual encadenada. | Salto directo definición↔referencias. |
+| "¿Hay duplicación / código muerto?" | Difícil de afirmar con texto. | Referencias vacías = candidato a muerto. |
+
+Por eso, en stacks tipados grandes, LSP es la inversión de mayor ROI para la fase de exploración: el
+subagente que **lee** (mapea el subsistema) devuelve una síntesis más fiel, protegiendo la ventana de
+contexto para la fase de **edición**.
+
+## Cuándo rinde (por stack)
+
+| Stack | Señal que detecta `doctor` | Por qué rinde LSP |
+|---|---|---|
+| Java / Kotlin | `pom.xml`, `build.gradle(.kts)` | Tipado fuerte + dependencias profundas (Spring): `grep` se ahoga. |
+| C# / .NET | `*.csproj`, `*.sln` | Símbolos y namespaces densos; refactors guiados por tipo. |
+| C / C++ | (no autodetectado; CMake/Make ambiguos) | Macros y headers hacen inútil la búsqueda de texto. |
+| PHP | `composer.json` | Autoload + magia dinámica: seguir definiciones reales ayuda. |
+| TypeScript | `tsconfig.json` | Tipos estructurales; el LSP de TS distingue lo que `grep` no. |
+
+En lenguajes **dinámicos sin tipos** (p.ej. scripts sueltos), el ROI de LSP es menor; ahí `grep`/`glob`
+suele bastar y el arnés no lo sugiere.
+
+## Cómo activarlo (en TU entorno)
+
+LSP es una capacidad **del cliente Claude Code**, no algo que el arnés instale o versione:
+
+1. Instala el **language server** de tu stack en tu máquina/imagen de dev (cada lenguaje tiene el
+   suyo; sigue la doc del servidor que elijas).
+2. Habilita la integración LSP en **tu** configuración de Claude Code (a nivel proyecto o usuario),
+   no en el arnés.
+3. A partir de ahí, Claude Code puede navegar con precisión semántica durante la fase de exploración
+   de `building-a-slice` y para los agentes `coherence-three-way`, `simple-design-reviewer` y
+   `stack-guardian`.
+
+> El arnés nunca levanta el servidor por ti ni versiona su configuración: la frontera (qué servidor,
+> con qué permisos) es **tuya**.
+
+## Relación con MCP
+
+No son lo mismo y conviven:
+
+- **LSP** → precisión de **símbolo** dentro del repo (definiciones, referencias, jerarquía de tipos).
+- **MCP** → conectividad a **sistemas externos** fuera del repo (tickets, BD, navegador, carga).
+
+Un mismo proyecto puede usar ambos: LSP para entender el código tipado, MCP (opt-in) para acelerar
+gates que necesitan evidencia externa. Detalle de MCP por gate en `mcp-extensions.md` y el mapa
+operativo en `skills/building-a-slice/references/mcp-map.md`.
+
+## Reglas de uso
+
+1. **Opt-in.** El arnés solo **sugiere** LSP (vía `doctor`); habilitarlo es decisión del consumidor.
+2. **No es dependencia.** Ningún gate exige LSP. Si no está, la navegación cae a `grep`/`glob` y los
+   gates se cierran igual por su resultado verificable.
+3. **Portabilidad.** No escribas en agentes/skills/hooks del arnés instrucciones que **requieran**
+   LSP: manténlo como acelerador documentado.
+
+---
+
+**Fuente de verdad.** Si algo aquí contradice la metodología Trycore (`METODOLOGIA.md`), **gana la
+metodología**. Para extensiones MCP (y la relación MCP↔LSP por gate), ver `mcp-extensions.md`.

package/docs/customization/mcp-extensions.md

@@ -6,6 +6,9 @@
 > gate, skill ni agente **depende** de un MCP concreto. Si tu entorno no expone ningún MCP, el arnés
 > funciona igual cubriendo cada fase con sus alternativas CLI/test.
 
+> **LSP tiene guía dedicada.** Este documento cubre sobre todo **MCP**. Para **LSP** (precisión de
+> símbolo en stacks tipados: por qué, cuándo y cómo), ver **`lsp-extensions.md`**.
+
 ## TL;DR
 
 - Los gates **pueden apoyarse** en MCP/LSP como **aceleradores**, nunca como dependencia dura.

package/docs/getting-started.md

@@ -76,9 +76,9 @@ trycore-build init
 - **10 agentes** en `.claude/agents/build/` (build-orchestrator, dor-dod-gatekeeper,
   security-reviewer, simple-design-reviewer, ux-krug-reviewer, coherence-three-way, stack-guardian,
   api-contract-tester, data-consistency-checker, change-epic-coherence).
-- **Comandos** `/opsx:*` (10) en `.claude/commands/opsx/` + `/build:onboard` en `.claude/commands/build/`.
+- **Comandos** `/opsx:*` (10) en `.claude/commands/opsx/` + `/build:onboard` y `/build:reflect` en `.claude/commands/build/`.
 - **12 skills** en `.claude/skills/` (`building-a-slice`, `releasing-a-version`, 10 `openspec-*`).
-- **6 hooks** bash en `.claude/hooks/build/` + permisos mínimos en `settings.json`.
+- **8 hooks** bash en `.claude/hooks/build/` + permisos mínimos en `settings.json`.
 - **Estado**: `.claude/state/build-state.json` (sembrado **vacío** y **nunca** sobreescrito; va al
   `.gitignore`), más el schema y el README versionados.
 - **Config**: `.claude/config/stack-allowlist.json` (artefacto del consumidor; lo siembra el CLI y
@@ -136,10 +136,14 @@ trycore-build doctor
 Comprueba:
 
 - Los **3 requisitos duros** (`git`, `python3`, `openspec`) — **falla con exit 1** si falta alguno.
-- Que los **6 hooks** tengan bit ejecutable (si no, sugiere `trycore-build init --copy` o `chmod +x`).
+- Que los **8 hooks** tengan bit ejecutable (si no, sugiere `trycore-build init --copy` o `chmod +x`).
 - **Doble canal**: si detecta hooks del arnés en `settings.json` (canal CLI) y además instalaste el
   plugin, te recuerda que la cadena de comando es idéntica en ambos canales y Claude Code
   **deduplica** → el hook dispara **una sola vez**. No requiere acción.
+- **Reflexión y LSP (informativo, no falla):** reporta cuántos slices archivados están **sin
+  reflexionar** (sugiere `/build:reflect`) y, si detecta un stack tipado (`pom.xml`,
+  `build.gradle`, `*.csproj`, `tsconfig.json`…), sugiere activar **LSP**
+  (ver `docs/customization/lsp-extensions.md`).
 
 Si ves `✓ Requisitos satisfechos.`, continúa.
 
@@ -211,6 +215,10 @@ Notas clave del inner loop:
   (bloquea commits/push directos a `main` — integras solo por **PR**).
 - **El enlace change↔épica** va en el bloque `## Trazabilidad` del `proposal.md`, **nunca** en
   frontmatter YAML (rompe `openspec validate`).
+- **Reflexión (ciclo autocorrectivo).** Tras archivar el slice, `/build:reflect` puede capturar las
+  convenciones aprendidas / errores recurrentes en el bloque `trycore-build-learnings` de
+  `CLAUDE.md` (con tu aprobación). Lo **sugiere** el hook `reflect-nudge.sh` al cerrar la sesión;
+  es opcional y no bloquea.
 - Objetivo: **≤ ~20 min por épica**, y producto que **camina end-to-end en todo momento**.
 
 ---
@@ -252,6 +260,7 @@ trycore-build doctor                                        # paso 3
 # en Claude Code:
 /build:onboard                                              # paso 4
 skill building-a-slice   # EP-XXX: DoR → /opsx:new → TDD → smoke → DoD → PR   # paso 5
+/build:reflect           # opcional: captura aprendizajes del slice recién archivado
 # y cuando cierres una línea de release del Story Map:
 skill releasing-a-version                                   # paso 6
 ```

package/docs/hooks.md

@@ -1,23 +1,25 @@
 # Hooks del arnés de construcción
 
-Este documento describe los **6 hooks** que `@trycore/spec-build-harness` instala en el proyecto del consumidor. Todos viven en `hooks/build/` (un script bash por hook) y se cablean a los eventos de Claude Code mediante una **cadena de comando única**, idéntica en ambos canales de instalación.
+Este documento describe los **8 hooks** que `@trycore/spec-build-harness` instala en el proyecto del consumidor. Todos viven en `hooks/build/` (un script bash por hook) y se cablean a los eventos de Claude Code mediante una **cadena de comando única**, idéntica en ambos canales de instalación.
 
-Los hooks son el sistema nervioso del arnés: vigilan GitFlow y el stack declarado (bloqueantes), inyectan el estado del build al iniciar la sesión, delegan estilo/typecheck a herramientas, y recuerdan validar trazabilidad y gates abiertos. No reemplazan a los agentes ni a las skills; los **complementan** liberando capacidad de razonamiento del modelo y poniendo barandillas mecánicas donde un olvido cuesta caro.
+Los hooks son el sistema nervioso del arnés: vigilan GitFlow, el stack declarado y el scaffold (bloqueantes), inyectan el estado del build al iniciar la sesión, delegan estilo/typecheck a herramientas, y recuerdan validar trazabilidad, gates abiertos y reflexionar al cerrar un slice. No reemplazan a los agentes ni a las skills; los **complementan** liberando capacidad de razonamiento del modelo y poniendo barandillas mecánicas donde un olvido cuesta caro.
 
 ---
 
-## Resumen de los 6 hooks
+## Resumen de los 8 hooks
 
 | Hook | Evento | Matcher | Qué hace | ¿Bloqueante? |
 |---|---|---|---|---|
 | `load-build-state.sh` | `SessionStart` | `startup\|clear\|compact` | Inyecta al contexto la rama, la fase del arnés, el slice activo y los gates abiertos; sincroniza `harness_phase`. | No |
 | `gitflow-guard.sh` | `PreToolUse` | `Bash` | Enforce GitHub Flow estricto sobre `git commit` / `git push`. | **Sí (exit 2)** |
 | `stack-guard.sh` | `PreToolUse` | `Write\|Edit\|MultiEdit` | Bloquea dependencias en `package.json` fuera de la allowlist del stack del PRD. | **Sí (exit 2)** |
+| `scaffold-guard.sh` | `PreToolUse` | `Write\|Edit\|MultiEdit` | Bloquea escribir código de slice (fases `red…data`) si el scaffold no está confirmado (`scaffold.confirmed`). | **Sí (exit 2)** |
 | `lint-typecheck.sh` | `PostToolUse` | `Write\|Edit\|MultiEdit` | Corre prettier/eslint/tsc sobre el archivo `.ts`/`.tsx` editado. | No |
 | `coherence-flag.sh` | `PostToolUse` | `Write\|Edit\|MultiEdit` | Recuerda validar la trazabilidad de un `proposal.md` de OpenSpec recién tocado. | No |
 | `build-gate-check.sh` | `Stop` | `.*` | Al cerrar el turno, avisa si el slice activo tiene gates abiertos. | No |
+| `reflect-nudge.sh` | `Stop` | `.*` | Al cerrar el turno, sugiere `/build:reflect` si hay slice(s) archivado(s) sin reflexionar (`reflected != true`). | No |
 
-> Dos bloqueantes (`gitflow-guard`, `stack-guard`) y cuatro informativos. Los bloqueantes usan `exit 2`: Claude Code devuelve el `stderr` al modelo y aborta la herramienta; el resto siempre sale `0`.
+> Tres bloqueantes (`gitflow-guard`, `stack-guard`, `scaffold-guard`) y cinco informativos. Los bloqueantes usan `exit 2`: Claude Code devuelve el `stderr` al modelo y aborta la herramienta; el resto siempre sale `0`.
 
 ---
 
@@ -58,7 +60,11 @@ Tras editar un archivo `.ts`/`.tsx`, delega el estilo a las herramientas para no
 
 - `prettier --write` sobre el archivo.
 - `eslint --fix` sobre el archivo (primeras 20 líneas de salida a `stderr`).
-- `tsc --noEmit` y filtra los errores que mencionan el archivo editado.
+- `tsc --noEmit --incremental` con un `tsBuildInfoFile` persistente, y filtra los errores que mencionan el archivo editado.
+
+**Typecheck incremental (desde v0.3.x).** `tsc` siempre recorre todo el grafo de tipos del proyecto, no solo el archivo editado. Para que ese coste no escale con el tamaño del repo en cada edición, el hook usa `--incremental` con un `tsBuildInfoFile` en `node_modules/.cache/trycore-build/tsbuildinfo`: el **primer** typecheck de la sesión paga `O(repo)` y cada edición posterior paga `~O(delta)`. El cache vive bajo `node_modules/` (que el consumidor casi siempre tiene gitignored), así que no contamina el repo. El typecheck va envuelto en `timeout 60` **si** `timeout`/`gtimeout` (coreutils) está disponible; si no, corre sin límite (al ser no bloqueante, agotar el tiempo solo omite el reporte de esa edición).
+
+> **Caveat `composite`:** en proyectos con `composite: true` en `tsconfig.json`, el typecheck canónico es `tsc -b`. Aquí `--noEmit` prevalece (igual que antes) y los posibles errores de configuración se suprimen (`|| true`); el reporte de tipos puede quedar vacío. No es una regresión respecto al comportamiento previo.
 
 Nunca bloquea (siempre `exit 0`); reporta a `stderr` como información. Inerte si no hay `package.json` o si el archivo no es `.ts`/`.tsx`.
 
@@ -70,6 +76,14 @@ Cuando se edita un `openspec/changes/**/proposal.md`, imprime un recordatorio: c
 
 Al cerrar el turno, si hay un slice activo con gates en `false`, avisa por `stderr` qué gates quedan abiertos y recuerda **no archivar ni abrir PR** hasta cerrarlos (ver skill `building-a-slice` / `dod.md`). Inerte si no hay `package.json`, ni estado, ni `python3`.
 
+### 7. `scaffold-guard.sh` — `PreToolUse` · Write/Edit/MultiEdit · **bloqueante** (desde v0.2.0)
+
+Refuerza el **scaffold como "Paso 1 fundamental"**. Bloquea con `exit 2` la escritura de **código de slice** —cuando `active_slice.phase` ∈ `red`/`green`/`refactor`/`smoke`/`api`/`data`— mientras `scaffold.confirmed` no sea `true` en `build-state.json`. **Permite** crear el scaffold (sin slice activo, o en fases `dor`/`change`). El arnés **exige** el scaffold pero **no lo genera**; la confirmación es **explícita** (vía `building-a-slice` Fase 0 / `dor-dod-gatekeeper`), nunca auto-detectada. Guarda `python3` fail-closed dirigido (solo bloquea si la entrada parece código de slice).
+
+### 8. `reflect-nudge.sh` — `Stop` · no bloqueante (desde v0.3.0)
+
+Cierra el **ciclo autocorrectivo**. Al terminar el turno, si en `history[]` hay slice(s) archivado(s) con `reflected != true`, imprime un *nudge* sugiriendo ejecutar `/build:reflect` para capturar las convenciones aprendidas (y errores recurrentes) en el bloque `trycore-build-learnings` de `CLAUDE.md`. **Nunca bloquea** el cierre de sesión: si falta `python3` o el estado, sale `0` en silencio (**fail-open**). El razonamiento —qué se aprendió— vive en el comando `/build:reflect`, no en el hook; este solo recuerda. Tras reflexionar y estampar `reflected: true`, el nudge calla.
+
 ---
 
 ## La cadena de comando única (sin doble disparo entre canales)
@@ -93,8 +107,8 @@ Como la cadena es **carácter por carácter idéntica** en ambos canales, si el
 
 Los hooks parsean el JSON del evento con `python3`. Qué pasa si **falta** `python3` depende de si el hook es bloqueante:
 
-- **Bloqueantes** (`gitflow-guard`, `stack-guard`) → **fail-closed dirigido**: si no pueden analizar el comando/edición, solo bloquean (`exit 2`) cuando la entrada *cruda* parece relevante (un `git commit`/`push`, o una edición que menciona `package.json`); en cualquier otro caso salen `0`. Esto evita falsos negativos peligrosos sin frenar el trabajo no relacionado. El mensaje pide instalar `python3` (verificable con `trycore-build doctor`).
-- **No bloqueantes** (`load-build-state`, `lint-typecheck`, `coherence-flag`, `build-gate-check`) → si falta `python3`, simplemente **omiten** su trabajo y salen `0`.
+- **Bloqueantes** (`gitflow-guard`, `stack-guard`, `scaffold-guard`) → **fail-closed dirigido**: si no pueden analizar el comando/edición, solo bloquean (`exit 2`) cuando la entrada *cruda* parece relevante (un `git commit`/`push`, una edición que menciona `package.json`, o código de slice sin scaffold confirmado); en cualquier otro caso salen `0`. Esto evita falsos negativos peligrosos sin frenar el trabajo no relacionado. El mensaje pide instalar `python3` (verificable con `trycore-build doctor`).
+- **No bloqueantes** (`load-build-state`, `lint-typecheck`, `coherence-flag`, `build-gate-check`, `reflect-nudge`) → si falta `python3`, simplemente **omiten** su trabajo y salen `0` (fail-open).
 
 > `python3` es un **requisito duro**: `trycore-build init` y `trycore-build doctor` **fallan** si no está presente, justo porque toda la cadena de hooks depende de él para leer el JSON del evento.
 
@@ -111,7 +125,9 @@ Los hooks que tocan el código construido se **auto-arman**: permanecen **inerte
 | `stack-guard.sh` | Inerte si no existe la allowlist; sin `package.json` que comparar, no hay violación que detectar. |
 | `lint-typecheck.sh` | Inerte (sale `0` de inmediato). |
 | `coherence-flag.sh` | Funciona siempre (depende de OpenSpec, no del código). |
+| `scaffold-guard.sh` | Permite (sin slice en fases de código no hay nada que bloquear; también permite crear el scaffold). |
 | `build-gate-check.sh` | Inerte (sale `0` de inmediato). |
+| `reflect-nudge.sh` | Silencioso (en `authoring` no hay slices archivados que reflexionar). |
 
 Así el arnés convive sin fricción con la fase de *discovery* y se "enciende" cuando empieza la construcción real.
 
@@ -125,7 +141,7 @@ Una sola definición de hooks, expresada en dos archivos espejo según el canal:
 
 `trycore-build init` hace un **merge idempotente y aditivo** en el `settings.json` del consumidor (lógica en `src/lib/settings-merge.ts`; espejo documental en `templates/settings-hooks.template.json`):
 
-- Agrega las 5 agrupaciones de hooks (las 6 invocaciones: `PostToolUse` agrupa `lint-typecheck` + `coherence-flag`) sin pisar lo que ya exista.
+- Agrega las 5 agrupaciones de hooks (las 8 invocaciones: `PreToolUse·Write` agrupa `stack-guard` + `scaffold-guard`; `PostToolUse·Write` agrupa `lint-typecheck` + `coherence-flag`; `Stop` agrupa `build-gate-check` + `reflect-nudge`) sin pisar lo que ya exista.
 - Agrega **permisos mínimos y enumerados** (sin `mcp__*` ni rutas absolutas):
 
   ```

package/hooks/build/lint-typecheck.sh

@@ -3,6 +3,9 @@
 # AUTO-ARME: inerte mientras no exista package.json (fase authoring).
 # No bloquea: reporta lint/format/typecheck del archivo editado para liberar
 # capacidad de razonamiento del modelo (estilo delegado a herramientas).
+# El typecheck es INCREMENTAL (--incremental + tsBuildInfoFile persistente): el primer
+# run de la sesión paga O(repo) y cada edición posterior paga ~O(delta), para que el
+# coste por edición no escale con el tamaño del repo.
 set -uo pipefail
 
 ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$(pwd)}")"
@@ -29,5 +32,22 @@ HAS() { [ -d node_modules ] && [ -x "node_modules/.bin/$1" ]; }
 
 if HAS prettier; then node_modules/.bin/prettier --write "$FILE" >/dev/null 2>&1 || true; fi
 if HAS eslint;   then node_modules/.bin/eslint --fix "$FILE" 2>&1 | sed -n '1,20p' >&2 || true; fi
-if HAS tsc;      then node_modules/.bin/tsc --noEmit 2>&1 | grep -F "$FILE" | sed -n '1,20p' >&2 || true; fi
+
+# Typecheck INCREMENTAL del proyecto. `tsc` siempre recorre todo el grafo de tipos, pero con
+# --incremental + un tsBuildInfoFile persistente, tras el primer run cada edición paga solo el delta.
+# El .tsbuildinfo vive bajo node_modules/ (que el consumidor casi siempre tiene gitignored) → no
+# contamina el repo. Filtramos la salida al archivo editado (grep -F) y la capamos a 20 líneas.
+# timeout OPCIONAL: si coreutils está disponible acota un tsconfig patológico; si no, corre sin
+# límite (el hook nunca bloquea, así que agotar el timeout solo omite el reporte de esta edición).
+# Caveat: proyectos con `composite: true` deben usar `tsc -b`; aquí --noEmit prevalece como hoy
+# y los errores se suprimen (|| true), igual que antes de v0.3.x.
+if HAS tsc; then
+  TSBI="node_modules/.cache/trycore-build/tsbuildinfo"
+  mkdir -p "$(dirname "$TSBI")" 2>/dev/null || true
+  TSC_TIMEOUT=""
+  if   command -v timeout  >/dev/null 2>&1; then TSC_TIMEOUT="timeout 60"
+  elif command -v gtimeout >/dev/null 2>&1; then TSC_TIMEOUT="gtimeout 60"; fi
+  $TSC_TIMEOUT node_modules/.bin/tsc --noEmit --incremental --tsBuildInfoFile "$TSBI" 2>&1 \
+    | grep -F "$FILE" | sed -n '1,20p' >&2 || true
+fi
 exit 0

package/hooks/build/reflect-nudge.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# reflect-nudge.sh — Stop
+# Ciclo autocorrectivo (reflexión post-sesión): NUNCA bloquea el cierre de sesión.
+# Sugiere /build:reflect SOLO si hay slice(s) archivado(s) sin reflexionar (reflected != true).
+# Determinista y barato: el razonamiento (qué se aprendió) lo hace el MODELO en /build:reflect.
+set -uo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$(pwd)}")"
+STATE="$ROOT/.claude/state/build-state.json"
+[ -f "$STATE" ] || exit 0
+command -v python3 >/dev/null 2>&1 || exit 0   # fail-open: jamás impide cerrar sesión
+
+# Mensaje a STDOUT (no stderr): un Stop hook con exit 0 no debe bloquear el cierre;
+# el `2>/dev/null` suprime SOLO trazas de python, nunca el nudge.
+python3 - "$STATE" <<'PY' 2>/dev/null || true
+import json, sys
+try:
+    d = json.load(open(sys.argv[1]))
+except Exception:
+    sys.exit(0)
+hist = d.get("history") or []
+pend = [h for h in hist if isinstance(h, dict) and h.get("reflected") is not True]
+if pend:
+    n = len(pend)
+    plural = "s" if n != 1 else ""
+    print(f"💡 Reflexión pendiente: {n} slice{plural} archivado{plural} sin capturar aprendizajes.")
+    print("   Ejecuta /build:reflect para proponer convenciones aprendidas a CLAUDE.md (se aplican tras tu aprobación).")
+PY
+exit 0

package/hooks/build-harness.json

@@ -57,6 +57,10 @@
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/build-gate-check.sh\""
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/reflect-nudge.sh\""
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trycore/spec-build-harness",
-  "version": "0.2.0",
+  "version": "0.4.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": {
@@ -18,6 +18,7 @@
     "templates/",
     "internal/",
     "docs/",
+    "!docs/superpowers",
     "scripts/",
     "METODOLOGIA.md",
     "GOVERNANCE.md",

package/skills/building-a-micro-change/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: building-a-micro-change
+description: Use for genuine maintenance that is NOT new product capability — a typo, a copy/string tweak, a dependency version bump within the stack allowlist, an infra/config/docs change, or a small bug fix of a few lines that adds no new capability. Lightweight lane — branch fix/*|chore/* → change → regression test only if behavior changes → PR — WITHOUT opening active_slice, an epic (EP-XXX), or an OpenSpec change. HARD LIMITS: escalate to building-a-slice (a full epic) if the change adds a new dependency, creates a new public API/endpoint, or changes domain logic or the data model/invariants. The epic stays the unit for product construction; this lane is out-of-band maintenance only.
+---
+
+# Micro-change (mantenimiento) — carril ligero
+
+Carril para **mantenimiento que no es construcción de producto nueva**. Espeja la filosofía del
+arnés: la épica es la unidad de **construcción**, pero un typo o un bump de dependencia **no son
+construcción** — forzarlos por las 8 fases de `building-a-slice` es ceremonia desproporcionada. Este
+carril les da una vía corta **sin** diluir los guardarraíles deterministas.
+
+> **Si una regla aquí contradice la metodología Trycore (`METODOLOGIA.md`), gana la metodología.**
+
+## Paso 0 · Decision gate (obligatorio) — ¿es esto un micro-change?
+
+Un cambio califica como micro-change **solo si cumple TODO**:
+
+- **No añade capacidad de producto nueva.** Corrige, ajusta o mantiene algo que ya existe.
+- **Alcance acotado:** pocas líneas / una sola preocupación. No toca múltiples módulos a la vez.
+- **Proyecto en fase `active`** (el scaffold runnable ya existe y está confirmado). El carril **no**
+  es para arrancar proyectos (eso es la Fase 0 de `building-a-slice`).
+
+Ejemplos típicos (neutros): corregir un typo o un texto visible; ajustar un valor de configuración;
+actualizar la versión de una dependencia **ya presente en la allowlist**; cambios de docs; un fix de
+una a pocas líneas que repara un comportamiento sin introducir nada nuevo.
+
+### Límites DUROS — si el cambio cruza **cualquiera**, STOP: esto es una épica
+
+Escala a `building-a-slice` (abre una épica `EP-XXX` con su DoR) si el cambio:
+
+1. **Añade una dependencia nueva** (fuera de `stack-allowlist.json`). *Lo bloquea además
+   `stack-guard.sh` de forma determinista.*
+2. **Crea un endpoint o una API pública nueva.**
+3. **Cambia lógica de dominio** o el **modelo/invariantes de datos**.
+4. **Desborda el alcance acotado** (introduce capacidad, toca muchos archivos, mezcla preocupaciones).
+
+Ante la duda, **es una épica**. El carril micro-change nunca es un atajo para esquivar gates de
+producto.
+
+## Pipeline ligero
+
+1. **Rama tipada.** Crea `fix/<slug>` (corrección) o `chore/<slug>` (infra/config/docs/bump).
+   `gitflow-guard.sh` ya exige rama tipada y prohíbe commit/push directo a `main`.
+2. **Aplica el cambio acotado.** Mantente dentro de los límites duros. Si al implementar descubres
+   que cruzas uno, **detente y escala** a `building-a-slice`.
+3. **Test de regresión — solo si cambia comportamiento.** Si el micro-change repara un bug,
+   añade/ajusta un test que falle antes y pase después (red→green del fix, delega en
+   `superpowers:test-driven-development`). Para cambios **no conductuales** (typo en copy, docs,
+   config) **no** se exige test.
+4. **PR a `main`.** Abre el Pull Request (`gitflow-guard.sh` impide la integración por push directo).
+   En la descripción del PR indica que es un micro-change y por qué califica (qué límite NO cruza).
+
+## Qué se mantiene y qué se salta
+
+| Se mantiene (gratis, vía hooks deterministas) | Se salta (por diseño) |
+|---|---|
+| `gitflow-guard` (rama tipada + PR) | DoR formal (escenarios G/W/T, INVEST) |
+| `stack-guard` (no dependencia nueva) | OpenSpec change + bloque `## Trazabilidad` |
+| `lint-typecheck` (estilo + typecheck incremental) | `journey_smoke`, `api`, `data`, DoD reducido |
+| | Apertura de `active_slice` / decisión de Release Gate |
+
+`scaffold-guard` no aplica: no hay slice activo y el carril exige proyecto en fase `active` (scaffold
+ya confirmado).
+
+## Estado y trazabilidad
+
+El micro-change **no escribe** `build-state.json` — es mantenimiento fuera de banda, trazado por el
+historial de git y el PR. No entra a `history[]`, así que `reflect-nudge.sh` **no** sugiere
+reflexionar por él (no hay aprendizaje de épica que capturar en un typo).
+
+## Reglas duras
+
+- **El decision gate es obligatorio.** Si dudas si algo es micro-change o épica, **es épica**.
+- **Límites duros = STOP, no excepción.** Cruzar un límite obliga a escalar a `building-a-slice`;
+  jamás se "fuerza" un micro-change para evitar el DoR.
+- **Integración solo por PR** a `main` (lo respalda `gitflow-guard.sh`).
+- Si una regla aquí contradice `METODOLOGIA.md`, **gana la metodología**.

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

@@ -14,6 +14,12 @@ el avance en el estado.
 > 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.
 
+> **¿Mantenimiento, no producto nuevo?** Un typo, un bump de dependencia ya permitida, un ajuste de
+> copy/config/docs o un fix de pocas líneas **sin nueva capacidad** NO abren una épica: usa la skill
+> **`building-a-micro-change`** (carril ligero `fix/*`|`chore/*` → cambio → PR). Si ese micro-change
+> cruza un **límite duro** (dependencia nueva, API/endpoint nuevo, lógica de dominio o datos), escala
+> **aquí** y ábrelo como épica.
+
 ## 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.

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

@@ -6,7 +6,7 @@ la épica; lo de abajo aplica a la épica y a **cada HU** que cubre (`hus[]`). L
 - [ ] **É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).
+- [ ] **AC en Given/When/Then** por HU, **proporcional a `complejidad`** (cubre los modos de fallo que *realmente existen*, no una cuota fija): `trivial`/baja → **1–2** (happy + el error/edge crítico si existe); `media` → **3** (happy + error + edge); `alta` → **3–5** (cobertura completa). Regla dura Trycore: si existe una rama de error/edge, **debe** tener su escenario (lo que se elimina es fabricar 3–5 para una HU trivial).
 - [ ] **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`).

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

@@ -16,7 +16,9 @@ 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`.
+  Una rama por **épica** (= un slice): `feature/ep-003-pricing-engine`. Las ramas `fix/*` y `chore/*`
+  son también el carril de la skill `building-a-micro-change` (mantenimiento que no es producto nuevo:
+  va a PR sin abrir épica ni `active_slice`; ver sus límites duros).
 - **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.

package/state/README.md

@@ -51,6 +51,15 @@ Arranca en `confirmed: false` y **solo** pasa a `true` por **confirmación expl
 restrictiva para abrir cualquier slice: el hook `scaffold-guard.sh` bloquea escribir código de
 slice (fases `red…data`) mientras `confirmed` no sea `true`. El arnés **no genera** el scaffold.
 
+### Reflexión post-slice (ciclo autocorrectivo)
+
+Tras archivar un slice, su entrada en `history[]` puede llevar `reflected` / `reflected_at`. El
+hook `reflect-nudge.sh` (evento `Stop`, **no bloqueante**) sugiere ejecutar `/build:reflect` mientras
+exista al menos una entrada con `reflected != true`. `/build:reflect` lo ejecuta el **modelo**:
+detecta convención nueva o error recurrente, **propone** un parche al bloque `trycore-build-learnings`
+de `CLAUDE.md` (se aplica **solo tras tu aprobación**) y estampa `reflected: true` → el nudge calla.
+El razonamiento vive en el modelo; el hook solo es un recordatorio determinista.
+
 ## Quién escribe qué
 
 | Campo / gate | Lo escribe | Cadencia |
@@ -62,4 +71,5 @@ slice (fases `red…data`) mientras `confirmed` no sea `true`. El arnés **no ge
 | `gates.api` | `api-contract-tester` | slice |
 | `gates.data` | `data-consistency-checker` | slice |
 | `releases[]` (`security`, `smell`, `ux`, `coherence`, `stack_arch`, `integration`, `status`) | `releasing-a-version` (delega en `security-reviewer`, `simple-design-reviewer`, `ux-krug-reviewer`, `coherence-three-way`, `stack-guardian`) | release |
+| `history[].reflected` · `history[].reflected_at` | `/build:reflect` | post-slice (tras archivar) |
 | `harness_phase` | `load-build-state.sh` (SessionStart) | — |

package/state/build-state.schema.json

@@ -86,7 +86,9 @@
         },
         "updated_at": { "type": "string", "format": "date-time" },
         "updated_by": { "type": "string", "description": "Agente o hook que escribió el estado." },
-        "notes": { "type": "string", "description": "Nota libre opcional (p.ej. changes/branches adicionales de una épica construida en varios pasos)." }
+        "notes": { "type": "string", "description": "Nota libre opcional (p.ej. changes/branches adicionales de una épica construida en varios pasos)." },
+        "reflected": { "type": "boolean", "description": "True si /build:reflect ya capturó los aprendizajes de este slice archivado (ciclo autocorrectivo). Mientras sea false/ausente, reflect-nudge.sh sugiere reflexionar al cerrar sesión." },
+        "reflected_at": { "type": "string", "format": "date-time", "description": "Cuándo se reflexionó (ISO-8601 UTC). Lo escribe /build:reflect." }
       }
     },
     "release": {

package/templates/CLAUDE.md.template

@@ -54,4 +54,10 @@ Estos puntos de extensión los leen los agentes `security-reviewer`, `stack-guar
 
 <!-- END trycore-build-harness -->
 
+<!-- BEGIN trycore-build-learnings -->
+## Convenciones aprendidas (mantenido por /build:reflect)
+
+<!-- /build:reflect propone aquí viñetas concretas (convención nueva o error recurrente) tras cerrar un slice; se agregan SOLO con tu aprobación. Revísalas en PR como cualquier cambio de equipo. -->
+<!-- END trycore-build-learnings -->
+
 <!-- A partir de aquí, el equipo del proyecto puede agregar instrucciones específicas del cliente. -->

package/docs/superpowers/specs/2026-06-02-scaffold-gate-design.md

@@ -1,87 +0,0 @@
-# Diseño: Scaffold como Paso 1 fundamental (scaffold gate)
-
-Fecha: 2026-06-02 · Target: `@trycore/spec-build-harness` v0.2.0 · Estado: aprobado (diseño)
-
-## Contexto y problema
-
-Hoy el arnés es **permisivo** respecto al scaffold del proyecto (el esqueleto runnable: `package.json` + framework que arranca vacío). Lo trata como un evento implícito: `harness_phase` pasa de `authoring` a `active` cuando `load-build-state.sh` detecta `package.json`, y los gates de código "no se cierran" en `authoring`, pero nada **exige ni bloquea** explícitamente. La decisión del usuario:
-
-> Es requerido que exista un scaffold. **No lo forcemos** (el arnés NO lo genera — sigue agnóstico al stack), **pero nuestro setup debe ser restrictivo para avanzar**. Es el **Paso 1 fundamental**. Y debe **preguntarse explícitamente** (no inferirse en silencio de `package.json`).
-
-Objetivo: convertir "scaffold presente" en una **precondición explícita y restrictiva** — confirmada por el equipo, registrada en el estado, y respaldada por un bloqueo determinista — sin que el arnés genere el scaffold.
-
-## Decisiones tomadas (brainstorming)
-
-1. **Condición = confirmación explícita**, no inferencia silenciosa de `package.json`.
-2. **Enforcement = skill/agente (Fase 0 de DoR) + gate en estado + hook determinista de respaldo.**
-3. **Regla del hook = Enfoque A (por estado/fase):** bloquea solo cuando un slice está en fase de código sin el scaffold confirmado; permite crear el scaffold (fases `dor`/`change` o sin slice).
-4. **No se genera el scaffold.** El arnés exige, bloquea e instruye; el equipo lo crea (guiado por `stack-allowlist.json`/PRD).
-
-## Diseño
-
-### 1. Estado (`state/build-state.json` + `build-state.schema.json`)
-Nuevo gate **a nivel proyecto** (no por-slice), explícito, default cerrado:
-
-```jsonc
-"scaffold": {
-  "confirmed": false,
-  "confirmed_by": null,      // agente/skill que confirmó
-  "confirmed_at": null,      // ISO 8601 UTC
-  "notes": ""                // ej. "Next.js app arranca vacía; npm run dev ok"
-}
-```
-
-- Top-level, junto a `harness_phase`/`active_slice`/`history`/`releases`.
-- `harness_phase` (authoring/active) se mantiene como señal **informativa** auto-detectada; el **gate de avance** es `scaffold.confirmed`.
-- Solo pasa a `true` por **confirmación explícita** (nunca auto). Una transición = una escritura, con `confirmed_by`/`confirmed_at` (protocolo de `state/README.md`).
-- Schema: `scaffold` se añade a `properties` y a `required` del objeto raíz; `build-state.template.json` lo incluye con `confirmed:false`.
-
-### 2. Skill `building-a-slice` — Fase 0 (precondición de DoR)
-Antes de abrir cualquier slice:
-- Si `scaffold.confirmed` ya es `true` → continúa al DoR normal.
-- Si es `false` → **pregunta explícitamente** (AskUserQuestion): *"¿Existe un scaffold runnable del proyecto (arranca vacío: build/dev corre sin error)?"*
-  - **No** → **STOP**. Instruye crearlo según `stack-allowlist.json#source` (PRD) y el stack permitido; **no lo genera**. No abre el slice.
-  - **Sí** → registra `scaffold.confirmed=true` (con `confirmed_by`, `confirmed_at`, `notes`) y continúa.
-- Documenta la relación con el walking skeleton (ver §5).
-
-### 3. Agente `dor-dod-gatekeeper`
-Añade **"scaffold confirmado"** como criterio **duro** de DoR (primer ítem). No deja pasar a fases de código sin `scaffold.confirmed=true`. Es el dueño de escribir el gate cuando valida el DoR.
-
-### 4. Hook determinista `hooks/build/scaffold-guard.sh` (PreToolUse · Write|Edit) — Enfoque A
-Backstop ineludible si el agente se salta la Fase 0:
-- Resuelve `ROOT` por `git rev-parse --show-toplevel` (+ fallback `${CLAUDE_PROJECT_DIR}`); lee `$ROOT/.claude/state/build-state.json`.
-- Guarda python3 fail-closed dirigida (igual patrón que `stack-guard.sh`).
-- **Regla de bloqueo:** si `active_slice` existe y `active_slice.phase ∈ {red, green, refactor, smoke, api, data}` **y** `scaffold.confirmed != true` → **exit 2** con mensaje: *"⛔ scaffold-guard: confirma el scaffold (Paso 1) antes de escribir código de slice. Ver building-a-slice / DoR."* En cualquier otro caso (sin slice, o fase `dor`/`change`) → exit 0 (permite crear el scaffold y planificar).
-- Auto-arme: si no existe `build-state.json` → exit 0.
-
-### 5. Metodología (`METODOLOGIA.md`) — clarificación walking skeleton
-- **Paso 1 — Scaffold (precondición, NO generada por el arnés):** esqueleto runnable mínimo del proyecto (build/dev arranca vacío). El equipo lo crea, guiado por el stack del PRD/allowlist; el arnés lo **exige, lo pregunta explícitamente y lo bloquea** hasta confirmarlo.
-- **Primer slice — Walking skeleton:** sobre el scaffold confirmado, construye el journey end-to-end más delgado. El scaffold (shell vacío) precede al walking skeleton (primer journey real delgado).
-
-### 6. Wiring de canales y CLI
-- `src/lib/settings-merge.ts`: añade `scaffold-guard.sh` al `HOOK_SPECS` (PreToolUse · `Write|Edit|MultiEdit`), misma cadena única.
-- `hooks/build-harness.json`: añade la misma entrada (canal plugin).
-- `src/commands/doctor.ts` y `status.ts`: reportan `scaffold: ✓ confirmado / ✗ pendiente` leyendo el estado.
-- `state/README.md`: documenta el gate `scaffold` y su protocolo de confirmación.
-
-### 7. Versión
-`0.1.0 → 0.2.0` (feature). Sincronizar `VERSION` / `package.json` / `.claude-plugin/plugin.json`. Incluye el fix pendiente de `state/README.md` ("scaffold Next.js" → "scaffold de código del proyecto"). Entrada en `CHANGELOG.md`. Nota de cadencia/uso en `GOVERNANCE.md` si aplica.
-
-## Casos borde
-- **Scaffold ya existe al instalar** (proyecto brownfield): la Fase 0 pregunta igual; el usuario confirma `Sí` una vez y queda registrado. No se re-pregunta mientras `scaffold.confirmed=true`.
-- **El equipo crea el scaffold dentro de un slice ya abierto**: desaconsejado por diseño (scaffold es Paso 1, antes del primer slice); el hook bloquea fases de código hasta confirmar. La creación del scaffold debe ocurrir con `active_slice=null` o en `dor`/`change`.
-- **Regresión de scaffold** (alguien borra package.json): `harness_phase` volvería a `authoring` (informativo); `scaffold.confirmed` sigue `true` salvo que se resetee manualmente. Aceptable para v0.2.0; documentar que el gate es una confirmación, no un chequeo continuo.
-- **python3 ausente**: el hook bloquea dirigido (no puede leer el estado de forma fiable) con mensaje claro, consistente con los otros hooks.
-
-## Verificación (end-to-end)
-1. `tsc` build limpio; `check-version-sync` (0.2.0 en los 3) / `check-agnostic` / `check-state-clean` en verde.
-2. `build-state.template.json` incluye `scaffold.confirmed=false`; el schema valida.
-3. Instalación en repo temporal: `scaffold-guard.sh` instalado y ejecutable; `settings.json` y `build-harness.json` contienen su entrada con la cadena única (sin doble disparo).
-4. Test del hook por estado: con un `build-state.json` que tenga `active_slice.phase="green"` y `scaffold.confirmed=false`, un `Write` simulado → exit 2; con `scaffold.confirmed=true` → exit 0; con `active_slice=null` → exit 0.
-5. `doctor`/`status` reportan el estado del scaffold.
-6. Lectura de `building-a-slice`/`dor-dod-gatekeeper`: el ask de Fase 0 y el criterio duro están presentes y son agnósticos (pasa `check-agnostic`).
-
-## Fuera de alcance
-- Generar el scaffold (decisión explícita: no lo forzamos).
-- Chequeo continuo de salud del scaffold (es una confirmación puntual, no un monitor).
-- Cambiar el modelo `harness_phase` (se mantiene como señal informativa).