@trycore/spec-build-harness 0.10.0 → 0.11.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.10.0",
+  "version": "0.11.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/VERSION

@@ -1 +1 @@
-0.10.0
+0.11.0

package/commands/build/escalate.md

@@ -1,6 +1,6 @@
 ---
 name: "BUILD: Escalate"
-description: Registra un bloqueo del slice en el runtime (evento escalation_raised) y devuelve la decisión al humano — recortar, diferir o desbloquear nunca lo decide el modelo. Adaptador delgado sobre slice-ops.sh escalate.
+description: Registra un bloqueo del slice en el runtime (evento slice_escalated) y devuelve la decisión al humano — recortar, diferir o desbloquear nunca lo decide el modelo. Adaptador delgado sobre slice-ops.sh escalate.
 category: Workflow
 tags: [build-harness, runtime, escalada, gobierno, trycore]
 ---

package/commands/build/onboard.md

@@ -253,18 +253,34 @@ el token de agente. El arnés **prepara y valida**; una persona sube.
     "release_lines": [{"id": "R1-mvp", "epics": ["EP-001"]}]}
    ```
 
-2. Normalízalo y valídalo (determinista, nunca sube nada):
+2. Normalízalo y valídalo (determinista, nunca sube nada). La salida va a
+   `.claude/state/graph-bundle.json` para que `trycore-build migrate` la encuentre sola:
 
    ```bash
