@trycore/spec-build-harness 0.1.0 → 0.4.0

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/scaffold-guard.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# scaffold-guard.sh — PreToolUse · Write/Edit/MultiEdit
+# Backstop determinista del "Paso 1 fundamental": no se escribe código de slice sin
+# scaffold confirmado. Enfoque A (por estado/fase): bloquea (exit 2) SOLO si hay un
+# active_slice en fase de código (red/green/refactor/smoke/api/data) y scaffold.confirmed
+# no es true. Permite crear el scaffold y planificar (sin slice, o fases dor/change).
+# AUTO-ARME: si no existe build-state.json, no hay nada que vigilar -> exit 0.
+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
+
+INPUT="$(cat)"
+
+# Guarda python3 [H4]: si falta, no podemos leer el estado de forma fiable. Fail-closed
+# DIRIGIDO: solo bloqueamos si la edición NO es del propio scaffold/planificación obvia.
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "⛔ scaffold-guard: python3 no disponible; no puedo verificar el gate de scaffold. Instala python3 (trycore-build doctor)." >&2
+  exit 2
+fi
+
+VERDICT="$(STATE="$STATE" python3 <<'PY' 2>/dev/null
+import os, sys, json
+try:
+    d = json.load(open(os.environ["STATE"]))
+except Exception:
+    sys.exit(0)  # estado ilegible -> no bloquear (auto-arme)
+slice_ = d.get("active_slice")
+if not slice_:
+    sys.exit(0)  # sin slice: se permite crear el scaffold / planificar
+code_phases = {"red", "green", "refactor", "smoke", "api", "data"}
+if slice_.get("phase") not in code_phases:
+    sys.exit(0)  # fases dor/change/pr/archived: permitido
+if (d.get("scaffold") or {}).get("confirmed") is True:
+    sys.exit(0)  # scaffold confirmado: permitido
+print("BLOCK")
+PY
+)"
+
+if [ "$VERDICT" = "BLOCK" ]; then
+  echo "⛔ scaffold-guard (Paso 1 fundamental): el slice está en fase de código pero el scaffold NO está confirmado." >&2
+  echo "   Confirma primero que existe un scaffold runnable del proyecto (ver building-a-slice Fase 0 / DoR)." >&2
+  echo "   El arnés NO genera el scaffold: créalo según tu stack (stack-allowlist.json) y confírmalo." >&2
+  exit 2
+fi
+exit 0

package/hooks/build-harness.json

@@ -27,6 +27,10 @@
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/stack-guard.sh\""
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/scaffold-guard.sh\""
           }
         ]
       }
@@ -53,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.1.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.
@@ -33,6 +39,23 @@ inner loop: **≤ ~20 min por épica** y producto que **camina end-to-end en tod
 > 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".
 
+## Fase 0 · Scaffold (Paso 1 fundamental — precondición restrictiva)
+
+Antes de abrir **cualquier** slice, el scaffold runnable del proyecto debe **existir y estar
+confirmado explícitamente**. El arnés **NO genera** el scaffold (es agnóstico al stack), pero
+**bloquea el avance** hasta confirmarlo. Es la precondición del primer slice; el *esqueleto que
+camina* se construye **encima** del scaffold ya existente.
+
+1. Lee `build-state.json`. Si `scaffold.confirmed` ya es `true` → continúa a la Fase 1 (dor).
+2. Si es `false` → **pregunta explícitamente** (AskUserQuestion): *"¿Existe un scaffold runnable del
+   proyecto (arranca vacío: el script de build/dev corre sin error)?"*
+   - **No** → **STOP**. Indica crearlo según el stack permitido (`.claude/config/stack-allowlist.json`
+     / el PRD técnico). **No lo generes tú.** No abras el slice.
+   - **Sí** → registra en el estado `scaffold.confirmed=true` (con `confirmed_by`, `confirmed_at`,
+     `notes` — p.ej. "build/dev arranca vacío sin error") y continúa.
+3. El gate lo valida también el `dor-dod-gatekeeper` (criterio duro de DoR) y lo respalda el hook
+   determinista `scaffold-guard.sh` (bloquea escribir código de slice sin scaffold confirmado).
+
 ## Pipeline — inner loop (carga la referencia indicada en cada paso)
 
 | Fase | Acción | Delega en | Gate | Referencia |
@@ -66,16 +89,21 @@ 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
+1. **Fase 0 — scaffold**: verifica `scaffold.confirmed` (ver arriba). Si no está confirmado, resuélvelo
+   primero (pregunta explícita; STOP si no existe). Sin scaffold confirmado no se abre slice.
+2. 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`,
+3. 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
+4. 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.
+- **Paso 1 fundamental**: sin `scaffold.confirmed=true` no se abre slice ni se escribe código de
+  slice (lo respalda `scaffold-guard.sh`). El arnés exige el scaffold pero **no lo genera**.
+- En `harness_phase` = `authoring` (sin `package.json`) puedes hacer la Fase 0 (crear/confirmar el
+  scaffold) + dor + change, pero los gates de código (tdd, journey_smoke, api, data) NO se cierran
+  hasta tener el scaffold confirmado.
 - 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).

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.