@trycore/spec-build-harness 0.8.1 → 0.8.3

package/skills/setup-architecture/assets/0000-drivers-y-asrs.template.md

@@ -0,0 +1,101 @@
+---
+id: 0000
+title: "Catálogo de Drivers Arquitectónicos y ASRs (entrada del método ADD)"
+date: YYYY-MM-DD
+status: living-document
+authors:
+  - <Equipo Arquitectura>
+tags:
+  - add
+  - drivers
+  - asr
+  - quality-attributes
+---
+
+# ADR 0000 — Drivers Arquitectónicos y ASRs
+
+> **Naturaleza:** No es un ADR de decisión, sino la **entrada de diseño** (Paso 1 del método ADD de Len
+> Bass). Consolida propósito, requisitos funcionales primarios, escenarios de atributos de calidad
+> priorizados, restricciones y concerns. Toda decisión en un ADR (0001+) debe trazar a uno o más drivers
+> de este catálogo, y todo driver debe estar cubierto por al menos un ADR (ver
+> [_backlog-arquitectonico.md](_backlog-arquitectonico.md)).
+>
+> **Cómo se genera:** la skill `setup-architecture` (`/build:architect`) lo **propone** leyendo `docs/`
+> (PRD + user story map + `03-backlog/epicas.md` + `04-historias/HU-*.md`) — de solo lectura. Este es un
+> **documento vivo**: cada re-corrida añade drivers nuevos que surjan de HUs/épicas nuevas.
+
+## Cómo se usa este documento en ADD
+
+ADD diseña por **rondas e iteraciones** de 7 pasos. Este catálogo alimenta los pasos 1 y 2:
+
+- **Paso 1 — Review Inputs:** todo lo de este documento.
+- **Paso 2 — Establish Iteration Goal:** cada iteración selecciona un subconjunto priorizado de estos
+  drivers (ver §6 Plan de iteraciones).
+
+## Propósito de diseño
+
+<Greenfield / brownfield; una línea sobre qué es el sistema y su enfoque de diseño (top-down desde el
+sistema completo, o refinamiento de elementos internos).>
+
+Fuente: [docs/01-prd/<prd>.md](../01-prd/<prd>.md) §<x>.
+
+## 1. Objetivos de negocio (OE)
+
+| ID | Objetivo | Métrica / Meta |
+|----|----------|----------------|
+| OE-01 | … | … |
+
+## 2. Requisitos funcionales primarios (UC) — arquitecturalmente significativos
+
+> Solo los casos de uso que **moldean** la arquitectura. No es el backlog completo.
+
+| UC | Descripción | Trazabilidad |
+|----|-------------|--------------|
+| UC-1 | … | OE-…, HU-… |
+
+## 3. Escenarios de atributos de calidad (QA) — formato de 6 partes
+
+> Formato Bass: **Fuente del estímulo · Estímulo · Artefacto · Entorno · Respuesta · Medida de respuesta.**
+> Cada escenario lleva prioridad `(Importancia de negocio, Impacto/Dificultad arquitectónica)` en escala
+> {A=Alta, M=Media, B=Baja}. La **medida de respuesta** debe ser cuantificable (es lo que convierte un
+> deseo en un ASR verificable).
+
+### QA-1 — <Atributo> · prioridad (A, M)
+- **Fuente:** …
+- **Estímulo:** …
+- **Artefacto:** …
+- **Entorno:** …
+- **Respuesta:** …
+- **Medida:** … (traza a HU/AC/PRD)
+
+## 4. Restricciones (CON)
+
+| ID | Restricción | Origen |
+|----|-------------|--------|
+| CON-1 | … | … |
+
+## 5. Concerns / preocupaciones del proyecto (CRN)
+
+| ID | Concern | Implicación de diseño |
+|----|---------|-----------------------|
+| CRN-1 | … | … |
+
+## 6. Plan de iteraciones (rondas ADD ↔ fases del PRD / líneas de release)
+
+> Estrategia: iterar en el orden de las fases del PRD (o las líneas de release del Story Map). Cada
+> iteración ejecuta los Pasos 2–7 de ADD sobre el subconjunto de drivers indicado.
+
+| Iteración | Fase PRD / Release | Drivers seleccionados (Paso 2) | Elementos a refinar (Paso 3) | ADRs |
+|-----------|--------------------|--------------------------------|------------------------------|------|
+| **1** | … | … | … | … |
+
+## 7. Matriz de priorización (Importancia de negocio × Impacto arquitectónico)
+
+| | Impacto arq. ALTO | Impacto arq. MEDIO | Impacto arq. BAJO |
+|---|---|---|---|
+| **Negocio ALTO** | … | … | — |
+| **Negocio MEDIO** | … | … | — |
+
+> Los cuadrantes superiores (alta importancia × alto impacto) son los **ASRs críticos**: se atacan
+> primero o se mitiga su riesgo lo antes posible (principio ADD de iterar hasta satisfacer los drivers
+> críticos / mitigar el riesgo).