-   python3 .claude/scripts/lib/graph-bundle.py < /tmp/epics.json > /tmp/graph-bundle.json
+   python3 .claude/scripts/lib/graph-bundle.py < /tmp/epics.json > .claude/state/graph-bundle.json
    ```
 
+   El script emite las épicas en el **formato exacto del hub**: `layer` en MAYÚSCULA
+   (`FOUNDATIONAL`|`BUSINESS` — un layer inválido rechaza el grafo ENTERO), historias con
+   `code`, y `release_line` (string) por épica.
+
 3. **Lee los avisos** (`warnings` del bundle y stderr): capa ausente, dependencia inexistente,
    ciclo, línea de release que referencia una épica desconocida. Corrígelos en discovery — el arnés
    **no inventa** el grafo ni edita `epicas.md` (salvo el carve-out de la épica caparazón, Fase 2c).
 
-4. **Entrega el fichero a un ADMIN** con esta instrucción literal: *«súbelo en la consola del hub,
-   pantalla de import del proyecto»*. El import es idempotente y **reanuda** si falló a medias.
+4. **Entrega al ADMIN un solo fichero.** Si vas a migrar historial, corre `trycore-build migrate`:
+   embebe el grafo como sección `graph` del bundle de estado (un único fichero para la pantalla de
+   import del proyecto). Sin historial que migrar, entrega `graph-bundle.json` con esta instrucción
+   literal: *«súbelo en la consola del hub, pantalla de import del proyecto»*. El import es
+   idempotente y **reanuda** si falló a medias.
+
+   Si el proyecto tiene épicas construidas **antes** de instalar el arnés (sin slice en el
+   historial del estado local), decláralas en un fichero que **el humano confirme** y pásalo con
+   `--pre-harness <fichero>` (`{"epics": [{"code": "EP-001", "note": "…opcional…"}]}`): se
+   importan archivadas **sin declarar gates**, con un acta de migración honesta — sin esto
+   quedan «sin empezar» en el hub y `claim_next` las reparte como trabajo nuevo. `migrate`
+   avisa de las épicas del grafo sin slice ni declaración pre-arnés, pero **nunca** las
+   añade por su cuenta.
 
 5. Modo `legacy` o sin credenciales: salta esta fase; el grafo sigue viviendo en los documentos.
 

package/dist/cli.js

@@ -112,9 +112,19 @@ program
     .argument('[directory]', 'Directorio del proyecto', '.')
     .option('--out <path>', 'Ruta de salida del bundle (default: .claude/state/migration-bundle.json)')
     .option('--project-ref <ref>', 'Identificador de proyecto en el hub (default: nombre del directorio)')
+    .option('--graph <path>', 'Bundle de grafo (graph-bundle.py) a embeber como sección graph (default: .claude/state/graph-bundle.json si existe)')
+    .option('--pre-harness <path>', 'Fichero JSON con las épicas construidas ANTES de instalar el arnés, confirmadas por el humano: {"epics": [{"code": "EP-001", "note": "…"}]} — se importan archivadas sin declarar gates, con acta de migración')
+    .option('--verify', 'Solo verifica el bundle normalizado contra los invariantes del hub (offline, no escribe nada); exit ≠0 si hay violaciones')
     .action(async (directory, opts) => {
     try {
-        await migrate({ targetDir: directory, outFile: opts.out, projectRef: opts.projectRef });
+        await migrate({
+            targetDir: directory,
+            outFile: opts.out,
+            projectRef: opts.projectRef,
+            graphFile: opts.graph,
+            preHarnessFile: opts.preHarness,
+            verifyOnly: Boolean(opts.verify),
+        });
     }
     catch (err) {
         console.error('✗ Error:', err.message);

package/dist/commands/migrate.js

@@ -4,7 +4,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { targetPaths } from '../lib/paths.js';
-import { buildStateBundle } from '../lib/state-bundle.js';
+import { buildStateBundle, extractGraphSection, graphEpicsWithoutRepresentation, verifyStateBundle, } from '../lib/state-bundle.js';
+import { parsePreHarnessList } from '../lib/normalize.js';
 export async function migrate(opts) {
     const targetDir = path.resolve(opts.targetDir);
     const t = targetPaths(targetDir);
@@ -20,14 +21,107 @@ export async function migrate(opts) {
         console.error(`✗ build-state.json no parsea como JSON: ${err.message}`);
         process.exit(1);
     }
+    // Épicas pre-arnés (issue #42): construidas ANTES de instalar el arnés, sin
+    // entrada en history[] — importadas sin esto quedan «sin empezar» en el hub
+    // y claim_next las reparte como trabajo nuevo (incidente del primer piloto).
+    // La lista la escribe/confirma el humano; nunca se infiere del grafo.
+    let preHarness;
+    if (opts.preHarnessFile) {
+        const preHarnessFile = path.resolve(opts.preHarnessFile);
+        if (!fs.existsSync(preHarnessFile)) {
+            console.error(`✗ No existe el fichero pre-arnés: ${preHarnessFile}`);
+            process.exit(1);
+        }
+        let preHarnessRaw;
+        try {
+            preHarnessRaw = JSON.parse(fs.readFileSync(preHarnessFile, 'utf8'));
+        }
+        catch (err) {
+            console.error(`✗ El fichero pre-arnés no parsea como JSON: ${err.message}`);
+            process.exit(1);
+        }
+        const { list, errors } = parsePreHarnessList(preHarnessRaw);
+        if (list === null || errors.length > 0) {
+            console.error(`✗ El fichero pre-arnés (${preHarnessFile}) no es válido:`);
+            for (const e of errors)
+                console.error(`    ✗ ${e}`);
+            console.error('  Forma esperada: {"epics": [{"code": "EP-001", "note": "…opcional…"}], "as_of": "…ISO opcional…"}');
+            process.exit(1);
+        }
+        preHarness = list;
+    }
     const projectRef = opts.projectRef ?? path.basename(targetDir);
-    const bundle = buildStateBundle(raw, projectRef);
+    const bundle = buildStateBundle(raw, projectRef, preHarness);
+    // Sección `graph` embebida (issue #41): el import del hub la consume DENTRO del
+    // bundle de estado (ImportBundleIn.graph) — un fichero de grafo aparte se ignora
+    // y la historia falla («la épica no existe en el grafo»). El grafo se genera con
+    // scripts/lib/graph-bundle.py (flujo de /build:onboard); aquí solo se embebe.
+    const defaultGraphFile = path.join(t.stateDir, 'graph-bundle.json');
+    const graphFile = opts.graphFile
+        ? path.resolve(opts.graphFile)
+        : fs.existsSync(defaultGraphFile)
+            ? defaultGraphFile
+            : undefined;
+    if (graphFile) {
+        if (!fs.existsSync(graphFile)) {
+            console.error(`✗ No existe el bundle de grafo: ${graphFile}`);
+            process.exit(1);
+        }
+        let graphRaw;
+        try {
+            graphRaw = JSON.parse(fs.readFileSync(graphFile, 'utf8'));
+        }
+        catch (err) {
+            console.error(`✗ El bundle de grafo no parsea como JSON: ${err.message}`);
+            process.exit(1);
+        }
+        const { graph, errors } = extractGraphSection(graphRaw);
+        if (graph === null) {
+            console.error(`✗ El bundle de grafo (${graphFile}) no está en el formato del hub — no se escribe el fichero.`);
+            for (const e of errors)
+                console.error(`    ✗ ${e}`);
+            console.error('  Regenéralo con scripts/lib/graph-bundle.py (layer FOUNDATIONAL|BUSINESS, historias con `code`, `release_line` por épica).');
+            process.exit(1);
+        }
+        bundle.graph = graph;
+        // Síntoma exacto del incidente del piloto: épicas del grafo sin slice en
+        // history[] ni declaración pre-arnés quedan «sin empezar» en el hub y
+        // claim_next las reparte como trabajo nuevo. SOLO aviso — la lista
+        // pre-arnés la confirma el humano, nada se auto-añade.
+        const unrepresented = graphEpicsWithoutRepresentation(graph, bundle.history.map((h) => h.epic_code));
+        if (unrepresented.length > 0) {
+            bundle.warnings.push(`graph: ${unrepresented.length} épica(s) del grafo sin slice en el historial ni declaración pre-arnés (${unrepresented.join(', ')}) — quedarán «sin empezar» en el hub y claim_next las repartirá como trabajo nuevo; si ya están construidas, decláralas en el fichero de --pre-harness (nunca se auto-añaden)`);
+        }
+    }
     if (bundle.validation_errors.length > 0) {
         console.error('✗ El bundle normalizado no pasa la validación local — no se escribe el fichero.');
         for (const e of bundle.validation_errors)
             console.error(`    ✗ ${e}`);
         process.exit(1);
     }
+    // Verificación offline contra los invariantes del hub (issue #40): la misma
+    // entrada que el import rechazaría debe salir aquí, no en la consola del ADMIN.
+    const violations = verifyStateBundle(bundle);
+    if (opts.verifyOnly) {
+        if (violations.length === 0) {
+            console.log('✓ Verificación offline: el bundle normalizado no viola ningún invariante conocido del hub.');
+            console.log('  (No se escribió ningún fichero: --verify solo verifica.)');
+            return;
+        }
+        console.error(`✗ Verificación offline: ${violations.length} violación(es) de los invariantes del hub:`);
+        for (const v of violations)
+            console.error(`    ✗ ${v.source_key}: ${v.message}`);
+        process.exit(1);
+    }
+    if (violations.length > 0) {
+        // El destino del bundle es un ADMIN: un bundle que el hub rechazaría no se
+        // entrega en silencio — se aborta sin escribir, igual que la validación local.
+        console.error(`✗ El bundle viola ${violations.length} invariante(s) del hub — no se escribe el fichero.`);
+        for (const v of violations)
+            console.error(`    ✗ ${v.source_key}: ${v.message}`);
+        console.error('  Corrige el build-state.json de origen (o reporta el caso al arnés) y reintenta.');
+        process.exit(1);
+    }
     bundle.generated_at = new Date().toISOString();
     const outFile = opts.outFile ? path.resolve(opts.outFile) : path.join(t.stateDir, 'migration-bundle.json');
     fs.mkdirSync(path.dirname(outFile), { recursive: true });
@@ -35,6 +129,17 @@ export async function migrate(opts) {
     console.log(`✓ Bundle de estado preparado: ${outFile}`);
     console.log(`  ${bundle.history.length} slice(s) de historial · ${bundle.releases.length} release(s) · ` +
         `${bundle.fronts.length} front(s) · ${bundle.facts.length} hecho(s) de proyecto · ${bundle.unmapped.length} entrada(s) no mapeable(s)`);
+    if (preHarness) {
+        console.log(`  Épicas pre-arnés declaradas: ${preHarness.epics.length} (${preHarness.epics.map((e) => e.code).join(', ')}) — archivadas sin declarar gates, con acta de migración`);
+    }
+    if (bundle.graph) {
+        console.log(`  Grafo embebido: ${bundle.graph.epics.length} épica(s) (sección graph del bundle — un solo fichero para el ADMIN)`);
+    }
+    else {
+        console.log('  ⚠ Grafo: NO incluido — el hub reportará «Grafo: no incluida» y rechazará la historia si el');
+        console.log('    grafo no fue importado antes. Genera el grafo con scripts/lib/graph-bundle.py y pásalo');
+        console.log('    con --graph <fichero> (o déjalo en .claude/state/graph-bundle.json).');
+    }
     if (bundle.warnings.length > 0) {
         console.log('');
         console.log('  Avisos (no bloquean; corrígelos en discovery si aplica):');