@trycore/spec-build-harness 0.2.0 → 0.5.0

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

@@ -18,9 +18,9 @@ function cmd(script) {
 const HOOK_SPECS = [
     { event: 'SessionStart', matcher: 'startup|clear|compact', scripts: ['load-build-state.sh'] },
     { event: 'PreToolUse', matcher: 'Bash', scripts: ['gitflow-guard.sh'] },
-    { event: 'PreToolUse', matcher: 'Write|Edit|MultiEdit', scripts: ['stack-guard.sh', 'scaffold-guard.sh'] },
+    { event: 'PreToolUse', matcher: 'Write|Edit|MultiEdit', scripts: ['stack-guard.sh', 'scaffold-guard.sh', 'design-source-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/dist/lib/state-seed.js

@@ -11,6 +11,7 @@ const EMPTY_STATE = {
     version: '1.0',
     harness_phase: 'authoring',
     scaffold: { confirmed: false, confirmed_by: null, confirmed_at: null, notes: '' },
+    design_source: { applies: false, confirmed: false, confirmed_by: null, confirmed_at: null, source: '', notes: '' },
     active_slice: null,
     history: [],
     releases: [],

package/docs/agents.md

@@ -1,6 +1,6 @@
 # Agentes de construcción (`agents/build/`)
 
-Los **10 agentes** de `@trycore/spec-build-harness` ejecutan los *gates* del arnés de
+Los **11 agentes** de `@trycore/spec-build-harness` ejecutan los *gates* del arnés de
 construcción de dos loops. Ninguno edita código de producto: son read-only sobre el
 repositorio (algunos ejecutan tests o levantan la app), diagnostican y **devuelven el
 veredicto al `build-orchestrator`**, que es quien propone la escritura del estado
@@ -27,6 +27,7 @@ veredicto al `build-orchestrator`**, que es quien propone la escritura del estad
 | 8 | `api-contract-tester` | sonnet | Contrato / datos | Gate `api` — pruebas de contrato (Newman/Postman) |
 | 9 | `data-consistency-checker` | sonnet | Contrato / datos | Gate `data` — invariantes y consistencia de datos |
 | 10 | `change-epic-coherence` | sonnet | Trazabilidad | Gate `coherence_link` — enlace change↔épica↔HU |
+| 11 | `ux-fidelity-reviewer` | sonnet | Inner loop · smoke | Gate `fidelity` — fidelidad visual a la fuente de diseño declarada |
 
 ---
 

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

@@ -73,12 +73,12 @@ trycore-build init
 
 `init` es **idempotente** (re-correrlo es seguro) y siembra:
 
-- **10 agentes** en `.claude/agents/build/` (build-orchestrator, dor-dod-gatekeeper,
+- **11 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/`.
+  api-contract-tester, data-consistency-checker, change-epic-coherence, ux-fidelity-reviewer).
+- **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`.
+- **9 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 **9 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,26 @@
 # 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 **9 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, el scaffold y la fuente de diseño (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 9 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)** |
+| `design-source-guard.sh` | `PreToolUse` | `Write\|Edit\|MultiEdit` | Bloquea escribir código de un slice **con UI** (`gates.fidelity===false`, fases `red…data`) si la fuente de diseño del proyecto no está confirmada (`design_source.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`.
+> Cuatro bloqueantes (`gitflow-guard`, `stack-guard`, `scaffold-guard`, `design-source-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 +61,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 +77,18 @@ 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.
+
+### 9. `design-source-guard.sh` — `PreToolUse` · Write/Edit/MultiEdit · **bloqueante** (desde v0.5.0)
+
+Refuerza el **seguro de fuente de diseño** (espejo de `scaffold-guard`, para slices con UI). Bloquea con `exit 2` la escritura de **código de un slice con UI** —cuando `active_slice.phase` ∈ `red`/`green`/`refactor`/`smoke`/`api`/`data` **y** `active_slice.gates.fidelity === false` (marcado UI-pendiente por la DoR)— mientras el proyecto tenga UI (`design_source.applies === true`) y `design_source.confirmed` no sea `true`. **Permite** todo lo demás: slices sin UI (`gates.fidelity === null` o ausente), proyectos sin UI (`applies !== true`), fases de planificación (`dor`/`change`), o fuente ya confirmada. El arnés **exige** la fuente de diseño pero **no genera** el prototipo; la confirmación es **explícita** (vía `building-a-slice` Fase 0-bis / `dor-dod-gatekeeper`), nunca auto-detectada. Guarda `python3` fail-closed dirigido. En la práctica, como `design_source` es gate de proyecto, solo muerde la **primera** construcción de UI sin fuente declarada.
+
 ---
 
 ## La cadena de comando única (sin doble disparo entre canales)
@@ -93,8 +112,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`, `design-source-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/fuente de diseño confirmados); 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 +130,10 @@ 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). |
+| `design-source-guard.sh` | Permite (sin slice UI en fases de código, o sin `design_source.applies=true`, no hay nada que bloquear). |
 | `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 +147,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 9 invocaciones: `PreToolUse·Write` agrupa `stack-guard` + `scaffold-guard` + `design-source-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/design-source-guard.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# design-source-guard.sh — PreToolUse · Write/Edit/MultiEdit
+# Backstop determinista del "seguro de fuente de diseño": no se escribe código de un slice
+# CON UI sin que la fuente de diseño del proyecto esté confirmada. Espejo de scaffold-guard.sh.
+# Bloquea (exit 2) SOLO si: hay active_slice en fase de código (red/green/refactor/smoke/api/data),
+# el proyecto tiene UI (design_source.applies===true), el slice está marcado UI-pendiente
+# (gates.fidelity===false) y design_source.confirmed!==true.
+# AUTO-ARME: si no existe build-state.json, 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)"  # consumir stdin (protocolo de hook); la decisión es por estado.
+
+# Guarda python3 [H4]: si falta, no podemos leer el estado de forma fiable. Fail-closed.
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "⛔ design-source-guard: python3 no disponible; no puedo verificar el gate de fuente de diseño. 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: permitir declarar / 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
+ds = d.get("design_source") or {}
+if ds.get("applies") is not True:
+    sys.exit(0)  # proyecto sin UI (o indeterminado): mecanismo apagado
+if (slice_.get("gates") or {}).get("fidelity") is not False:
+    sys.exit(0)  # solo UI-pendiente (false) cuenta; null/ausente -> no bloquear
+if ds.get("confirmed") is True:
+    sys.exit(0)  # fuente de diseño confirmada: permitido
+print("BLOCK")
+PY
+)"
+
+if [ "$VERDICT" = "BLOCK" ]; then
+  echo "⛔ design-source-guard: el slice con UI está en fase de código pero la fuente de diseño NO está confirmada." >&2
+  echo "   Declara y confirma primero el DESIGN_SOURCE del proyecto (ver building-a-slice Fase 0-bis / DoR)." >&2
+  echo "   El arnés NO genera el prototipo: declara la fuente (prototipo/export) y confírmala." >&2
+  exit 2
+fi
+exit 0

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

@@ -31,6 +31,10 @@
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/scaffold-guard.sh\""
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/design-source-guard.sh\""
           }
         ]
       }
@@ -57,6 +61,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\""
           }
         ]
       }