package/skills/setup-architecture/assets/_backlog-arquitectonico.template.md

@@ -0,0 +1,51 @@
+# Backlog Arquitectónico (ADD — Paso 7)
+
+> Tablero de seguimiento del método ADD. Rastrea qué drivers/ASRs
+> ([0000-drivers-y-asrs.md](0000-drivers-y-asrs.md)) han sido abordados por una decisión, cuáles están en
+> progreso y cuáles pendientes. Equivale al Kanban arquitectónico que recomienda Len Bass para no perder
+> de vista la cobertura entre iteraciones.
+>
+> **Este archivo es el estado de la capa de arquitectura.** Lo escribe la skill `setup-architecture`
+> (`/build:architect`) y lo consumen los gates del arnés: el **DoR** verifica que los drivers
+> arquitectónicamente significativos de una épica tengan un ADR con estado ≥ `ABORDADO` antes de abrir el
+> slice; el gate **`stack_arch`** del Release Gate audita conformidad contra los ADRs referenciados aquí.
+
+**Convención de estado:**
+- `PENDIENTE` — driver sin decisión asociada.
+- `EN DISEÑO` — iteración en curso.
+- `ABORDADO` — existe ADR que lo cubre con análisis (Paso 7) registrado.
+- `VERIFICADO` — el análisis confirma que la decisión satisface la medida de respuesta (idealmente
+  revisado por un par).
+
+## Tablero por driver
+
+> La columna **Trazabilidad** (EP/HU/§PRD de los que sale el driver, heredada del `0000`) es la que usa
+> el DoR para el join épica↔driver: dado un `EP-XXX`, sus drivers son las filas cuya trazabilidad cita
+> esa épica o alguna de sus HU.
+
+| Driver | Tipo | Prioridad | Trazabilidad (EP/HU) | Iteración | ADR | Estado |
+|--------|------|-----------|----------------------|-----------|-----|--------|
+| UC-1 … | Funcional | (A,A) | EP-…, HU-… | 1 | 000N | PENDIENTE |
+| QA-1 … | QA | (A,M) | HU-…, §PRD | 1 | 000N | PENDIENTE |
+| CON-1 … | Restricción | — | §PRD | 1 | 000N | PENDIENTE |
+| CRN-1 … | Concern | — | — | 1 | 000N | PENDIENTE |
+
+## Riesgos arquitectónicos abiertos
+
+> Salida del análisis ATAM-lite (Paso 6/7): puntos de sensibilidad, trade-offs y riesgos sin mitigar.
+> Cada riesgo traza a su driver y a la mitigación planificada. Marcar ✅ CERRADO al resolver (no borrar:
+> deja el rastro).
+
+| Riesgo | Driver | Mitigación planificada | Iteración |
+|--------|--------|------------------------|-----------|
+| … | QA-… | … | … |
+
+## Bitácora de iteraciones
+
+> Una fila por ronda ADD. `Objetivo` = Paso 2; `Resultado` = Paso 7 (qué ADR se creó/refactorizó y qué
+> quedó sin resolver). La fila de **Cierre** registra la promoción `proposed → accepted` tras la revisión
+> humana.
+
+| Iteración | Fecha | Objetivo (Paso 2) | Resultado (Paso 7) |
+|-----------|-------|-------------------|--------------------|
+| 1 | YYYY-MM-DD | … | … |

