@trycore/spec-build-harness 0.1.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.1.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 -->` |
 
@@ -65,6 +65,15 @@ por slice. Y el inner loop **no** dispara reviewers pesados. Cada gate vive en e
 
 ## 2. La regla del "esqueleto que camina"
 
+> **Paso 1 fundamental — el scaffold (precondición, NO generada por el arnés).** Antes del primer
+> slice debe **existir** un *scaffold* runnable: el esqueleto del proyecto que arranca vacío (el
+> script de build/dev corre sin error). El arnés lo **exige y bloquea** —gate de proyecto
+> `scaffold.confirmed`, que solo pasa a `true` por **confirmación explícita** (no por auto-detección
+> de `package.json`), respaldado por el hook determinista `scaffold-guard.sh`— pero **no lo genera**
+> (es agnóstico al stack: el equipo lo crea según el PRD/allowlist). El *esqueleto que camina* se
+> construye **encima** del scaffold: el scaffold es el shell vacío que arranca; el walking skeleton
+> es el primer journey real más delgado. Sin scaffold confirmado no se abre ningún slice.
+
 El arnés prohíbe construir capas horizontales aisladas que "se juntan al final" (el anti-patrón que
 hace que todos los gates por-slice estén en verde y el producto aun así no funcione de punta a
 punta). En su lugar:
@@ -81,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)
@@ -108,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`).
@@ -142,8 +163,9 @@ vía el hook `stack-guard.sh` en tiempo real, no vía subagente.
 
 - `ux` y `api` admiten `null` cuando el slice no tiene UI o endpoints. `null` ≠ abierto: **no
   bloquea** el DoD.
-- En `harness_phase: authoring` (sin `package.json`) se puede hacer `dor` + `change`, pero los gates
-  de código (`tdd`, `journey_smoke`, `api`, `data`) **no se cierran** hasta scaffoldear.
+- En `harness_phase: authoring` (sin `package.json`) se puede 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 (gate de proyecto `scaffold.confirmed`, ver §2).
 
 ---
 
@@ -341,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.1.0
+0.4.0

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

@@ -9,6 +9,13 @@ Eres el **gatekeeper DoR/DoD** del arnés de construcción. Eres read-only sobre
 proponer la escritura del estado (no editas código de producto).
 
 ## Definition of Ready (gate `dor`) — antes de construir
+
+**Precondición — Paso 1 fundamental (scaffold):** antes de validar nada más, exige
+`scaffold.confirmed=true` en `build-state.json`. Si es `false`, **NO valides el DoR**: instruye
+confirmar primero que existe un scaffold runnable del proyecto (ver `building-a-slice` Fase 0). El
+arnés **no genera** el scaffold; lo exige. (El hook `scaffold-guard.sh` respalda este bloqueo en
+las fases de código.)
+
 La unidad es la **épica**. Identifica `EP-XXX` en `docs/03-backlog/epicas.md` y el conjunto de HU
 que la componen (las que tienen `epica: EP-XXX` en `docs/04-historias/`). Pasa SOLO si **todas** se
 cumplen; lista cada una con ✓/✗:
@@ -16,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

@@ -59,6 +59,26 @@ export async function doctor(opts) {
     else {
         console.log('  — sin hooks instalados (corre `trycore-build init`)');
     }
+    // Gate de scaffold (Paso 1 fundamental)
+    console.log('');
+    if (fs.existsSync(t.stateFile)) {
+        try {
+            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');
+        }
+    }
+    else {
+        console.log('Scaffold (Paso 1): — (sin build-state.json; corre `trycore-build init`)');
+    }
     // Detección de doble canal (CLI settings.json + plugin) [H3]
     const settingsHasHooks = fs.existsSync(t.settingsFile) &&
         /hooks\/build\//.test(fs.readFileSync(t.settingsFile, 'utf8'));
@@ -68,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.`);
@@ -75,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

@@ -38,6 +38,7 @@ export async function status(opts) {
             console.log('');
             console.log('Estado del arnés:');
             console.log(`  Fase:       ${st.harness_phase ?? '?'}`);
+            console.log(`  Scaffold:   ${st.scaffold?.confirmed === true ? '✓ confirmado (Paso 1)' : '✗ pendiente (Paso 1)'}`);
             const slice = st.active_slice;
             if (slice) {
                 const openGates = Object.entries(slice.gates ?? {})
@@ -50,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'] },
+    { 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/dist/lib/state-seed.js

@@ -10,6 +10,7 @@ import { ensureDir } from './install-engine.js';
 const EMPTY_STATE = {
     version: '1.0',
     harness_phase: 'authoring',
+    scaffold: { confirmed: false, confirmed_by: null, confirmed_at: null, notes: '' },
     active_slice: null,
     history: [],
     releases: [],