@dforce2055/dai 0.1.0

package/skills/tdd/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: tdd
+description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+---
+
+# Test-Driven Development
+
+## Philosophy
+
+**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+
+**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
+
+**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
+
+This produces **crap tests**:
+
+- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
+- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
+- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
+- You outrun your headlights, committing to test structure before understanding the implementation
+
+**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+  ...
+```
+
+## Workflow
+
+### 1. Planning
+
+When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching.
+
+Before writing any code:
+
+- [ ] Confirm with user what interface changes are needed
+- [ ] Confirm with user which behaviors to test (prioritize)
+- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
+- [ ] Design interfaces for [testability](interface-design.md)
+- [ ] List the behaviors to test (not implementation steps)
+- [ ] Get user approval on the plan
+
+Ask: "What should the public interface look like? Which behaviors are most important to test?"
+
+**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:   Write test for first behavior → test fails
+GREEN: Write minimal code to pass → test passes
+```
+
+This is your tracer bullet - proves the path works end-to-end.
+
+### 3. Incremental Loop
+
+For each remaining behavior:
+
+```
+RED:   Write next test → fails
+GREEN: Minimal code to pass → passes
+```
+
+Rules:
+
+- One test at a time
+- Only enough code to pass current test
+- Don't anticipate future tests
+- Keep tests focused on observable behavior
+
+### 4. Refactor
+
+After all tests pass, look for [refactor candidates](refactoring.md):
+
+- [ ] Extract duplication
+- [ ] Deepen modules (move complexity behind simple interfaces)
+- [ ] Apply SOLID principles where natural
+- [ ] Consider what new code reveals about existing code
+- [ ] Run tests after each refactor step
+
+**Never refactor while RED.** Get to GREEN first.
+
+## Checklist Per Cycle
+
+```
+[ ] Test describes behavior, not implementation
+[ ] Test uses public interface only
+[ ] Test would survive internal refactor
+[ ] Code is minimal for this test
+[ ] No speculative features added
+```

package/skills/tdd/deep-modules.md

@@ -0,0 +1,33 @@
+# Deep Modules
+
+From "A Philosophy of Software Design":
+
+**Deep module** = small interface + lots of implementation
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid)
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing interfaces, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?

package/skills/tdd/interface-design.md

@@ -0,0 +1,31 @@
+# Interface Design for Testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area**
+   - Fewer methods = fewer tests needed
+   - Fewer params = simpler test setup

package/skills/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/skills/tdd/refactoring.md

@@ -0,0 +1,10 @@
+# Refactor Candidates
+
+After TDD cycle, look for:
+
+- **Duplication** → Extract function/class
+- **Long methods** → Break into private helpers (keep tests on public interface)
+- **Shallow modules** → Combine or deepen
+- **Feature envy** → Move logic to where data lives
+- **Primitive obsession** → Introduce value objects
+- **Existing code** the new code reveals as problematic

package/skills/tdd/tests.md