package/skills/setup-architecture/assets/adr-add.template.md

@@ -0,0 +1,84 @@
+---
+id: NNNN
+title: "<Título de la decisión>"
+date: YYYY-MM-DD
+status: proposed   # proposed | accepted | superseded | deprecated
+authors:
+  - <Equipo / persona>
+tags: []
+add:
+  iteracion: <n>
+  fase_prd: "<Fase X>"
+---
+
+# ADR NNNN — <Título>
+
+> Plantilla alineada al método **ADD** (Attribute-Driven Design, Len Bass — *Software Architecture in
+> Practice*). Cada sección numerada corresponde a un paso del método. Las decisiones deben trazar a
+> [0000-drivers-y-asrs.md](0000-drivers-y-asrs.md) y actualizar
+> [_backlog-arquitectonico.md](_backlog-arquitectonico.md). Generada por la skill `setup-architecture`
+> (`/build:architect`); un humano la promueve `proposed → accepted`.
+
+## 1. Objetivo de la iteración y drivers seleccionados (Pasos 2–3)
+
+- **Objetivo de la iteración:** <qué se busca resolver en esta ronda>.
+- **Elemento(s) a refinar:** <sistema completo | servicio X | módulo Y>.
+- **Drivers abordados:**
+  - Funcionales: UC-…
+  - Atributos de calidad: QA-… (con su medida de respuesta)
+  - Restricciones: CON-…
+  - Concerns: CRN-…
+
+## 2. Conceptos de diseño elegidos (Paso 4)
+
+> Patrones arquitectónicos, **tácticas** (sentido Bass), componentes externos o arquitecturas de
+> referencia evaluados y elegidos para satisfacer los drivers. Registra las alternativas descartadas:
+> ese es el valor del ADR.
+
+| Driver | Concepto / Táctica | Alternativas descartadas | Razón |
+|--------|--------------------|--------------------------|-------|
+| QA-… | … | … | … |
+
+## 3. Instanciación: responsabilidades e interfaces (Paso 5)
+
+> Cómo se convierten los conceptos en estructuras reales: componentes/módulos, sus responsabilidades y
+> los contratos (interfaces) por los que se comunican.
+
+- **Elementos instanciados:** …
+- **Responsabilidades:** …
+- **Interfaces / contratos:** …
+
+## 4. Vistas y registro de la decisión (Paso 6)
+
+> Boceto de vista(s) estructural(es) — de módulos, de componentes-y-conectores o de asignación física —
+> y el rationale + trade-offs.
+
+```mermaid
+%% vista estructural / de despliegue / de secuencia
+```
+
+**Decisión:** …
+
+**Trade-offs aceptados:** …
+
+## 5. Análisis del diseño (Paso 7)
+
+> ¿La decisión satisface el objetivo de la iteración? Cada driver con veredicto y evidencia/medida.
+
+| Driver | ¿Satisfecho? | Evidencia / medida | Riesgo residual |
+|--------|--------------|--------------------|-----------------|
+| QA-… | ✅/⚠️/❌ | … | … |
+
+**Drivers no resueltos en esta iteración:** … (se devuelven al backlog arquitectónico).
+
+## 6. Consecuencias
+
+- Positivas: …
+- Negativas / riesgos: …
+- Operacionales: …
+
+## 7. Trazabilidad
+
+- Drivers: [0000-drivers-y-asrs.md](0000-drivers-y-asrs.md)
+- PRD / HU / Flows: …
+- Stack operacionalizado en: `.claude/config/stack-allowlist.json` (si esta ADR decide stack)

