@trycore/spec-build-harness 0.1.0 → 0.4.0

package/state/README.md

@@ -40,7 +40,25 @@ Luego se pregunta el **Release Gate** (outer loop, skill `releasing-a-version`)
 computado desde las líneas de release del Story Map.
 
 `harness_phase` arranca en `authoring` y lo cambia `load-build-state.sh` a `active` cuando
-detecta `package.json` en la raíz (aparición del scaffold Next.js).
+detecta `package.json` en la raíz (aparición del scaffold de código del proyecto). Es una señal
+**informativa**, no el gate de avance.
+
+### Gate `scaffold` (Paso 1 fundamental)
+
+`scaffold` es un gate **de proyecto** (no por-slice): `{ confirmed, confirmed_by, confirmed_at, notes }`.
+Arranca en `confirmed: false` y **solo** pasa a `true` por **confirmación explícita** (vía
+`building-a-slice` Fase 0 / `dor-dod-gatekeeper`), nunca por auto-detección. Es la precondición
+restrictiva para abrir cualquier slice: el hook `scaffold-guard.sh` bloquea escribir código de
+slice (fases `red…data`) mientras `confirmed` no sea `true`. El arnés **no genera** el scaffold.
+
+### Reflexión post-slice (ciclo autocorrectivo)
+
+Tras archivar un slice, su entrada en `history[]` puede llevar `reflected` / `reflected_at`. El
+hook `reflect-nudge.sh` (evento `Stop`, **no bloqueante**) sugiere ejecutar `/build:reflect` mientras
+exista al menos una entrada con `reflected != true`. `/build:reflect` lo ejecuta el **modelo**:
+detecta convención nueva o error recurrente, **propone** un parche al bloque `trycore-build-learnings`
+de `CLAUDE.md` (se aplica **solo tras tu aprobación**) y estampa `reflected: true` → el nudge calla.
+El razonamiento vive en el modelo; el hook solo es un recordatorio determinista.
 
 ## Quién escribe qué
 
@@ -53,4 +71,5 @@ detecta `package.json` en la raíz (aparición del scaffold Next.js).
 | `gates.api` | `api-contract-tester` | slice |
 | `gates.data` | `data-consistency-checker` | slice |
 | `releases[]` (`security`, `smell`, `ux`, `coherence`, `stack_arch`, `integration`, `status`) | `releasing-a-version` (delega en `security-reviewer`, `simple-design-reviewer`, `ux-krug-reviewer`, `coherence-three-way`, `stack-guardian`) | release |
+| `history[].reflected` · `history[].reflected_at` | `/build:reflect` | post-slice (tras archivar) |
 | `harness_phase` | `load-build-state.sh` (SessionStart) | — |

package/state/build-state.schema.json

@@ -5,14 +5,15 @@
   "description": "Single source of truth para el handoff secuencial entre agentes de construcción. Lo escriben build-orchestrator y los gates; lo lee load-build-state.sh.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["version", "harness_phase", "active_slice", "history", "releases"],
+  "required": ["version", "harness_phase", "scaffold", "active_slice", "history", "releases"],
   "properties": {
     "version": { "type": "string", "const": "1.0" },
     "harness_phase": {
       "type": "string",
       "enum": ["authoring", "active"],
-      "description": "authoring = aún no hay package.json; active = scaffold de código presente."
+      "description": "Señal INFORMATIVA auto-detectada: authoring = aún no hay package.json; active = scaffold de código presente. El gate de avance es `scaffold.confirmed`, NO esta señal."
     },
+    "scaffold": { "$ref": "#/$defs/scaffold" },
     "active_slice": {
       "description": "El slice (épica) en construcción. null si no hay ninguno activo.",
       "oneOf": [
@@ -32,6 +33,18 @@
     }
   },
   "$defs": {
+    "scaffold": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Gate de PROYECTO (Paso 1 fundamental): el scaffold runnable existe. Precondición EXPLÍCITA y restrictiva — solo pasa a confirmed=true por confirmación humana (vía building-a-slice Fase 0 / dor-dod-gatekeeper), nunca por auto-detección. El arnés NO genera el scaffold.",
+      "required": ["confirmed"],
+      "properties": {
+        "confirmed": { "type": "boolean", "description": "true solo tras confirmación explícita de que el esqueleto runnable existe." },
+        "confirmed_by": { "type": ["string", "null"], "description": "Agente/skill que registró la confirmación." },
+        "confirmed_at": { "type": ["string", "null"], "format": "date-time" },
+        "notes": { "type": "string", "description": "Evidencia libre (p.ej. 'build/dev arranca vacío sin error')." }
+      }
+    },
     "slice": {
       "type": "object",
       "additionalProperties": false,
@@ -73,7 +86,9 @@
         },
         "updated_at": { "type": "string", "format": "date-time" },
         "updated_by": { "type": "string", "description": "Agente o hook que escribió el estado." },
-        "notes": { "type": "string", "description": "Nota libre opcional (p.ej. changes/branches adicionales de una épica construida en varios pasos)." }
+        "notes": { "type": "string", "description": "Nota libre opcional (p.ej. changes/branches adicionales de una épica construida en varios pasos)." },
+        "reflected": { "type": "boolean", "description": "True si /build:reflect ya capturó los aprendizajes de este slice archivado (ciclo autocorrectivo). Mientras sea false/ausente, reflect-nudge.sh sugiere reflexionar al cerrar sesión." },
+        "reflected_at": { "type": "string", "format": "date-time", "description": "Cuándo se reflexionó (ISO-8601 UTC). Lo escribe /build:reflect." }
       }
     },
     "release": {

package/state/build-state.template.json

@@ -1,6 +1,12 @@
 {
   "version": "1.0",
   "harness_phase": "authoring",
+  "scaffold": {
+    "confirmed": false,
+    "confirmed_by": null,
+    "confirmed_at": null,
+    "notes": ""
+  },
   "active_slice": null,
   "history": [],
   "releases": []

package/templates/CLAUDE.md.template

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

package/templates/settings-hooks.template.json

@@ -13,7 +13,7 @@
     ],
     "PreToolUse": [
       { "matcher": "Bash", "hooks": [ { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/gitflow-guard.sh\"" } ] },
-      { "matcher": "Write|Edit|MultiEdit", "hooks": [ { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/stack-guard.sh\"" } ] }
+      { "matcher": "Write|Edit|MultiEdit", "hooks": [ { "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\"" } ] }
     ],
     "PostToolUse": [
       { "matcher": "Write|Edit|MultiEdit", "hooks": [ { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/lint-typecheck.sh\"" }, { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/coherence-flag.sh\"" } ] }