@trycore/spec-build-harness 0.1.0 → 0.2.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.2.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/METODOLOGIA.md

@@ -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:
@@ -142,8 +151,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).
 
 ---
 

package/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.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 ✓/✗:

package/dist/commands/doctor.js

@@ -59,6 +59,21 @@ 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'}`);
+        }
+        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'));

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 ?? {})

package/dist/lib/settings-merge.js

@@ -18,7 +18,7 @@ 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'] },
 ];

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: [],

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

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

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\""
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trycore/spec-build-harness",
-  "version": "0.1.0",
+  "version": "0.2.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": {

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

@@ -33,6 +33,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 +83,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/state/README.md

@@ -40,7 +40,16 @@ 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.
 
 ## Quién escribe qué
 

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,

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/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\"" } ] }