package/skills/setup-architecture/references/add-method.md

@@ -0,0 +1,53 @@
+# Método ADD — iterar el diseño (Pasos 2–7) — referencia
+
+ADD (Attribute-Driven Design, Len Bass) diseña por **rondas**. Cada ronda ejecuta 7 pasos sobre un
+subconjunto priorizado de drivers del catálogo `0000`. Una ronda produce **un ADR** (a veces refactoriza
+uno previo). Usa la plantilla `assets/adr-add.template.md` de esta skill —instalada junto a estas
+references— (7 secciones = los 7 pasos, con su frontmatter `id/title/date/status/authors/tags/add`).
+
+## Los 7 pasos por iteración
+
+1. **Review inputs** — ya está en `0000-drivers-y-asrs.md`.
+2. **Establecer el objetivo de la iteración** — elige la fase/release y el subconjunto de drivers
+   (empieza por los ASRs críticos, cuadrante (A,A) de la matriz). → §1 del ADR.
+3. **Elegir el elemento a refinar** — sistema completo (primera ronda, top-down) o un módulo/servicio
+   interno (rondas posteriores). → §1 del ADR.
+4. **Elegir conceptos de diseño** — **tácticas** (Bass), **patrones**/estilos, componentes externos o
+   arquitecturas de referencia. Registra las **alternativas descartadas** y por qué. → §2 del ADR.
+5. **Instanciar** — convierte los conceptos en componentes/módulos reales con responsabilidades e
+   **interfaces/contratos**. → §3 del ADR.
+6. **Bocetar vistas y registrar la decisión** — al menos una vista (módulos, C&C o despliegue) en
+   `mermaid`, con la **decisión** y sus **trade-offs**. → §4 del ADR.
+7. **Analizar** (ATAM-lite) — cada driver con veredicto y evidencia; drivers no resueltos vuelven al
+   backlog. → §5 del ADR (delegado a `architecture-evaluator`; ver `atam-lite.md`).
+
+## Tácticas ↔ atributos (guía rápida, no exhaustiva)
+
+| Atributo (QA) | Tácticas típicas (Bass) | Estilos/patrones que las agrupan |
+|---|---|---|
+| Disponibilidad | redundancia, detección (heartbeat/ping), recuperación (rollback, reintento con backoff) | activo-pasivo, health-check, circuit breaker |
+| Rendimiento | gestión de recursos (índices, caché), gestión de demanda (paginación, rate-limit) | CQRS de lectura, caché-aside |
+| Seguridad | resistir (authN/authZ, secretos fuera de código), detectar (auditoría), recuperar | RBAC central, gateway de seguridad, WORM/SIEM |
+| Modificabilidad | encapsular, intermediario, restringir dependencias | capas, hexagonal/puertos-adaptadores, contrato OpenAPI como fuente |
+| Integrabilidad | adaptador, orquestación, límite (bulkhead) | adaptadores por integración, anti-corruption layer |
+| Escalabilidad | replicación, particionamiento, trabajo asíncrono | workers, colas, outbox |
+| Integridad transaccional | transacción, compensación (saga), idempotencia | saga orquestada + outbox |
+
+## Estrategia de iteración
+
+- **Ancho antes que profundo**: primera ronda decide el estilo estructural y el stack del **sistema
+  completo**; rondas posteriores refinan piezas (worker, motor de notificaciones, servicio de RBAC…).
+- **Cimiento primero**: las decisiones fundacionales (identidad/authN, acceso a datos, arquitectura base,
+  design-system) van en las primeras iteraciones — son las que el DoR exigirá antes de abrir épicas de
+  negocio (`layer: foundational`).
+- **Un ADR por decisión coherente**, no por archivo tocado. Si una decisión supersede a otra, marca la
+  vieja `superseded` y enlaza; no borres.
+- **Stack como decisión trazada**: las elecciones de lenguaje/framework/BD/infra son ADRs con su §2
+  (alternativas descartadas). En la fase 5 se consolidan en `stack-allowlist.json`. Si el stack elegido
+  **diverge** del PRD §técnica, regístralo explícitamente como riesgo/restricción (no lo escondas).
+
+## Salida por ronda
+
+1. Escribe `docs/adr/000N-<slug>.md` desde la plantilla, con §1–§4 completas.
+2. Corre `architecture-evaluator` sobre el ADR → completa §5 y §6.
+3. Actualiza `_backlog-arquitectonico.md`: estado de cada driver, riesgos nuevos, fila de bitácora.

