@trycore/spec-build-harness 0.1.0

package/docs/getting-started.md

@@ -0,0 +1,260 @@
+# Getting Started — Tu primer ciclo end-to-end en ~15 min
+
+Esta guía te lleva, de forma secuencial y práctica, desde cero hasta cerrar tu primer **slice**
+(una épica `EP-XXX`) con el arnés de construcción de Trycore (`@trycore/spec-build-harness`).
+
+El arnés es el **compañero de construcción** de `@trycore/spec-product-flow`: la vertical de
+discovery produce los artefactos (`PRD → User Story Map → Backlog → Historias → Priorización →
+Flows`); este arnés los lleva al **código** mediante un pipeline de **dos loops**.
+
+| Loop | Skill | Frecuencia | Qué hace |
+|---|---|---|---|
+| **Inner** (rápido) | `building-a-slice` | por épica `EP-XXX` | DoR → OpenSpec change → TDD → journey-smoke → api/data → DoD reducido → PR + archive |
+| **Outer** (pesado) | `releasing-a-version` | por release (línea del Story Map) | gates de seguridad, diseño, UX, coherencia triple, arquitectura e integración con deps reales — **una sola vez** |
+
+Ambas verticales coexisten en el mismo `.claude/` sin colisión (namespaces disjuntos:
+`trycore/` para discovery vs. `opsx/` + `build/` para construcción).
+
+> **Regla de oro:** `METODOLOGIA.md` es la fuente de verdad. Si una skill la contradice, **gana la
+> metodología**.
+
+---
+
+## Mapa de los 15 minutos
+
+| Min | Paso | Quién lo corre |
+|---|---|---|
+| 0–2 | 1. Instalar el CLI + requisitos duros | terminal |
+| 2–5 | 2. `trycore-build init` en tu proyecto | terminal |
+| 5–6 | 3. `trycore-build doctor` (verificar) | terminal |
+| 6–9 | 4. `/build:onboard` (parametrizar dominio) | Claude Code |
+| 9–14 | 5. Abrir un slice con la skill `building-a-slice` | Claude Code |
+| 14+ | 6. ¿Cuándo correr `releasing-a-version`? | Claude Code |
+
+---
+
+## Paso 1 · Instalar el CLI y los requisitos duros (~2 min)
+
+El CLI `trycore-build` siembra los archivos del arnés. Pero el arnés depende de **tres binarios
+externos** que el CLI **no puede instalar por ti**. `init` y `doctor` **fallan (exit 1)** si falta
+alguno:
+
+| Requisito | Para qué | Cómo instalarlo |
+|---|---|---|
+| `openspec` | columna vertebral de `/opsx:*` y las skills `openspec-*` | `npm i -g @fission-ai/openspec` |
+| `python3` | los hooks parsean `build-state.json` con python3 | gestor del sistema (brew, apt, …) |
+| `git` | los hooks y `gitflow-guard` resuelven la raíz y bloquean commits directos | gestor del sistema |
+
+Instala el CLI y OpenSpec:
+
+```bash
+npm install -g @trycore/spec-build-harness   # CLI: bin `trycore-build`
+npm install -g @fission-ai/openspec           # requisito duro
+```
+
+> **Canal CLI vs. plugin.** El canal **npm CLI es el canónico** y el recomendado para operar en un
+> proyecto: instala los comandos en `.claude/commands/{opsx,build}/`, namespaceados por subcarpeta
+> (`/opsx:*`, `/build:onboard`), y referencia los agentes por su nombre. El canal **plugin nativo**
+> (`/plugin marketplace add <repo> ; /plugin install trycore-spec-build-harness@trycore-build`) se
+> ofrece como conveniencia a nivel usuario, pero Claude Code namespacea sus componentes bajo el
+> nombre del plugin (`/trycore-spec-build-harness:*`); las cross-references internas (skills que
+> invocan `/opsx:*`, agentes por nombre) están escritas para el canal CLI. **Para construir en un
+> proyecto, usa el CLI.**
+
+---
+
+## Paso 2 · `trycore-build init` en tu proyecto (~3 min)
+
+Sitúate en la raíz de tu proyecto y ejecuta:
+
+```bash
+trycore-build init
+```
+
+`init` es **idempotente** (re-correrlo es seguro) y siembra:
+
+- **10 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/`.
+- **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`.
+- **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
+  lo puebla `/build:onboard`).
+- **Bloque marcado en `CLAUDE.md`** entre `<!-- BEGIN trycore-build-harness ... -->` y
+  `<!-- END trycore-build-harness -->`, con `{{placeholders}}` **sin resolver** (los resuelve
+  `/build:onboard`).
+
+### Onboarding en dos capas
+
+El onboarding tiene **dos capas** por una razón técnica: un binario Node **no puede escribir la
+auto-memory de Claude**.
+
+1. **Capa mecánica (este CLI)** — captura el stack: lenguaje/deps, package manager, runtime y ruta
+   del PRD. Por **prompt TTY** interactivo, o **CI-safe** con flags y `--yes`.
+2. **Capa semántica (`/build:onboard`, lo corre Claude)** — lee el PRD, pregunta por PII, capa de
+   servicios externos/IA, capa determinista, secretos y decisiones de alto impacto, resuelve los
+   `{{placeholders}}` y escribe la auto-memory. (Paso 4.)
+
+#### Flags de `init` (modo no interactivo / CI)
+
+| Flag | Para qué |
+|---|---|
+| `--yes` | no interactivo: usa defaults para el stack |
+| `--stack <deps>` | dependencias permitidas, coma-separadas |
+| `--pkg-manager <pm>` | package manager (`npm` \| `pnpm` \| `yarn`) |
+| `--runtime <semver>` | semver del runtime (ej. `">=18.18"`) |
+| `--prd-path <path>` | ruta#ancla del PRD técnico (fuente del allowlist) |
+| `--copy` | copiar archivos en vez de symlinkear (Windows sin admin, sandboxes) |
+| `--force-init` | fuerza modo init aunque exista instalación previa |
+| `--skip-doctor` | omite la verificación de requisitos (no recomendado) |
+
+Ejemplo CI-safe:
+
+```bash
+trycore-build init --yes \
+  --stack "express,zod,pg" --pkg-manager pnpm \
+  --runtime ">=18.18" --prd-path "docs/01-prd/prd.md#requisitos-tecnicos"
+```
+
+> Otros comandos del CLI: `trycore-build status` (estado de la instalación y fase del arnés),
+> `trycore-build update` (refresca assets/schema tras actualizar el paquete; **no** pisa estado ni
+> allowlist), `trycore-build uninstall` (quita el arnés **preservando** `state/` y `config/`).
+
+---
+
+## Paso 3 · `trycore-build doctor` (~1 min)
+
+Verifica que el entorno esté listo **antes** de construir:
+
+```bash
+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`).
+- **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.
+
+Si ves `✓ Requisitos satisfechos.`, continúa.
+
+---
+
+## Paso 4 · `/build:onboard` en Claude Code (~3 min)
+
+Abre Claude Code en el proyecto y ejecuta:
+
+```
+/build:onboard
+```
+
+Este slash command (lo corre Claude, no el CLI) **parametriza el dominio**: lee tu PRD y/o
+`openspec/project.md` y confirma contigo, vía `AskUserQuestion`, **6 puntos** que luego leen los
+agentes de calidad:
+
+| Placeholder | Qué define |
+|---|---|
+| `PRD_TECH_PATH` | ruta#ancla del PRD técnico (fuente del stack) |
+| `EXTERNAL_SERVICE_LAYER` | capa de servicios externos / IA y su frontera/aislamiento |
+| `DETERMINISTIC_LAYER` | lógica que **no** puede delegarse a un servicio no determinista |
+| `SENSITIVE_DATA_CATEGORIES` | categorías reguladas de datos / PII del dominio |
+| `SERVER_SIDE_SECRETS` | claves/tokens que **jamás** van al cliente |
+| `HIGH_STAKES_DECISIONS` | decisiones que exigen explicabilidad/justificación en la UI |
+
+Al terminar, `/build:onboard` resuelve los `{{placeholders}}` del bloque marcado en `CLAUDE.md`,
+opcionalmente puebla el `stack-allowlist.json`, y escribe la auto-memory (memorias tipo `project`).
+Si un punto no aplica, se registra explícitamente como "no aplica" (no se deja como `{{...}}`).
+
+---
+
+## Paso 5 · Abrir un slice con `building-a-slice` (~5 min)
+
+Esta es la unidad de trabajo del **inner loop**: **un slice = una épica = un OpenSpec change = una
+rama = un PR**. Las HU de la épica (las que tienen `epica: EP-XXX` en `docs/04-historias/`) son el
+**alcance interno** del change.
+
+En Claude Code, invoca la skill (o pídelo en lenguaje natural: *"construye la épica EP-001"*):
+
+```
+skill building-a-slice
+```
+
+La skill conduce el pipeline (delega en el `build-orchestrator`). Las fases del inner loop:
+
+| Fase | Acción | Delega en | Gate |
+|---|---|---|---|
+| 1 · dor | Validar Definition of Ready | `dor-dod-gatekeeper` | `dor` |
+| 2 · change | `/opsx:new` + bloque `## Trazabilidad` que enlaza el change a la épica | `/opsx:new`, `change-epic-coherence` | `coherence_link` |
+| 3 · tdd | red → green → refactor | `superpowers:test-driven-development` | `tdd` |
+| 4 · smoke | recorrer el journey-hasta-aquí end-to-end | skill `verify`/`run` (+ MCP) | `journey_smoke` |
+| 5 · api/data | contratos + consistencia (si aplican) | `api-contract-tester`, `data-consistency-checker` | `api`, `data` |
+| 6 · dod | Definition of Done reducido por slice | `dor-dod-gatekeeper` | `dod` |
+| 7 · pr | abrir PR + archivar el change en el mismo PR | `/opsx:archive`, `/opsx:sync` | — |
+| 8 · release? | preguntar si correr el Release Gate ahora | usuario (default computado) | — |
+
+Notas clave del inner loop:
+
+- **Esqueleto que camina.** El **primer** slice de una release construye el journey completo más
+  delgado posible (aunque cada paso sea un stub). Cada épica posterior **engorda** un paso y mantiene
+  el `journey_smoke` verde. Nunca se construyen capas horizontales aisladas que "se juntan al final".
+- **Estado = una sola fuente de verdad.** Todo se sincroniza en `.claude/state/build-state.json`
+  (schema y protocolo en `.claude/state/README.md`). Lee antes de actuar; escribe una vez por
+  transición. Un slice activo a la vez; un gate no se salta.
+- **Gates pesados NO se cierran aquí.** `stack`, `security`, `smell`, `ux` y la coherencia triple
+  completa pertenecen al Release Gate. Lo que sí corre en tiempo real son los **hooks**:
+  `stack-guard.sh` (vigila deps fuera del allowlist), `lint-typecheck.sh`, `gitflow-guard.sh`
+  (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`).
+- Objetivo: **≤ ~20 min por épica**, y producto que **camina end-to-end en todo momento**.
+
+---
+
+## Paso 6 · ¿Cuándo correr `releasing-a-version`? (outer loop)
+
+Tras archivar la épica (fase 8), la skill te **pregunta** si correr el Release Gate, con un
+**default computado** desde las líneas de release del Story Map (`docs/02-user-story-map/`):
+
+- Si la épica **cierra una línea de release** (todas sus épicas ya están archivadas) → default
+  **"Sí, correr `releasing-a-version`"**.
+- Si no la cierra → default **"Continuar a la siguiente épica"**. Excepción (*nudge*): si hay
+  **≥ 2 épicas** archivadas desde el último Release Gate, lo recomienda igual.
+
+El humano siempre decide. El Release Gate corre las **revisiones pesadas una sola vez**, sobre el
+**diff acumulado** de toda la release:
+
+| Gate | Delega en |
+|---|---|
+| `security` | `security-reviewer` |
+| `smell` (4 reglas de Beck + code smells) | `simple-design-reviewer` |
+| `ux` (Krug + lighthouse; `null` si sin UI) | `ux-krug-reviewer` |
+| `coherence` (trazabilidad triple AC↔change↔código) | `coherence-three-way` |
+| `stack_arch` (arquitectura del PRD) | `stack-guardian` |
+| `integration` (journey completo con **deps reales**, no stubs) | skill `verify`/`run` |
+
+Los resultados se registran en `build-state.json → releases[]`. **La integración con deps reales es
+obligatoria** para `status: passed`: es el gate que garantiza que el producto realmente funciona al
+terminar. Si algo falla, lo corriges como un slice normal en `building-a-slice` y re-corres el gate.
+
+---
+
+## Resumen del primer ciclo
+
+```
+npm i -g @trycore/spec-build-harness @fission-ai/openspec   # paso 1
+trycore-build init                                          # paso 2
+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
+# y cuando cierres una línea de release del Story Map:
+skill releasing-a-version                                   # paso 6
+```
+
+> El core del arnés es **100% agnóstico** al proyecto. El ejemplo de referencia completo vive
+> aparte, en `docs/examples/reference/` (no forma parte del core).

package/docs/hooks.md

@@ -0,0 +1,143 @@
+# 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.
+
+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.
+
+---
+
+## Resumen de los 6 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)** |
+| `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 |
+
+> 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`.
+
+---
+
+## Detalle por hook
+
+### 1. `load-build-state.sh` — `SessionStart` · no bloqueante
+
+Se dispara al arrancar, limpiar o compactar la sesión (`matcher: startup|clear|compact`). Su trabajo:
+
+- Resuelve la raíz del repo (`git rev-parse --show-toplevel`, con *fallback* a `$CLAUDE_PROJECT_DIR`).
+- Determina la **fase real del arnés**: `active` si existe `package.json`, `authoring` si no (ver [auto-arme](#auto-arme-inertes-hasta-que-exista-packagejson)).
+- Sincroniza `harness_phase` en `state/build-state.json` si cambió (solo si hay `python3` y el archivo existe).
+- Imprime al contexto la rama actual, la fase, y el **slice activo** con sus **gates pendientes** (lee `active_slice.gates` y lista los que están en `false`). Si no hay slice activo, sugiere abrir uno con la skill `building-a-slice` empezando por el DoR.
+
+Es el hook que le da a Claude "memoria de obra" al empezar: sabe en qué historia/épica está, qué change de OpenSpec le corresponde y qué le falta cerrar.
+
+### 2. `gitflow-guard.sh` — `PreToolUse` · Bash · **bloqueante**
+
+Enforce **GitHub Flow estricto** antes de ejecutar cualquier comando Bash. Parsea el `tool_input.command` del JSON del hook y solo actúa sobre comandos `git` de escritura. Bloquea con `exit 2` en tres casos:
+
+1. **Commit directo a `main`/`master`** → exige `git switch -c feature/<slug>`.
+2. **Commit desde una rama no tipada** → solo se permite commitear en `feature/*`, `fix/*` o `chore/*`.
+3. **Push apuntando a `main`/`master`** → la integración va por Pull Request, nunca por push directo.
+
+Cualquier otro comando (incluido cualquier `git` que no sea commit/push) sale `0`. La política está alineada con el inner loop (la skill `building-a-slice` cierra cada slice con PR + archive).
+
+### 3. `stack-guard.sh` — `PreToolUse` · Write/Edit/MultiEdit · **bloqueante**
+
+Vigila el **contrato de stack** declarado en el PRD. Solo le importan las ediciones que tocan `package.json`. Compara las dependencias del contenido entrante (`dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`) contra `config/stack-allowlist.json` —usando *globs* (`fnmatch`)— y **bloquea con `exit 2`** si aparece alguna dependencia fuera de la allowlist.
+
+- Sabe extraer nombres tanto de un `package.json` completo como de un fragmento de edición (regex sobre pares `"nombre": "versión"`).
+- El mensaje guía a actualizar `config/stack-allowlist.json` y dejar nota en `GOVERNANCE.md`, o a consultar al agente `stack-guardian`.
+- La allowlist es **artefacto del consumidor**: el CLI la siembra y `/build:onboard` la puebla a partir del PRD.
+
+### 4. `lint-typecheck.sh` — `PostToolUse` · Write/Edit/MultiEdit · no bloqueante
+
+Tras editar un archivo `.ts`/`.tsx`, delega el estilo a las herramientas para no gastar tokens del modelo en formateo. Si los binarios existen en `node_modules/.bin/`, corre:
+
+- `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.
+
+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`.
+
+### 5. `coherence-flag.sh` — `PostToolUse` · Write/Edit/MultiEdit · no bloqueante
+
+Cuando se edita un `openspec/changes/**/proposal.md`, imprime un recordatorio: correr el agente `change-epic-coherence` para validar el bloque `## Trazabilidad` (Épica `EP-XXX` / Historias `HU-XXX`) y ejecutar `openspec validate`. Es un *nudge* de coherencia change↔épica, no un control de bloqueo.
+
+### 6. `build-gate-check.sh` — `Stop` · no bloqueante
+
+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`.
+
+---
+
+## La cadena de comando única (sin doble disparo entre canales)
+
+Todos los hooks se invocan con **la misma cadena autorresolutiva**, idéntica en el canal CLI y en el canal plugin:
+
+```
+"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/<script>.sh"
+```
+
+- Con el **plugin** instalado, `CLAUDE_PLUGIN_ROOT` apunta a la raíz del plugin → los scripts se resuelven dentro de él.
+- Sin plugin (**CLI puro**), el *fallback* `$CLAUDE_PROJECT_DIR/.claude` resuelve los scripts sembrados por `trycore-build init`.
+
+Como la cadena es **carácter por carácter idéntica** en ambos canales, si el consumidor instala **CLI y plugin a la vez**, Claude Code las **deduplica** y cada hook **dispara una sola vez**. Por eso el merge del CLI compara por *cadena exacta* (no por substring de ruta): así el alta es idempotente y la baja (`uninstall`) remueve **solo** lo que el paquete inyectó, preservando los hooks propios del consumidor.
+
+> Las comillas envuelven la cadena para soportar rutas con espacios.
+
+---
+
+## La guarda `python3` (fail-closed dirigido)
+
+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`.
+
+> `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.
+
+---
+
+## Auto-arme (inertes hasta que exista `package.json`)
+
+Los hooks que tocan el código construido se **auto-arman**: permanecen **inertes durante la fase `authoring`** (mientras no exista `package.json` en disco) y se activan solos al aparecer el primer `package.json` (fase `active`):
+
+| Hook | Comportamiento sin `package.json` |
+|---|---|
+| `load-build-state.sh` | Funciona siempre; reporta fase `authoring`. |
+| `gitflow-guard.sh` | Funciona siempre (GitFlow aplica desde el primer commit). |
+| `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). |
+| `build-gate-check.sh` | Inerte (sale `0` de inmediato). |
+
+Así el arnés convive sin fricción con la fase de *discovery* y se "enciende" cuando empieza la construcción real.
+
+---
+
+## Cómo se instalan
+
+Una sola definición de hooks, expresada en dos archivos espejo según el canal:
+
+### Canal CLI (canónico) — merge en `settings.json`
+
+`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 **permisos mínimos y enumerados** (sin `mcp__*` ni rutas absolutas):
+
+  ```
+  Bash(openspec validate *)
+  Bash(openspec list *)
+  Bash(openspec show *)
+  ```
+
+- `trycore-build uninstall` remueve **solo** las cadenas que el paquete inyectó (por set exacto) y preserva el resto de la config, incluidos `state/` y `config/`.
+
+### Canal plugin — `hooks/build-harness.json`
+
+El plugin declara los hooks en `hooks/build-harness.json` (referenciado desde `.claude-plugin/plugin.json` con `"hooks": "./hooks/build-harness.json"`). El contenido es **equivalente** al bloque que mergea el CLI y usa la **misma cadena de comando**.
+
+> **Caveat de canales:** el canal CLI es el **canónico** para operar en un proyecto. El plugin namespacea los componentes bajo el nombre del plugin (`/trycore-spec-build-harness:*`) por diseño de Claude Code; las cross-references internas (skills que invocan `/opsx:*`, agentes por nombre) están escritas para el canal CLI. Los **hooks**, en cambio, son idénticos en ambos canales y se deduplican si coexisten.

package/hooks/build/build-gate-check.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# build-gate-check.sh — Stop
+# AUTO-ARME: inerte mientras no exista package.json.
+# No bloquea: al cerrar el turno, avisa si hay un slice activo con gates abiertos.
+set -uo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$(pwd)}")"
+[ -f "$ROOT/package.json" ] || exit 0
+STATE="$ROOT/.claude/state/build-state.json"
+[ -f "$STATE" ] || exit 0
+command -v python3 >/dev/null 2>&1 || exit 0
+
+python3 - "$STATE" <<'PY' 2>/dev/null || true
+import json,sys
+d=json.load(open(sys.argv[1]))
+s=d.get("active_slice")
+if not s: sys.exit(0)
+g=s.get("gates",{})
+abiertos=[k for k,v in g.items() if v is False]
+if abiertos:
+    print(f"build-gate-check: slice {s.get('hu')} en fase '{s.get('phase')}' con gates abiertos: {', '.join(abiertos)}.", file=sys.stderr)
+    print("   No archives ni abras PR hasta cerrarlos (ver building-a-slice / dod.md).", file=sys.stderr)
+PY
+exit 0

package/hooks/build/coherence-flag.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# coherence-flag.sh — PostToolUse · Write/Edit en openspec/changes/**/proposal.md
+# No bloquea: recuerda validar la trazabilidad del change recién tocado.
+set -uo pipefail
+
+INPUT="$(cat)"
+
+# Guarda python3 [H4]: hook informativo no-bloqueante; si falta python3, omite el recordatorio.
+command -v python3 >/dev/null 2>&1 || exit 0
+
+FILE="$(printf '%s' "$INPUT" | python3 -c 'import sys,json
+try:
+    ti=json.load(sys.stdin).get("tool_input",{})
+    print(ti.get("file_path") or ti.get("path") or "")
+except Exception:
+    print("")' 2>/dev/null)"
+
+case "$FILE" in
+  *openspec/changes/*/proposal.md)
+    echo "🔗 proposal.md modificado: corre el agente change-epic-coherence para validar el bloque '## Trazabilidad' (Épica EP-XXX / Historias HU-XXX) y 'openspec validate'." >&2
+    ;;
+esac
+exit 0

package/hooks/build/gitflow-guard.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# gitflow-guard.sh — PreToolUse · Bash
+# Enforce GitHub Flow estricto:
+#   - Prohíbe `git commit` directo en main/master.
+#   - Prohíbe `git push` que apunte a main/master (la integración va por PR).
+#   - Exige trabajar en rama feature/* | fix/* | chore/* para commitear.
+# Bloquea con exit 2 (stderr se devuelve a Claude). Cualquier otra cosa -> exit 0.
+set -euo pipefail
+
+INPUT="$(cat)"
+
+# Guarda python3 [H4]: si falta, no podemos parsear el JSON del hook. Fail-closed DIRIGIDO:
+# solo bloqueamos (exit 2) si el comando crudo parece un git commit/push; si no, exit 0.
+if ! command -v python3 >/dev/null 2>&1; then
+  if printf '%s' "$INPUT" | grep -Eq 'git[^"]*(commit|push)'; then
+    echo "⛔ gitflow-guard: python3 no disponible; no puedo analizar el comando git. Instala python3 (trycore-build doctor)." >&2
+    exit 2
+  fi
+  exit 0
+fi
+
+CMD="$(printf '%s' "$INPUT" | python3 -c 'import sys,json
+try:
+    print(json.load(sys.stdin).get("tool_input",{}).get("command",""))
+except Exception:
+    print("")')"
+
+# Sólo nos interesan comandos git de escritura.
+if ! printf '%s' "$CMD" | grep -Eq '(^|[;&| ])git[ ]'; then
+  exit 0
+fi
+
+is_commit=false
+is_push=false
+printf '%s' "$CMD" | grep -Eq '(^|[;&| ])git[ ]+(.*[ ])?commit([ ]|$)' && is_commit=true
+printf '%s' "$CMD" | grep -Eq '(^|[;&| ])git[ ]+(.*[ ])?push([ ]|$)'   && is_push=true
+
+if [ "$is_commit" = false ] && [ "$is_push" = false ]; then
+  exit 0
+fi
+
+BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '')"
+
+block() {
+  echo "⛔ gitflow-guard (GitHub Flow estricto): $1" >&2
+  echo "   Política: main protegida · trabajar en feature/* | fix/* | chore/* · integrar por PR." >&2
+  exit 2
+}
+
+# 1) Commit directo a main/master.
+if [ "$is_commit" = true ] && printf '%s' "$BRANCH" | grep -Eq '^(main|master)$'; then
+  block "commit directo a '$BRANCH' no permitido. Crea una rama: git switch -c feature/<slug>"
+fi
+
+# 2) Commit desde una rama no tipada.
+if [ "$is_commit" = true ] && [ -n "$BRANCH" ] && ! printf '%s' "$BRANCH" | grep -Eq '^(feature|fix|chore)/'; then
+  block "rama '$BRANCH' no sigue la convención. Usa feature/* | fix/* | chore/* para commitear."
+fi
+
+# 3) Push apuntando a main/master.
+if [ "$is_push" = true ] && printf '%s' "$CMD" | grep -Eq 'push[^|;&]*[ :](main|master)([ ]|$|:)'; then
+  block "push directo a main/master no permitido. Abre un Pull Request desde tu rama feature/*."
+fi
+
+exit 0

package/hooks/build/lint-typecheck.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# lint-typecheck.sh — PostToolUse · Write/Edit en *.ts/*.tsx
+# 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).
+set -uo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$(pwd)}")"
+[ -f "$ROOT/package.json" ] || exit 0   # guard de auto-arme
+
+# Guarda python3 [H4]: hook no-bloqueante; sin python3 no podemos extraer el archivo → omite.
+command -v python3 >/dev/null 2>&1 || exit 0
+
+INPUT="$(cat)"
+FILE="$(printf '%s' "$INPUT" | python3 -c 'import sys,json
+try:
+    ti=json.load(sys.stdin).get("tool_input",{})
+    print(ti.get("file_path") or ti.get("path") or "")
+except Exception:
+    print("")' 2>/dev/null)"
+
+case "$FILE" in
+  *.ts|*.tsx) : ;;
+  *) exit 0 ;;
+esac
+
+cd "$ROOT" || exit 0
+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
+exit 0

package/hooks/build/load-build-state.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# load-build-state.sh — SessionStart
+# Inyecta al contexto: rama actual, harness_phase, slice activo y gates abiertos.
+# Además sincroniza harness_phase (authoring -> active) según exista package.json.
+set -uo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$(pwd)}")"
+STATE="$ROOT/.claude/state/build-state.json"
+BRANCH="$(git -C "$ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'desconocida')"
+
+# Determina la fase real del arnés.
+if [ -f "$ROOT/package.json" ]; then PHASE="active"; else PHASE="authoring"; fi
+
+# Sincroniza harness_phase en el estado (si python3 disponible y el archivo existe).
+if [ -f "$STATE" ] && command -v python3 >/dev/null 2>&1; then
+  python3 - "$STATE" "$PHASE" <<'PY' 2>/dev/null || true
+import json,sys
+path,phase=sys.argv[1],sys.argv[2]
+try:
+    d=json.load(open(path))
+    if d.get("harness_phase")!=phase:
+        d["harness_phase"]=phase
+        json.dump(d,open(path,"w"),indent=2,ensure_ascii=False)
+except Exception:
+    pass
+PY
+fi
+
+echo "🏗️  Arnés de construcción"
+echo "   Rama: $BRANCH | Fase del arnés: $PHASE"
+
+if [ -f "$STATE" ] && command -v python3 >/dev/null 2>&1; then
+  python3 - "$STATE" <<'PY' 2>/dev/null || true
+import json,sys
+d=json.load(open(sys.argv[1]))
+s=d.get("active_slice")
+if not s:
+    print("   Slice activo: ninguno. Usa la skill building-a-slice para abrir uno (empieza por DoR).")
+else:
+    g=s.get("gates",{})
+    abiertos=[k for k,v in g.items() if v is False]
+    print(f"   Slice activo: {s.get('hu')} ({s.get('epica')}) · change={s.get('openspec_change')} · fase={s.get('phase')}")
+    print(f"   Gates pendientes: {', '.join(abiertos) if abiertos else 'ninguno ✅'}")
+PY
+fi
+exit 0

package/hooks/build/stack-guard.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# stack-guard.sh — PreToolUse · Write/Edit en package.json
+# AUTO-ARME: si aún no existe package.json en disco (primer scaffold), no hay
+# qué comparar -> exit 0. Una vez existe, bloquea (exit 2) la introducción de
+# dependencias fuera de .claude/config/stack-allowlist.json (el contrato de stack del PRD).
+set -uo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$(pwd)}")"
+ALLOW="$ROOT/.claude/config/stack-allowlist.json"
+[ -f "$ALLOW" ] || exit 0
+
+INPUT="$(cat)"
+
+# Guarda python3 [H4]: si falta, no podemos verificar las deps. Fail-closed DIRIGIDO:
+# solo bloqueamos (exit 2) si la edición toca package.json; si no, exit 0.
+if ! command -v python3 >/dev/null 2>&1; then
+  if printf '%s' "$INPUT" | grep -q 'package\.json'; then
+    echo "⛔ stack-guard: python3 no disponible; no puedo verificar las dependencias de package.json. Instala python3 (trycore-build doctor)." >&2
+    exit 2
+  fi
+  exit 0
+fi
+
+# El script va por heredoc (= stdin), así que el JSON del hook se pasa por la
+# variable de entorno INPUT, no por stdin.
+VIOL="$(ALLOW="$ALLOW" INPUT="$INPUT" python3 <<'PY' 2>/dev/null
+import os,sys,json,re,fnmatch
+try:
+    data=json.loads(os.environ.get("INPUT") or "{}")
+except Exception:
+    sys.exit(0)
+ti=data.get("tool_input",{})
+fp=ti.get("file_path") or ti.get("path") or ""
+if not fp.endswith("package.json"):
+    sys.exit(0)
+content=ti.get("content") or ti.get("new_string") or ""
+if not content.strip():
+    sys.exit(0)
+allow=json.load(open(os.environ["ALLOW"])).get("allow",[])
+def ok(name):
+    return any(fnmatch.fnmatch(name, pat) for pat in allow)
+# Extrae nombres de deps tanto de JSON completo como de fragmentos de edición.
+deps=set()
+try:
+    pkg=json.loads(content)
+    for sec in ("dependencies","devDependencies","peerDependencies","optionalDependencies"):
+        deps.update((pkg.get(sec) or {}).keys())
+except Exception:
+    for m in re.finditer(r'"((?:@[\w.-]+/)?[\w.-]+)"\s*:\s*"[\^~>=<*\d][^"]*"', content):
+        deps.add(m.group(1))
+bad=sorted(d for d in deps if d and not ok(d))
+if bad:
+    print(" ".join(bad))
+PY
+)"
+
+if [ -n "$VIOL" ]; then
+  echo "⛔ stack-guard: dependencias fuera del stack declarado del PRD (allowlist): $VIOL" >&2
+  echo "   Si es intencional, actualiza .claude/config/stack-allowlist.json y deja nota en GOVERNANCE.md," >&2
+  echo "   o consulta al agente stack-guardian. Allowlist: .claude/config/stack-allowlist.json" >&2
+  exit 2
+fi
+exit 0