@@ -0,0 +1,61 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```

package/templates/adr.md

@@ -0,0 +1,43 @@
+<!--
+  ARCHITECTURE DECISION RECORD (ADR) · dai
+  ─────────────────────────────────────────────────────────────────
+  Registra UNA decisión de fondo, con su contexto y sus consecuencias.
+  Es inmutable una vez aceptada: si la decisión cambia, se escribe un
+  ADR NUEVO que "supersede" a este (no se edita el viejo).
+
+  Los ADR son la forma de enmendar el MANIFIESTO y de cerrar las
+  decisiones abiertas de la metodología. Numerar secuencial: 0001, 0002…
+  Nombre de archivo: NNNN-slug-corto.md
+-->
+
+# ADR-NNNN — <título de la decisión>
+
+- **Estado:** propuesto | aceptado | supersedido por `ADR-XXXX`
+- **Fecha:** YYYY-MM-DD
+- **Decide:** <rol/persona con autoridad para la decisión>
+
+## Contexto
+
+Qué situación obliga a decidir. Las fuerzas en juego (restricciones, dolores,
+requisitos). Lo suficiente para que alguien que cae de nuevo entienda por qué esto
+no era obvio. Sin todavía elegir.
+
+## Decisión
+
+Lo que decidimos, en presente afirmativo: *"Usamos X."* Clara y sin ambigüedad.
+
+## Consecuencias
+
+Qué se vuelve más fácil y qué más difícil por haber decidido esto. Lo bueno **y**
+lo que aceptamos pagar. Incluye las obligaciones nuevas (p. ej. "el CI ahora debe…").
+
+## Alternativas consideradas
+
+- **<Opción B>** — por qué se descartó.
+- **<Opción C>** — por qué se descartó.
+
+<!--
+  Un buen ADR se lee en 2 minutos. Si necesita más, probablemente son varias
+  decisiones: pártelo. La sección más valiosa es "Consecuencias" — es lo que el
+  yo-del-futuro va a agradecer cuando se pregunte "¿por qué hicimos esto?".
+-->

package/templates/commit-msg

@@ -0,0 +1,48 @@
+#!/bin/sh
+# =============================================================================
+# commit-msg · dai · valida que el mensaje siga Conventional Commits
+# =============================================================================
+# Formato:  <tipo>(<scope>)!: <resumen>
+#   tipo    obligatorio · scope opcional · "!" opcional (breaking change)
+#   resumen en imperativo, minúscula, sin punto final, hasta 72 caracteres
+#
+# Cero dependencias: POSIX sh + grep. No necesita dai, node ni commitlint.
+# Instalación: ver governance/commit-convention.md (husky o git hook pelado).
+# =============================================================================
+
+msg_file="$1"
+# Primera línea que no sea comentario (git antepone líneas '#').
+subject=$(grep -vE '^\s*#' "$msg_file" | sed '/./,$!d' | head -1)
+
+# Dejar pasar merges, reverts, fixup/squash y commits de bots (🤖).
+case "$subject" in
+  "Merge "*|"Revert "*|"fixup! "*|"squash! "*|"🤖"*) exit 0 ;;
+esac
+
+pattern='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-z0-9._/-]+\))?!?: .{1,72}$'
+
+if printf '%s' "$subject" | grep -qE "$pattern"; then
+  exit 0
+fi
+
+echo ""
+echo "  ✗  Mensaje de commit inválido"
+echo "  ───────────────────────────────────────────────"
+echo "     tu mensaje:  $subject"
+echo ""
+echo "     formato:     <tipo>(<scope>): <resumen>"
+echo "     tipos:       feat · fix · docs · style · refactor · perf"
+echo "                  test · build · ci · chore · revert"
+echo "     reglas:      resumen en imperativo, minúscula, sin punto final, ≤72"
+echo "                  '!' tras el scope marca un breaking change"
+echo ""
+echo "     ejemplos:    feat(cart): rechaza finalizar un carrito vacío"
+echo "                  fix(auth): corrige el refresh del token"
+echo "                  docs: aclara los niveles N1/N2/N3"
+echo "                  refactor(api)!: unifica el contrato de /orders"
+echo ""
+echo "     traza:       si el commit implementa una US, referénciala en el"
+echo "                  cuerpo (p. ej. \"US: ABC-482\") — el link vive en el"
+echo "                  implements.yaml, pero mencionarlo ayuda a leer el historial."
+echo ""
+exit 1

package/templates/definition-of-done.md

@@ -0,0 +1,50 @@
+<!--
+  DEFINITION OF DONE (DoD) · dai
+  ─────────────────────────────────────────────────────────────────
+  El contrato de cierre del CÓMO: cuándo una implementación está
+  realmente terminada. Cubre los pasos 4–7 de SCRUM-CON-IA.
+
+  Es configurable por organización (sobre todo el ítem de despliegue),
+  pero los ítems de trazabilidad y tests NO se negocian.
+-->
+
+# Definition of Done — ¿la implementación está terminada?
+
+> "Terminada" no es "compila". Es testeable, trazable, revisada y con el estado
+> derivado, no reportado a mano.
+
+## Checklist
+
+### Tests (TDD)
+- [ ] Cada criterio de aceptación tiene su **test** y está **verde**. *([Art. 3](../docs/MANIFIESTO.md#art-3))*
+- [ ] Los tests verifican por la **interfaz pública**, no espían lo interno.
+- [ ] El **smoke** end-to-end del flujo pasa.
+
+### Trazabilidad (el link)
+- [ ] Existe `implements.yaml` con `id`, `version` y `ac_hash`. *(Art. 9)*
+- [ ] El **`ac_hash` coincide** con el de la US vigente (no se implementó una versión atrasada). *(Art. 11)*
+- [ ] La rama sigue la convención (`feature/ABC-###-<slug>`) → ver `governance/branch-naming.md`.
+
+### Revisión
+- [ ] Pasó el **primer pase de IA** (`dai-review`): sin problemas de correctitud.
+- [ ] Un **partner aprobó** el PR/MR (en N1, auto-review honesto). *(Art. 5, Art. 15)*
+- [ ] Cumple los estándares del repo (lint, tipos, convenciones).
+
+### Cierre
+- [ ] El change se promovió (`opsx:apply` → `opsx:archive`) si aplica.
+- [ ] El **CI estampó la cobertura** en el gestor (no la escribió una persona). *(Art. 10)*
+- [ ] La US quedó en estado **implementada**.
+
+## Configurable: ¿"done" incluye desplegado?
+
+Cada organización define hasta dónde llega su DoD según su **nivel de ceremonia**
+(**N1** dev solo · **N2** equipo compacto · **N3** organización grande — ver
+[glosario](../docs/glosario.md)):
+
+| | El DoD termina en… |
+|---|---|
+| **N1 / N2** | mergeado + cobertura estampada. El deploy es aparte. |
+| **N3** | mergeado + **desplegado en el ambiente acordado** (p. ej. `test`), con el CD reportando la versión viva por ambiente. |
+
+> **Implementación ≠ despliegue.** El CI dice "el repo implementó `@v3`"; el CD dice
+> "`@v3` está viva en `pre`". El DoD elige cuál de los dos es el corte de "terminado".

package/templates/definition-of-ready.md