package/skills/setup-architecture/references/atam-lite.md

@@ -0,0 +1,44 @@
+# ATAM-lite — evaluación de la arquitectura en papel (ADD Paso 7) — referencia
+
+Análisis de cada ADR **antes de programar**, para descubrir riesgos y trade-offs. Es una versión ligera
+de ATAM (Architecture Tradeoff Analysis Method): no se hace un taller formal con stakeholders, sino un
+barrido adversarial delegado en el agente `architecture-evaluator` (read-only). Alimenta §5/§6 del ADR y
+la sección de riesgos del backlog (estructura completa del backlog — tablero por driver, riesgos
+abiertos, bitácora — en `assets/_backlog-arquitectonico.template.md` de esta skill).
+
+## Qué produce el evaluador, por ADR
+
+- **Veredicto por driver**: para cada driver que el ADR dice satisfacer, ✅/⚠️/❌ con la **evidencia o
+  medida** que lo respalda (o la que falta). Un ⚠️/❌ es un riesgo, no un rechazo.
+- **Puntos de sensibilidad**: propiedades del diseño donde una decisión afecta fuertemente a un atributo
+  (p.ej. "el tamaño del pool de conexiones determina QA-1 rendimiento de lectura").
+- **Trade-offs**: puntos donde una decisión mejora un atributo y empeora otro (p.ej. "el backoff
+  1s/3s/9s da robustez pero puede exceder el P99 ≤ 10 s de la integración externa").
+- **Riesgos**: decisiones sin evidencia, drivers no cubiertos, supuestos sin validar. Cada uno con
+  driver, mitigación planificada e iteración.
+- **Drivers no resueltos**: se devuelven explícitamente al backlog (estado `PENDIENTE`/`EN DISEÑO`).
+
+## Conceptos ATAM que se usan
+
+- **Sensitivity point** — una decisión de la que depende crítica­mente una respuesta de calidad.
+- **Tradeoff point** — un sensitivity point que afecta a más de un atributo en direcciones opuestas.
+- **Risk** — una decisión (o su ausencia) que puede impedir alcanzar la medida de respuesta.
+- **Non-risk** — una decisión que, analizada, se confirma segura para los drivers en juego.
+
+## Reglas del análisis
+
+- **Adversarial y honesto**: el evaluador busca **refutar** que el ADR satisface sus drivers. Ante la
+  duda, marca riesgo, no lo omitas. Es más barato un riesgo en papel que un rediseño en código.
+- **Medida, no opinión**: un driver solo se marca ✅ si hay una medida verificable o un plan de
+  verificación (k6, prueba de carga, matriz de RBAC, etc.). "Parece suficiente" es ⚠️.
+- **No decide negocio**: si el riesgo se resuelve con una decisión de negocio (exponer o no un dato,
+  fijar o aplazar un objetivo de DR), lo marca como **trade-off de negocio** → sube a la revisión única
+  (fase 5), no lo resuelve el modelo.
+- **Cierre trazable**: al mitigar un riesgo en una iteración posterior, se marca ✅ CERRADO en el backlog
+  con el ADR que lo cerró; no se borra la fila.
+
+## Cobertura (invariante del backlog)
+
+Al cerrar la capa, **todo driver del 0000 debe tener estado ≥ ABORDADO** o un riesgo abierto explícito
+que explique por qué no. Un driver crítico (A,A) en `PENDIENTE` sin riesgo declarado es un fallo de la
+capa: no está lista para habilitar el build.

package/skills/setup-architecture/references/drivers-extraction.md

@@ -0,0 +1,39 @@
+# Extracción de drivers / ASRs (ADD Paso 1) — referencia
+
+Objetivo de la fase: producir `docs/adr/0000-drivers-y-asrs.md` **leyendo `docs/`** (solo lectura),
+sobre la plantilla `assets/0000-drivers-y-asrs.template.md` de esta skill (frontmatter + §1–§7). Se
+delega el barrido a `asr-extractor` (fan-out) y la sesión principal consolida. Un **ASR**
+(Architecturally Significant Requirement) es un requisito que, si cambia, cambia la arquitectura.
+
+## De dónde sale cada bloque del 0000
+
+| Bloque del 0000 | Fuente en `docs/` | Cómo derivarlo |
+|---|---|---|
+| **OE** (objetivos de negocio) | `01-prd/` §objetivos, `02-user-story-map/` | Copiar los objetivos específicos + su métrica/meta. Si el PRD no da métrica, proponerla y marcarla como *a validar*. |
+| **UC** (funcionales significativos) | `03-backlog/epicas.md`, `04-historias/HU-*.md` | **Solo** los casos que moldean la arquitectura (integraciones externas, transaccionalidad, RBAC, asincronía, auditoría). No es el backlog completo. |
+| **QA** (escenarios de calidad) | PRD §requisitos no funcionales, AC de las HUs, §técnica | Un escenario de **6 partes** por atributo (rendimiento, disponibilidad, seguridad, integrabilidad, modificabilidad, observabilidad, escalabilidad…). La **medida** debe ser cuantificable. |
+| **CON** (restricciones) | PRD §técnica/§7, política de datos, identidad | Lo que **no** es negociable (stack impuesto, prohibiciones, headers, gates de CI). |
+| **CRN** (concerns) | PRD riesgos, capacidades del equipo, costos | Preocupaciones que condicionan el diseño aunque no sean requisitos formales. |
+| **Prioridad** | juicio + importancia del PRD | Par `(Importancia de negocio, Impacto arquitectónico)` en {A,M,B}. El cuadrante (A,A) son los **ASRs críticos**. |
+| **Plan de iteraciones** | fases del PRD / líneas de release del story map | Una iteración por fase; lista los drivers que ataca cada una. |
+
+## Escenario QA de 6 partes (formato Bass)
+
+Cada QA-N se escribe con exactamente estas seis partes:
+
+- **Fuente** del estímulo (quién/qué lo genera)
+- **Estímulo** (el evento)
+- **Artefacto** (qué parte del sistema recibe el estímulo)
+- **Entorno** (condiciones: normal, pico, degradado)
+- **Respuesta** (qué hace el sistema)
+- **Medida de respuesta** (cuantificable: P95 ≤ X ms, uptime ≥ X%, 0 incidentes…)
+
+Sin medida cuantificable no es un ASR: es un deseo. Si el PRD no la da, **propón** una razonable y déjala
+marcada para validación en la revisión (fase 5), no bloquees.
+
+## Reglas
+
+- **Traza siempre**: cada UC/QA cita las HU/OE/§PRD de las que sale (columna Trazabilidad).
+- **No inventes dominio**: si un atributo no tiene sustento en `docs/`, no lo agregues; si es un hueco
+  real (p.ej. el PRD no fija disponibilidad), decláralo como CRN o riesgo, no como QA fabricado.
+- **Documento vivo**: en re-corridas, añade drivers nuevos de HUs/épicas nuevas; no borres los previos.