@@ -0,0 +1,51 @@
+<!--
+  DEFINITION OF READY (DoR) · dai
+  ─────────────────────────────────────────────────────────────────
+  El contrato del gate ENTRE el QUÉ y el CÓMO: cuándo una User Story
+  está lista para entrar a un sprint / ser implementada.
+
+  Lo verifica una persona (y la IA puede pre-chequearlo). Si un ítem
+  no se cumple, la US NO entra: vuelve a grill-user-story o grill-intent.
+  Es la contracara del Definition of Done.
+-->
+
+# Definition of Ready — ¿la US está lista para implementarse?
+
+> Una US que no cumple esto no se planifica. No es burocracia: es lo que evita
+> arrancar a codear sobre un QUÉ vago ([Art. 7](../docs/MANIFIESTO.md#art-7) — no vibe coding).
+
+## Checklist
+
+### Identidad y forma (linkeable)
+- [ ] Tiene **ID estable** (ticket del gestor, p. ej. `ABC-###`). *(Art. 8)*
+- [ ] Tiene **`spec_version`** (`v1` al nacer).
+- [ ] Tiene **autor** identificado.
+- [ ] Sigue el formato canónico (`templates/formato-us.md`).
+
+### Problema validado (Gate 0)
+- [ ] Pasó `grill-intent`: el **problema** fue desafiado y el veredicto es `a-spec`.
+- [ ] Se sabe **quién** siente el dolor (un rol concreto, no "el usuario").
+- [ ] Se sabe el **costo de no hacerlo** (por qué ahora).
+
+### Criterios testeables
+- [ ] Los **criterios de aceptación** están en **Gherkin** (Dado/Cuando/Entonces).
+- [ ] **Cada** criterio puede volverse un **test**. *(Art. 3 — testeable o no existe)*
+- [ ] Ningún criterio menciona tablas, endpoints ni framework (eso es CÓMO).
+
+### Alcance y contexto
+- [ ] Hay **flujos**: happy path + al menos una excepción.
+- [ ] Está explícito el **fuera de scope**.
+- [ ] Las **dependencias** (otras US, sistemas, decisiones) están listadas.
+
+### Tamaño (INVEST)
+- [ ] Es **chica**: entra en un sprint. Si desborda, se **parte** antes de entrar.
+- [ ] Es **independiente**: no depende de otra US a medias.
+
+## Regla de calibración por nivel
+
+- **N1 (dev solo):** el DoR se auto-verifica; el `proposal.md` de OpenSpec hace de US.
+  Igual se exige: criterios testeables + fuera de scope. Lo demás se aligera.
+- **N2 (equipo compacto):** DoR completo, verificado por el que agarra la US.
+- **N3 (federado):** DoR completo + firma del PO + Gate 0 formal registrado.
+
+> El link no se negocia; la ceremonia alrededor sí (Art. 13, Art. 15).

package/templates/epica.md

@@ -0,0 +1,62 @@
+<!--
+  FORMATO DE ÉPICA · dai
+  ─────────────────────────────────────────────────────────────────
+  Una épica es un bloque grande de valor de negocio que se parte en
+  varias User Stories. Es funcional y de alto nivel: define el ALCANCE,
+  no el detalle ni el CÓMO.
+
+  La épica NO se implementa directamente: agrupa. Las US que la componen
+  son las que viajan por el flujo (grill-intent → grill-user-story → ...).
+  El link QUÉ↔CÓMO vive a nivel US, no de épica.
+-->
+
+# 🔗 Metadata
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | `ABC-###` (épica en el gestor) |
+| **Autor** | quién la definió |
+| **Estado** | `abierta` \| `en curso` \| `cerrada` |
+| **US que la componen** | `ABC-###`, `ABC-###` … _(se completa a medida que se parten)_ |
+
+---
+
+# <Título de la épica>
+
+Orientado a la capacidad de negocio grande. Una frase.
+
+## Objetivo de negocio
+
+Qué resultado de negocio persigue esta épica. Por qué importa ahora. 2–4 líneas.
+
+## Alcance
+
+Qué entra y qué **no** entra en esta épica. El límite grueso que después las US
+respetan.
+
+- **Dentro** — <capacidades que sí cubre>
+- **Fuera** — <lo que explícitamente queda para otra épica>
+
+## User Stories (partición)
+
+Lista viva de las US en las que se parte. Cada una es independiente y cabe en un
+sprint (INVEST). No es el detalle: es el índice.
+
+- [ ] `ABC-###` — <título corto de la US>
+- [ ] `ABC-###` — <título corto de la US>
+
+## Métricas de éxito
+
+Cómo sabremos que la épica agregó valor (indicadores de negocio, no de construcción).
+
+- <métrica observable>
+
+## Dependencias y riesgos
+
+- <otra épica / sistema / decisión que tiene que existir antes o en paralelo>
+
+<!--
+  REGLA: si una "US" no cabe en un sprint, probablemente sea una épica y haya que
+  partirla. Si una "épica" no se puede partir en US independientes, probablemente
+  sea una sola US grande. El corte es el sprint.
+-->