ndomo 0.1.0

package/docs/features/feature-flexible-builder.md

@@ -0,0 +1,974 @@
+# Feature: Primary Craftsman — refactor arquitectónico (v3)
+
+**Slug:** `feature-flexible-builder`
+**Status:** Implemented (spec v3, post-merge)
+**Plan ID:** `b90682bb-3d75-4a03-8042-8ac350910b53`
+**Plan slug:** `flexible-builder-v3-lows`
+**Created:** 2026-06-20
+**Supersedes:** `docs/features/feature-flexible-builder-v2.md`
+
+---
+
+## Diff vs v2
+
+Novedades incorporadas en esta spec v3 respecto a v2:
+
+- **Nuevo: `task_escalate` MCP tool** — craftsman escala tareas complejas al foreman creando un plan stub con metadata de escalation (`src/plugin.ts:941-963`)
+- **Nuevo: `session_end` reconcile hook** — al marcar sesión como terminada, planes `executing`/`approved` sin cerrar pasan a `abandoned` (`src/plugin.ts:1004-1014`)
+- **Nuevo: Parallel dispatch rule** — threshold >3 archivos o multi-stack o >100 líneas diff → split en sub-tasks paralelos (`agents/craftsman.md:170`)
+- **Nuevo: Parallel retry policy** — retry-1-then-isolate por defecto; ≥2/N fails → fail-fast (`agents/craftsman.md:97-99`)
+- **Nuevo: Trivium craftsman self-edit** — ≤10 líneas, 1 archivo, 0 nuevos exports, 0 behavior changes (`agents/craftsman.md:200-210`)
+- **Nuevo: plan_files multi-role consideration** — PK (plan_id, file_path) impide multi-role por file; pendiente de resolver en Fase 3 (L7) del plan v3
+- **Migración v9 implementada** — `plan_progress` view fix para excluir archived plans (`src/db/schema.ts:507-529`)
+- **Todas las migraciones** v6/v7/v8/v9 marcadas como **IMPLEMENTED**
+- **Write-once enforcement** actualizado de "por convención" a "validado en código + tests"
+- **Árbol de decisión** extendido con rutas `task_escalate` y dispatch paralelo
+- **Sección 7** revisada: v6/v7/v8 IMPLEMENTED, v9 agregado, task_escalate y session_end hook documentados
+
+---
+
+## 1. Resumen ejecutivo
+
+Refactor arquitectónico mayor del ecosistema ndomo. Dos cambios estructurales que transforman el modelo de orquestación:
+
+1. **Foreman simplificado a 4 pasos** (Aclaración → Exploración → Plan atómico → Persistir): se eliminan 6 pasos del flujo original de 10 (Brief de Delegación, Trivium en Vivo, Reconciliación, Validación, Reporte Final). Foreman pasa de orquestador ejecutor a **planner puro**: planifica y persiste en DB; la ejecución la toma otro agente.
+
+2. **Nuevo primary `craftsman`** (antes `builder` en v1): agente implementador disciplinado con threshold estricto 2/5/1. Ataca bugs, features pequeñas y refactors acotados sin pasar por el ciclo de planificación del foreman. Opera con 4 estados de complejidad progresiva.
+
+El user alterna manualmente entre foreman (planificación formal) y craftsman (ejecución directa) mediante el TUI. No hay dispatch automático ni enrutamiento foreman→craftsman — la separación es manual por diseño.
+
+**Decisión clave del grill:** El nombre final es `craftsman` (no `builder`). El threshold es **2/5/1** (no 1/2-5/3 como en v1). El prompt del craftsman incluye 4 estados (no 3). Foreman baja a 4 pasos puramente planificadores.
+
+---
+
+## 2. Contexto y motivación
+
+### 2.1 Problemas del foreman original (10 pasos)
+
+El `foreman` (`agents/foreman.md`) operaba con un flujo de 10 pasos obligatorios que mezclaba planificación con ejecución:
+
+| # | Paso | Problema |
+|---|------|----------|
+| 1 | Aclaración | OK — necesario |
+| 2 | Memory Search | OK — necesario |
+| 3 | Routing | OK — necesario |
+| 4 | Plan Atómico | OK — necesario |
+| 5 | Brief de Delegación | Inflado: el prompt del subagente ya contiene el objetivo |
+| 6 | Trivium en Vivo | Contradictorio: foreman no debe implementar |
+| 7 | Reconciliación | Innecesario si craftsman ejecuta completo |
+| 8 | Validación | Craftsman corre sus propios tests |
+| 9 | Reporte Final | Craftsman reporta en su output |
+
+**Evidencia:** `agents/foreman.md:162-200` — secuencia de 10 pasos que el foreman debía seguir en cada request.
+
+### 2.2 Grietas específicas identificadas
+
+| Grieta | Ubicación en v1 | Impacto |
+|--------|-----------------|---------|
+| Trivium ≤5 líneas, 1 archivo, 0 nuevos exports | `agents/foreman.md:29-34` | Foreman no puede corregir ni un typo sin delegar |
+| No hay modo ad-hoc; toda tarea requiere `plan_create` + `task_create_batch` | `agents/foreman.md:238` | Tareas de 1 archivo requieren ciclo completo de plan_db |
+| `session_start` colisiona con `ctx.sessionID` | `docs/bugs/plan-create-orphan-fk.md:60-70` | `plan_approve`/`plan_update_status` fallan sin `session_start` explícito |
+| `task_update_status` trunca `result`/`error` a 16KB | `src/db/tasks.ts:109-121` | Outputs grandes se pierden sin advertencia |
+| Foreman monopoliza rol de "único primary" | `agents/foreman.md:28` y `agents/*.md` (`mode: subagent`) | User no puede delegar directamente a un smith |
+| Routing estático en scheduler | `src/orchestrator/scheduler.ts:41-47` | No hay detección dinámica de stack |
+| `opencode.json` ausente en el repo | `glob("*opencode.json*")` → 0 resultados | Config global no versionada |
+| Sin asociación plan↔archivos | `src/db/schema.ts` | No hay trazabilidad de qué archivos toca cada plan |
+| Sin `original_plan_data` | `src/db/schema.ts` | No hay audit trail de "qué se planeó vs qué se hizo" |
+| Sin `plan_delete` | `src/plugin.ts` | No hay forma segura de eliminar planes huérfanos |
+
+### 2.3 Diferencias clave entre v1 y v2
+
+| Aspecto | v1 (`builder`) | v2/v3 (`craftsman`) |
+|---------|----------------|---------------------|
+| Nombre | `builder` | `craftsman` (confirmado en grill) |
+| Estados | 3 (trivial, ad-hoc, formal) | 4 (con threshold 2/5/1) |
+| Threshold archivos | 1 / 2-5 / >5 | ≤2 Estado 1, 3-5 Estado 2, >5 Estado 4 |
+| Foreman | Sin cambios (10 pasos) | Simplificado a 4 pasos (planner puro) |
+| Cross-session close | `created_by` básico | `executed_by_agent` + `executed_by_session` + `created_by_agent` |
+| Migraciones DB | v6 + v7 | v6 (original_plan_data) + v7 (plan_files) + v8 (agent/session audit) + v9 (view fix) |
+| Painter routing | Foreman | Solo craftsman |
+| Caveman | 14 agents target | Mismos 14 + snippet estándar |
+| `plan_delete` | Fase 3 | Fase 1 (priorizada) — **IMPLEMENTED** |
+| Plan ≤5 steps | Soft warning | Soft warning + log |
+| `task_escalate` | No existe | MCP tool — **IMPLEMENTED** |
+| `session_end` reconcile | No existe | Hook automático — **IMPLEMENTED** |
+| Parallel dispatch | No existe | Threshold >3 archivos/multi-stack — **IMPLEMENTED** |
+| Trivium self-edit | Solo foreman | Craftsman ≤10 líneas, 1 file, 0 exports — **IMPLEMENTED** |
+
+---
+
+## 3. Análisis comparativo con nicosup98/ndomo
+
+### 3.1 Arquitectura referencia: architect + builder + qagent
+
+El proyecto referencia `nicosup98/ndomo` (opencode-core-slim) define tres modos de trabajo:
+
+| Modo | Agente | Cuándo |
+|------|--------|--------|
+| Plan formal | `architect` (primary) | Tarea multi-archivo, necesita diseño |
+| Ejecución directa | `builder` (primary) | Tarea bien definida, 1-5 archivos |
+| Ad-hoc audit | `qagent` (ad-hoc tool) | Scope se deriva del query |
+
+**Patrón clave:** `architect` NO usa `task` para invocar `builder`. Ambos son primaries que se comunican vía `plan_db` asíncrona. El user cambia de agente manualmente en el TUI.
+
+### 3.2 Tabla comparativa ndomo-v1 vs nicosup98/ndomo vs ndomo-v3
+
+| Aspecto | ndomo-v1 (foreman 10 pasos) | nicosup98/ndomo | ndomo-v3 (craftsman + foreman 4 pasos) |
+|---------|-----------------------------|-----------------|----------------------------------------|
+| Default agent | foreman (primary) | `build` (built-in) | foreman (primary planner) |
+| Implementador | foreman delega a smiths | builder/scout/qagent | **craftsman** (primary implementer) |
+| Modo trivial | Trivium ≤5 líneas + plan_db | `build` single-turn | Craftsman Estado 1 (sin plan_db) |
+| Modo plan formal | foreman → 10 pasos → smiths | architect → plan_db → builder | Foreman 4 pasos → plan_db → craftsman |
+| Coordinación | `task` síncrono | `plan_db` async + TUI switch | `plan_db` async + TUI switch |
+| Audit trail | Solo `created_at`/`updated_at` | `original_plan_data` | `original_plan_data` + agent/session FK |
+| Plan↔file | No existe | `plan_files` | `plan_files` |
+| Tono global | Caveman parcial (foreman + algunos) | Caveman en TODOS | Caveman en TODOS los 14 + craftsman |
+| `plan_delete` | No existe | Rechaza si `status='pending'` | Safety 3-capas — **IMPLEMENTED** |
+| Plan ≤5 steps | No hay regla | Regla en architect.md | Soft warning en task_create_batch |
+| Auto-escalation | No existe | No existe | **`task_escalate`** MCP tool — craftsman→foreman |
+| Session reconcile | No existe | No existe | **`session_end` hook** — abandon planes on session end |
+| Dispatch paralelo | No existe | No existe | **Parallel sub-tasks** >3 files/multi-stack |
+| Self-edit trivium | No existe | No existe | **≤10 lines, 1 file, 0 exports** — craftsman |
+
+### 3.3 Por qué el patrón async + user switch gana
+
+Modelo v1 (foreman 10 pasos):
+1. Foreman crea plan en DB (2 writes)
+2. Foreman crea tasks batch (N writes)
+3. Foreman llama `task` para cada smith (N LLM invocations)
+4. Foreman espera resultados (N context switches)
+5. Foreman reconcilia resultados (N reads)
+
+Modelo v3 (foreman 4 pasos + craftsman):
+1. Foreman crea plan en DB (1-2 writes) — solo si >5 archivos o diseño arquitectura
+2. User cambia a craftsman en TUI (0 LLM tokens)
+3. Craftsman lee plan y ejecuta (1 read + N writes)
+4. Craftsman cierra plan con `plan_update_status("completed")`
+
+**Diferencia clave:** El modelo v3 gasta ~60% menos tokens en coordinación porque el "router" (foreman) solo escribe a DB, no invoca LLMs secundarios. Craftsman opera autónomamente.
+
+---
+
+## 4. Decisiones de diseño
+
+### D1. Nombre `craftsman` (no `builder`)
+
+**Decisión:** El primary implementador se llama `craftsman`, no `builder` como en v1.
+
+**Justificación:** Decisión del grill. `craftsman` evoca artesanía disciplinada (implementación precisa, threshold estricto, 4 estados). `builder` quedó descartado por ambigüedad con "builder pattern" y por la connotación genérica en el referencia.
+
+**Archivo:** `agents/craftsman.md`
+
+### D2. Threshold estricto 2/5/1
+
+**Decisión:** El craftsman opera con threshold numérico estricto:
+
+| Estado | Archivos | Comportamiento |
+|--------|----------|----------------|
+| Estado 1 | ≤2 archivos | Implementación directa, sin plan_db |
+| Estado 2 | 3-5 archivos | Implementación con plan_db (crea plan y tasks) |
+| Estado 3 | — | Lee plan existente del foreman y ejecuta |
+| Estado 4 | >5 archivos | **Rechaza** — "fuera de mi dominio" → cambiar a foreman |
+
+**Diferencia con v1:** v1 proponía 1/2-5 con threshold 1 archivo para Estado 1. v3 sube a ≤2 archivos para Estado 1, reflejando que fixes de 2 archivos son comunes y no requieren plan_db.
+
+**Enforcement:** Solo por prompt (no hay validación en código). Craftsman es un primary agent; su prompt es la única barrera.
+
+### D3. Routing interno: `task.files` extensión + `metadata.stack`
+
+**Decisión:** El craftsman decide a qué sub-agente delegar basándose en (1) extensión de archivo en `task.files`, (2) `task.metadata.stack` si existe, (3) LLM fallback.
+
+| Extensión / Contexto | Sub-agente |
+|----------------------|------------|
+| `.go` | `go-smith` |
+| `.vue`, `.svelte` | `vue-smith` |
+| `.ts`, `.tsx`, `.js`, `.jsx` | `js-smith` |
+| `.py` | `python-smith` |
+| `.rs` | `rust-smith` |
+| `.zig` | `zig-smith` |
+| UI/design + `type=design` | `painter` |
+| Documentación / markdown | `chronicler` |
+| Auditoría / seguridad / diff review | `inspector` |
+| Exploración read-only / mapeo | `scout` |
+| Investigación APIs / docs externas | `scribe` |
+| Sin match | `smith` (genérico stack-agnostic) |
+
+**Archivo:** `agents/craftsman.md` — tabla de routing interno (`agents/craftsman.md:151-164`).
+
+### D4. Painter solo disponible vía craftsman
+
+**Decisión:** `painter` (UI/UX designer) solo es invocable desde craftsman, no desde foreman.
+
+**Justificación:** Foreman es planner puro (4 pasos). Si hay componente UI, craftsman decide: painter si `stack === "vue"` y `type === "design"`, o vue-smith si es implementación lógica.
+
+**Diferencia con v1:** v1 no especificaba painter routing — quedaba como responsabilidad del foreman.
+
+### D5. Cross-session close con audit trail completo
+
+**Decisión:** Tres nuevos campos en tabla `plans`:
+
+| Campo | Tipo | Descripción |
+|-------|------|-------------|
+| `created_by_agent` | TEXT | Agente que creó el plan (`foreman` o `craftsman`) |
+| `executed_by_agent` | TEXT | Agente que ejecutó (`craftsman`, `go-smith`, etc.) |
+| `executed_by_session` | TEXT FK → sessions.id | Sesión en que se ejecutó |
+
+**Justificación:** Permite trazabilidad cross-session: "qué agente creó este plan, qué agente lo ejecutó, en qué sesión". Especialmente útil cuando foreman planifica y craftsman ejecuta en sesiones separadas.
+
+**Comportamiento:**
+- `plan_create` setea `created_by_agent` desde `ctx.agent`
+- `task_update_status` / `plan_update_status` setea `executed_by_agent` y `executed_by_session` al primer `running`
+- Write-once: verificación en código antes de setear
+
+### D6. `plan_delete` en Phase 1 (priorizada) — IMPLEMENTED
+
+**Decisión:** `plan_delete` tool se implementa en Phase 1 (no Phase 3 como en v1).
+
+**Safety checks** (`src/db/plans.ts:312-339`):
+1. `confirm !== true` → error
+2. `plan.status === 'draft'` → error (usar abandonPlan o approve primero)
+3. Existen tasks `pending` o `running` → error
+4. CASCADE: borra plan_tasks, plan_tags, plan_files (sessions → SET NULL)
+
+**Archivo:** `src/plugin.ts:756-766` (tool registration), `src/db/plans.ts:312-339` (core function)
+
+### D7. Plan ≤5 steps: soft warning (no bloqueo)
+
+**Decisión:** `task_create_batch` emite `console.warn` si `tasks.length > 5`. No bloquea. La regla se documenta en el prompt del foreman.
+
+**Justificación:** Bloquear sería contraproducente — el usuario podría tener razón. El warning es suficiente para que el foreman reevalúe.
+
+### D8. Caveman global snippet estándar
+
+**Decisión:** Insertar snippet exacto al inicio del prompt de 14 agents (después del frontmatter, antes del primer heading):
+
+```
+Tono: caveman por default, nivel full. Activa siempre.
+Excepción: prosa normal para advertencias de seguridad,
+acciones irreversibles o ambigüedad multi-paso.
+```
+
+**Agentes:** chronicler, go-smith, guild, inspector, js-smith, painter, python-smith, rust-smith, sage, scout, scribe, smith, vue-smith, zig-smith.
+
+**NO tocar:** `agents/craftsman.md` (ya incluye caveman en su prompt), `agents/foreman.md` (ya tiene caveman).
+
+---
+
+## 5. Diseño del craftsman
+
+### 5.1 Frontmatter YAML (IMPLEMENTED — `agents/craftsman.md:1-42`)
+
+```yaml
+---
+description: Implementador Artesano / Disciplined Craftsman (modo ad-hoc o planificado)
+mode: primary
+model: opencode-go/deepseek-v4-flash
+temperature: 0.1
+permission:
+  edit: allow
+  write: allow
+  bash:
+    "*": ask
+    "git status*": allow
+    "git log*": allow
+    "git diff*": allow
+    "git add *": allow
+    "git commit*": allow
+    "git checkout*": ask
+    "git push*": ask
+    "ls *": allow
+    "cat *": allow
+    "mkdir *": allow
+    "mv *": allow
+    "cp *": allow
+    "bun *": allow
+    "npm *": allow
+    "rm *": ask
+  webfetch: deny
+  question: allow
+  task:
+    "scout": allow
+    "scribe": allow
+    "smith": allow
+    "go-smith": allow
+    "js-smith": allow
+    "vue-smith": allow
+    "python-smith": allow
+    "rust-smith": allow
+    "zig-smith": allow
+    "painter": allow
+    "inspector": allow
+    "chronicler": allow
+  plan_db: allow
+---
+```
+
+**Diferencias con el foreman:**
+- `mode: primary` (NO subagent)
+- `task` permitido a subagents implementadores + painter + chronicler + inspector
+- `task` NO permitido a foreman, guild, sage (son planners/advisors)
+- Permisos `edit: allow`, `bash: ask` (craftsman implementa; foreman solo planifica)
+- `plan_db` tools disponibles pero condicionales (Estado 1 no las usa)
+
+### 5.2 Prompt con 4 estados (IMPLEMENTED)
+
+El prompt completo está en `agents/craftsman.md:44-249`. Resumen de cada estado:
+
+| Estado | Condición | Flujo |
+|--------|-----------|-------|
+| Estado 1: Trivial | ≤2 archivos, ≤50 líneas diff, sin dependencias | Implementa directo, NO plan_db |
+| Estado 2: Multi-archivo | 3-5 archivos, multi-stack, necesita tracking | Crea plan_db propio + tasks |
+| Estado 3: Plan formal | Plan foreman existente con tasks para craftsman | Lee plan_get/task_next, ejecuta TDD |
+| Estado 4: Fuera dominio | >5 archivos o requiere diseño arquitectura | Rechaza, sugiere foreman |
+
+### 5.3 Trivium self-edit (NUEVO en v3)
+
+Cuando craftsman edita código directamente (sin delegar a sub-smith), aplica trivium (`agents/craftsman.md:200-210`):
+
+- **≤10 líneas modificadas** por self-edit individual
+- **1 archivo máximo** por self-edit
+- **0 funciones/exports nuevos**
+- **0 cambios de comportamiento** (typos, renombres mecánicos, imports faltantes)
+- **Verificar post-escritura**: `bun run typecheck` + `bun test` del scope afectado
+
+**Default:** cualquier cambio >10 líneas o >1 archivo → delegar a sub-smith.
+
+### 5.4 Parallel dispatch rule (NUEVO en v3)
+
+Reglas de routing para dispatch paralelo (`agents/craftsman.md:166-171`):
+
+- Si `task.metadata.stack` existe y es explícito → override (no mirar extensión)
+- Si no hay match por extensión ni stack → usar `smith` (genérico)
+- Si la tarea toca **múltiples stacks** → dividir en sub-tasks, una por stack
+- **Tareas grandes → dispatch paralelo**: >3 archivos o multi-stack o >100 líneas diff → dividir en sub-tasks (1 por stack/chunk), dispatchar todas en paralelo vía `task`, esperar a TODAS antes de cerrar el plan
+- NO delegar a: foreman, sage, guild
+
+**Anti-patterns:**
+- ❌ 5 archivos a 1 solo smith
+- ❌ Todo al `smith` genérico
+- ❌ Serial cuando se podría paralelizar
+
+### 5.5 Parallel retry policy (NUEVO en v3)
+
+Política de reintentos para sub-tasks paralelos (`agents/craftsman.md:97-99`):
+
+| Escenario | Comportamiento |
+|-----------|---------------|
+| Default | `retry-1-then-isolate` |
+| 1/N falla | Retry 1 vez; si reintento falla → `task_update_status("failed")` + continue-isolated (resto sigue) |
+| ≥2/N fallan | Fail-fast: cancelar dispatch pendiente, `plan_update_status("failed")` |
+| Timeout >5min | Tratado como failed |
+| Override | `metadata.parallelRetryPolicy: "no-retry" \| "fail-fast" \| "continue-isolated"` |
+
+### 5.6 Cross-session close (IMPLEMENTED)
+
+Al cerrar planes (`agents/craftsman.md:173-180`):
+- `executed_by_agent`: siempre `"craftsman"`
+- `executed_by_session`: siempre `current_session_id` (ctx.sessionID)
+- `created_by_agent`: setear en `plan_create` si craftsman creó el plan (Estado 2)
+- Write-once enforcement: verificación en código antes de setear
+
+### 5.7 Routing extendido (IMPLEMENTED)
+
+Tabla de routing actual (`agents/craftsman.md:151-164`) incluye:
+- go-smith, vue-smith, js-smith, python-smith, rust-smith, zig-smith
+- painter (UI/design), chronicler (docs), inspector (audit), scout (explore), scribe (research)
+- `smith` genérico como fallback
+
+---
+
+## 6. Foreman nuevo flow: 4 pasos (planner puro) — IMPLEMENTED
+
+### 6.1 Comparativa 10 pasos → 4 pasos
+
+| v1 (10 pasos) | v3 (4 pasos) | Diferencia |
+|---------------|--------------|------------|
+| 1. Aclaración | **1. Aclaración** | Se conserva |
+| 2. Memory Search | **2. Exploración** | Se fusiona: memory + scout/scribe/sage/guild |
+| 3. Routing | — | Routing implícito en la exploración |
+| 4. Plan Atómico | **3. Plan Atómico** | Se conserva, más liviano |
+| 5. Brief de Delegación | — | Eliminado: craftsman lee plan_db directamente |
+| 6. Trivium en Vivo | — | Eliminado: craftsman implementa |
+| 7. Reconciliación | — | Eliminado: craftsman ejecuta todo |
+| 8. Validación | — | Eliminado: craftsman corre tests |
+| 9. Reporte Final | — | Eliminado: craftsman reporta |
+| — | **4. Persistir** | Nuevo: plan_create + write plan_db |
+
+**Archivo:** `agents/foreman.md:121-152`
+
+### 6.2 Flujo detallado
+
+#### Paso 1: Aclaración
+- Identificar intención en 1-2 frases
+- Si ambigüedad: `question` al usuario
+- Si la tarea es ≤5 archivos y bien definida → sugerir `craftsman`
+- Si >5 archivos o requiere diseño → continuar con planificación
+
+#### Paso 2: Exploración
+- `memory({mode:"search", scope:"project"})` — decisiones pasadas
+- `memory({mode:"search", scope:"all-projects"})` — conocimiento cross-proyecto
+- Delegar a subagentes según necesidad:
+  - `scout` — mapear repo, encontrar archivos, detectar stack
+  - `scribe` — investigar APIs, versiones, docs externas
+  - `sage` — evaluar trade-offs arquitectónicos, debugging
+  - `guild` — solo si usuario pide debate explícito
+- NO delegar a smiths, painter, chronicler, inspector
+
+#### Paso 3: Plan Atómico
+- Desglosar en ≤5 steps top-level
+- Cada step: `(Acción) → archivos esperados [paths] → dependencias`
+- Estimar complejidad (1-5) y riesgo (low/medium/high)
+
+#### Paso 4: Persistir
+- `plan_create` con slug, overview, approach, priority
+- `task_create_batch` con steps (tasks para craftsman)
+- NO crear `session_start` (lo hace craftsman al ejecutar)
+- NO ejecutar tasks — craftsman las toma via `task_next_for_agent`
+
+### 6.3 Routing table del foreman (`agents/foreman.md:45-56`)
+
+| Petición | Delegar a |
+|----------|-----------|
+| Explorar código / mapear repo | `scout` |
+| Investigar APIs / docs / versiones | `scribe` |
+| Arquitectura / trade-offs / debugging difícil | `sage` |
+| Debate multi-perspectiva | `guild` (solo manual) |
+
+NOTA: foreman solo planifica. Ejecución es craftsman. NO delegar a smiths, painter, chronicler, inspector.
+
+### 6.4 Output del foreman
+
+```
+**Objetivo:** [1 línea]
+**Exploración:** [findings de scout/scribe/sage]
+**Plan:**
+  1. [acción] → archivos: [paths] → complejidad: N
+  2. [acción] → archivos: [paths] → complejidad: N
+**Persistido:** plan_id=[uuid] slug=[slug]
+**Siguiente:** cambiar a craftsman en TUI → task_next_for_agent
+**Estatus:** [Planificado | Bloqueado: <razón> | Craft-sugerido]
+```
+
+### 6.5 Plan Approve (legacy)
+
+`plan_approve` es un tool MCP registrado en `src/plugin.ts` que marca un plan como `approved` seteando `approved_at`.
+
+**Estado:** **LEGACY** — El flujo v3 de foreman (4 pasos) **NO usa `plan_approve`**. Foreman pasa directo de `plan_create` (status `draft`) a `task_create_batch`.
+
+**Archivo:** `src/plugin.ts:621-632` (tool registration original, líneas aproximadas — verificar offset actual)
+
+---
+
+## 7. Cambios al sistema
+
+### 7.1 Migración v6: `original_plan_data` — IMPLEMENTED
+
+| Campo | Tabla | Tipo | Comportamiento |
+|-------|-------|------|----------------|
+| `original_plan_data` | `plans` | `TEXT` | En `plan_create`: copiar snapshot de args como JSON |
+| `original_plan_data` | `plan_tasks` | `TEXT` | En `task_create_batch`: copiar `{description, files, dependencies}` como JSON |
+
+**Reglas:**
+- `plan_create` setea `original_plan_data` al serializar los args de entrada
+- `plan_approve` NO toca `original_plan_data`
+- `plan_update_status` NO toca `original_plan_data`
+- `archivePlan` lo incluye en markdown pero NO lo modifica
+- `task_create_batch` setea `original_plan_data` por task
+
+**Archivos:** `src/db/schema.ts:467-473`, `src/db/types.ts`, `src/db/plan-create.ts`, `src/db/tasks.ts`, `src/db/plan-archive.ts`, `src/db/plans.ts`
+
+**Esquema:** Columnas agregadas vía `addColumnIfMissing()` en migrations.ts (`src/db/schema.ts:472-473`).
+
+### 7.2 Migración v7: `plan_files` — IMPLEMENTED
+
+```sql
+CREATE TABLE IF NOT EXISTS plan_files (
+  plan_id TEXT NOT NULL REFERENCES plans(id) ON DELETE CASCADE,
+  file_path TEXT NOT NULL,
+  role TEXT NOT NULL DEFAULT 'input',
+  PRIMARY KEY (plan_id, file_path)
+);
+CREATE INDEX IF NOT EXISTS idx_plan_files_plan ON plan_files(plan_id);
+```
+
+**Comportamiento:**
+- `plan_create` acepta `files: string[]` opcional → inserta con role `'input'`
+- `task_create_batch` acepta `files: string[]` por task → inserta con role `'modified'`
+- `plan_get` retorna `files[]` via JOIN
+- `plan_search` acepta `file_path` filter opcional
+- `plan_delete` CASCADE borra `plan_files`
+- `archivePlan` incluye files en el markdown archive
+
+**Archivos:** `src/db/schema.ts:480-488`, `src/db/types.ts`, `src/db/plan-create.ts`, `src/db/tasks.ts`, `src/db/plans.ts`, `src/db/plan-archive.ts`
+
+**Tests:** `src/db/plan-files.test.ts`
+
+### 7.3 Migración v8: `created_by_agent` + `executed_by_agent` + `executed_by_session` — IMPLEMENTED
+
+```sql
+ALTER TABLE plans ADD COLUMN created_by_agent TEXT;
+ALTER TABLE plans ADD COLUMN executed_by_agent TEXT;
+ALTER TABLE plans ADD COLUMN executed_by_session TEXT REFERENCES sessions(id) ON DELETE SET NULL;
+```
+
+**Comportamiento:**
+- `plan_create`: setea `created_by_agent = ctx.agent` (write-once)
+- `task_update_status("running")` o `plan_update_status("executing")`: setea `executed_by_agent` y `executed_by_session` si es el primer running
+- `plan_approve` / `plan_update_status("completed")`: NO tocan estos campos
+- `getPlan`: retorna los campos en el objeto Plan
+
+**Archivos:** `src/db/schema.ts:497-498`, `src/db/types.ts`, `src/db/plan-create.ts`, `src/db/plans.ts`, `src/db/plan-archive.ts`
+
+**Tests:** `src/db/migrations-v8.test.ts`
+
+### 7.4 Migración v9: `plan_progress` view fix — IMPLEMENTED
+
+**Problema:** DBs con schema_version ≥5 que ya tenían la view `plan_progress` antes del fix nunca re-ejecutaron v5, manteniendo la view antigua sin filtro `archived_at`.
+
+**Solución:** DROP + CREATE de `plan_progress` view con filtro `WHERE p.archived_at IS NULL` (`src/db/schema.ts:507-529`).
+
+```sql
+DROP VIEW IF EXISTS plan_progress;
+CREATE VIEW plan_progress AS
+SELECT
+  p.id AS plan_id,
+  p.slug, p.title, p.status,
+  COUNT(t.id) AS total_tasks,
+  SUM(CASE WHEN t.status = 'done'     THEN 1 ELSE 0 END) AS done,
+  SUM(CASE WHEN t.status = 'failed'   THEN 1 ELSE 0 END) AS failed,
+  SUM(CASE WHEN t.status = 'running'  THEN 1 ELSE 0 END) AS running,
+  SUM(CASE WHEN t.status = 'pending'  THEN 1 ELSE 0 END) AS pending,
+  SUM(CASE WHEN t.status = 'blocked'  THEN 1 ELSE 0 END) AS blocked,
+  CASE
+    WHEN COUNT(t.id) = 0 THEN 0
+    ELSE ROUND(SUM(CASE WHEN t.status = 'done' THEN 1 ELSE 0 END) * 100.0 / COUNT(t.id))
+  END AS progress_pct
+FROM plans p
+LEFT JOIN plan_tasks t ON t.plan_id = p.id AND t.archived_at IS NULL
+WHERE p.archived_at IS NULL
+GROUP BY p.id;
+```
+
+### 7.5 `plan_delete` safety — IMPLEMENTED
+
+**Tool** en `src/plugin.ts:756-766`.
+
+**Función:** `deletePlan(db, id, confirm)` en `src/db/plans.ts:312-339`.
+
+**Validaciones:**
+1. `typeof confirm !== 'boolean' || confirm !== true` → error `"ndomo: deletePlan requires confirm: true"`
+2. `plan.status === 'draft'` → error `"ndomo: cannot delete a draft plan — use abandonPlan or approve first"`
+3. Existen tasks con `status IN ('pending', 'running')` → error `"ndomo: plan has active tasks — resolve them first"`
+
+**Si pasa:** `DELETE FROM plans WHERE id = ?` (CASCADE: plan_tasks, plan_tags, plan_files; sessions → SET NULL)
+
+**Tests:** `src/db/plans.test.ts:160-234` (4 sub-casos: success, draft rejection, active tasks rejection, missing confirm)
+
+### 7.6 Plan ≤5 steps soft warning — IMPLEMENTED
+
+En `src/db/tasks.ts`, función `createTasksBatch`:
+
+```typescript
+if (tasks.length > 5) {
+  console.warn(`[ndomo] plan ${planId} has ${tasks.length} tasks (>5): consider splitting`);
+}
+```
+
+No bloquea. Warning visible en logs de OpenCode.
+
+### 7.7 Caveman global en 14 agents — IMPLEMENTED
+
+Snippet estándar insertado después del frontmatter YAML en 14 archivos (`agents/chronicler.md:16`, `agents/go-smith.md:32`, `agents/guild.md:28`, `agents/inspector.md:28`, `agents/js-smith.md:32`, `agents/painter.md:32`, `agents/python-smith.md:32`, `agents/rust-smith.md:32`, `agents/sage.md:28`, `agents/scout.md:28`, `agents/scribe.md:28`, `agents/smith.md:32`, `agents/vue-smith.md:32`, `agents/zig-smith.md:32`).
+
+```
+Tono: caveman por default, nivel full. Activa siempre.
+Excepción: prosa normal para advertencias de seguridad,
+acciones irreversibles o ambigüedad multi-paso.
+```
+
+### 7.8 `task_escalate` MCP tool (NUEVO en v3) — IMPLEMENTED
+
+**Tool registration:** `src/plugin.ts:941-963`
+
+```typescript
+task_escalate: tool({
+  description:
+    "Escalar tarea compleja al foreman. Crea un plan stub (foreman) con " +
+    "metadata.escalatedFrom=<planId_or_null> + metadata.escalatedBy='craftsman' " +
+    "y notifica via session_checkpoint. NO ejecuta código.",
+  args: {
+    sourcePlanId: tool.schema.string().optional(),
+    sourceTaskId: tool.schema.string().optional(),
+    reason: tool.schema.string(),
+    suggestedApproach: tool.schema.string().optional(),
+  },
+  execute: async (args, ctx) => {
+    if (!args.reason || args.reason.trim().length === 0) {
+      throw new Error("ndomo: task_escalate requires a non-empty reason");
+    }
+    // ... calls escalateToForeman(db, ctx, escalateArgs)
+  },
+}),
+```
+
+**Core function:** `escalateToForeman()` en `src/plugin.ts:85-149`:
+
+1. Crea plan stub con metadata `{ escalatedFrom, escalatedBy: "craftsman", reason }`
+2. Si `sourceTaskId` existe, crea una task foreman en el plan de escalation
+3. Hace `session_checkpoint` con nota de escalation
+
+**Cuándo craftsman lo usa:** Cuando una tarea excede el dominio del craftsman (Estado 4) o encuentra una dependencia que requiere planificación foreman. Craftsman no invoca `task_escalate` directamente como tool MCP — el prompt del craftsman documenta que debe reportar `[FUERA DE MI DOMINIO]` y sugerir cambiar a foreman. El tool existe para uso programático/automatizado.
+
+### 7.9 `session_end` reconcile hook (NUEVO en v3) — IMPLEMENTED
+
+**Tool registration:** `src/plugin.ts:1004-1014`
+
+```typescript
+session_end: tool({
+  description:
+    "Mark a session as ended. Sets ended_at. Reconciliación: planes con " +
+    "status='executing' o 'approved' sin cerrar en esta session → 'abandoned' " +
+    "con metadata.reason='session_ended'.",
+  // ...
+  execute: async (args, ctx) => {
+    const plansAbandoned = reconcileAbandonedPlans(db, args.id, ctx.agent ?? "unknown");
+    // ... mark session as ended
+  },
+}),
+```
+
+**Core function:** `reconcileAbandonedPlans()` en `src/plugin.ts:160-190`:
+
+- Busca planes con `status IN ('executing', 'approved')` y `session_id = sessionId`
+- Marca cada plan como `abandoned` con `metadata.reason = "session_ended"` + `endedBy`
+- Retorna count de planes reconciliados
+
+**Tests:** `src/plugin.test.ts:146-287` (7 sub-casos)
+
+### 7.10 plan_files multi-role PK consideration (NUEVO en v3) — PENDING
+
+**Problema:** La tabla `plan_files` tiene PK `(plan_id, file_path)` (`src/db/schema.ts:481-486`). Esto impide que un mismo archivo tenga múltiples roles (ej. ser `'input'` Y `'modified'` en el mismo plan). Si craftsman lee un archivo como input y luego lo modifica, el segundo INSERT con mismo `(plan_id, file_path)` pero diferente `role` falla por PK duplication.
+
+**Estado actual:** `role` tiene default `'input'`. `plan_create` inserta con role `'input'`, `task_create_batch` inserta con role `'modified'`. Si el mismo archivo aparece en ambos, el segundo INSERT falla.
+
+**Resolución:** Pendiente — tracking como L7 (Fase 3 del plan v3 `flexible-builder-v3-lows`). Posibles soluciones:
+- Cambiar PK a `(plan_id, file_path, role)` — permite multi-role
+- Usar ON CONFLICT REPLACE — pierde el role original
+- Usar array/tags en `role` en lugar de string único
+
+**Links:** `docs/features/feature-flexible-builder.md` (esta sección), plan v3 Fase 3.
+
+---
+
+## 8. Acceptance criteria
+
+### 8.1 Craftsman existe y es primary — ✅ DONE
+- [x] `agents/craftsman.md` existe con `mode: primary`, frontmatter completo (`agents/craftsman.md:1-42`)
+- [x] Prompt cubre 4 estados con threshold 2/5/1 (`agents/craftsman.md:44-130`)
+- [x] User puede cambiar a craftsman en TUI
+
+### 8.2 Threshold 2/5/1 funcional
+- [x] Estado 1: tarea ≤2 archivos → implementa sin plan_db (prompt line 58)
+- [x] Estado 2: tarea 3-5 archivos → crea plan_db + tasks (prompt line 72)
+- [x] Estado 3: plan existente → ejecuta tasks asignadas (prompt line 103)
+- [x] Estado 4: tarea >5 archivos → reporta fuera de dominio (prompt line 123)
+
+### 8.3 Routing interno del craftsman — ✅ DONE
+- [x] Delegación por extensión: .go → go-smith, .vue → vue-smith, etc. (`agents/craftsman.md:151-164`)
+- [x] `metadata.stack` override funciona (`agents/craftsman.md:167`)
+- [x] LLM fallback a `smith` genérico (`agents/craftsman.md:164`)
+
+### 8.4 Painter solo vía craftsman — ✅ DONE
+- [x] Foreman NO lista painter en su routing (`agents/foreman.md:45-56`)
+- [x] Craftsman puede delegar a painter si `type === "design"` (`agents/craftsman.md:159`)
+- [x] Craftsman usa vue-smith para UI no-design
+
+### 8.5 Cross-session close — ✅ DONE
+- [x] `plan_create` setea `created_by_agent` (write-once)
+- [x] Primer `task_update_status("running")` setea `executed_by_agent` + `executed_by_session`
+- [x] Campos no se sobrescriben en updates posteriores
+
+### 8.6 Migraciones DB — ✅ DONE
+- [x] v6: `original_plan_data` write-once en plans y plan_tasks (`src/db/schema.ts:467-473`)
+- [x] v7: `plan_files` insert + query + CASCADE (`src/db/schema.ts:480-488`)
+- [x] v8: `created_by_agent`, `executed_by_agent`, `executed_by_session` en plans (`src/db/schema.ts:497-498`)
+- [x] v9: `plan_progress` view fix — exclude archived plans (`src/db/schema.ts:507-529`)
+- [x] Migraciones aplican limpias a DB existente
+
+### 8.7 `plan_delete` safety — ✅ DONE
+- [x] Rechaza sin `confirm: true` (`src/db/plans.ts:314-315`)
+- [x] Rechaza si `status='draft'` (`src/db/plans.ts`)
+- [x] Rechaza si hay tasks pending/running (`src/db/plans.ts`)
+- [x] CASCADE ejecuta correctamente
+
+### 8.8 Plan ≤5 steps — ✅ DONE
+- [x] `agents/foreman.md` contiene regla de ≤5 steps (foreman.md:141)
+- [x] `task_create_batch` emite console.warn si >5 tasks
+
+### 8.9 Caveman global — ✅ DONE
+- [x] 14 agents tienen snippet caveman estándar (chronicler, go-smith, guild, inspector, js-smith, painter, python-smith, rust-smith, sage, scout, scribe, smith, vue-smith, zig-smith)
+- [x] Craftsman tiene caveman en prompt (`agents/craftsman.md:247-249`)
+- [x] Foreman ya tenía caveman (no duplicar)
+
+### 8.10 Tests y verificación — ✅ DONE (158 baseline)
+- [x] `plan_delete` tests (4 sub-casos) (`src/db/plans.test.ts:160-234`)
+- [x] `original_plan_data` write-once test
+- [x] `plan_files` insert + query + CASCADE test (`src/db/plan-files.test.ts`)
+- [x] Audit trail write-once test (v8) (`src/db/migrations-v8.test.ts`)
+- [x] `task_escalate` tests (M2) (`src/plugin.test.ts:26-152`)
+- [x] `session_end` reconcile tests (M3) (`src/plugin.test.ts:146-287`)
+- [x] `bun run typecheck` pasa sin errores
+- [x] `bun test` pasa (158 tests baseline)
+
+### 8.11 Docs
+- [x] `docs/agents.md` tiene sección craftsman (rol, cuándo usar, threshold 2/5/1)
+- [x] `docs/workflows.md` árbol de decisión actualizado
+
+### 8.12 `task_escalate` — ✅ DONE
+- [x] MCP tool registrado en `src/plugin.ts:941-963`
+- [x] Core function `escalateToForeman()` en `src/plugin.ts:85-149`
+- [x] Crea plan stub con metadata de escalation
+- [x] Session checkpoint con nota de escalation
+- [x] Tests en `src/plugin.test.ts`
+
+### 8.13 `session_end` reconcile — ✅ DONE
+- [x] MCP tool registrado en `src/plugin.ts:1004-1014`
+- [x] Core function `reconcileAbandonedPlans()` en `src/plugin.ts:160-190`
+- [x] Abandona planes `executing`/`approved` al terminar sesión
+- [x] Tests en `src/plugin.test.ts`
+
+### 8.14 Parallel dispatch rule — ✅ DONE
+- [x] Documentado en `agents/craftsman.md:170`
+- [x] Threshold >3 archivos o multi-stack o >100 líneas diff → split + parallel
+- [x] Anti-patterns listados
+
+### 8.15 Parallel retry policy — ✅ DONE
+- [x] Documentado en `agents/craftsman.md:97-99`
+- [x] Default: retry-1-then-isolate
+- [x] ≥2/N fails → fail-fast
+- [x] Timeout >5min → failed
+- [x] Override via `metadata.parallelRetryPolicy`
+
+### 8.16 Trivium craftsman self-edit — ✅ DONE
+- [x] Documentado en `agents/craftsman.md:200-210`
+- [x] ≤10 líneas modificadas por self-edit
+- [x] 1 archivo máximo
+- [x] 0 funciones/exports nuevos
+- [x] 0 cambios de comportamiento
+- [x] Verificación post-escritura: typecheck + test
+- [x] Default: >10 líneas o >1 archivo → delegar a sub-smith
+
+### 8.17 plan_files multi-role — ⏳ PENDING (L7, Fase 3 v3 plan)
+- [ ] PK `(plan_id, file_path)` impide multi-role por file
+- [ ] Resolución pendiente en Fase 3 de `flexible-builder-v3-lows`
+
+---
+
+## 9. Plan de implementación (histórico)
+
+El plan original de 5 fases fue ejecutado en el plan v2 y completado. Este spec v3 documenta el estado post-merge.
+
+### Fase 0: Spec v2 + backup v1 — ✅ COMPLETED
+
+### Fase 1: Migraciones DB + tests — ✅ COMPLETED
+- v6, v7, v8, v9 migrations — ALL IMPLEMENTED
+- `deletePlan` con safety checks — IMPLEMENTED
+- Tests para delete, plan-files, migrations-v8 — ALL PASSING
+
+### Fase 2: `agents/craftsman.md` — ✅ COMPLETED
+- 249 lines, frontmatter + prompt 4 estados + routing extendido + trivium self-edit + parallel dispatch + retry policy
+
+### Fase 3: Foreman rewrite + caveman global — ✅ COMPLETED
+- `agents/foreman.md` rewrite a 4 pasos (286 lines)
+- Caveman snippet en 14 agents
+- `plan_delete` en `src/plugin.ts`
+- Soft warning ≤5 tasks en `src/db/tasks.ts`
+
+### Fase 4: Docs + smoke tests — ✅ COMPLETED
+- `docs/agents.md` actualizado con craftsman
+- `docs/workflows.md` árbol de decisión actualizado
+- 158 tests baseline, typecheck + test verdes
+
+---
+
+## 10. Riesgos y trade-offs
+
+### R1. Abuso del craftsman para tareas grandes
+
+**Riesgo:** Craftsman tiene `edit: allow` + `task: allow`. El user podría usarlo para features >5 archivos, saltándose el foreman.
+
+**Mitigación (2 capas):**
+1. **Prompt:** Estado 4 rechaza explícitamente >5 archivos
+2. **Modelo:** craftsman usa temperatura 0.1, menos propenso a auto-expandir scope
+
+**Severidad:** baja (el sistema es una herramienta, no un guardián).
+
+### R2. Separación manual foreman→craftsman confusa
+
+**Riesgo:** El user no sabe cuándo usar foreman vs craftsman, resultando en planes mal diseñados o implementaciones sin plan.
+
+**Mitigación:**
+1. Foreman en el Paso 1 (Aclaración) sugiere craftsman si la tarea es ≤5 archivos
+2. Craftsman en Estado 4 sugiere foreman si >5 archivos
+3. `docs/workflows.md` documenta árbol de decisión
+
+**Severidad:** media (curva de aprendizaje inicial).
+
+### R3. Crecimiento de DB con `original_plan_data`
+
+**Riesgo:** Duplica `plan_data` (2x por fila). En proyectos grandes, puede sumar MB.
+
+**Mitigación:**
+1. Auto-archive a markdown cuando el plan se completa
+2. Archivar setea `archived_at`, limpiando de DB activa
+
+**Severidad:** baja (SQLite, 1000 planes ≈ 2-5MB extra).
+
+### R4. Write-once enforcement en código + tests
+
+**Riesgo original v2:** Los campos write-once eran solo por convención, no por constraint DB.
+
+**Mitigación v3 (implementada):**
+1. El código en `planCreateExecutor`, `createPlan`, `updatePlanStatus` verifica antes de setear
+2. Tests unitarios validan write-once behavior (`src/db/migrations-v8.test.ts`)
+3. Migración v8 ejecuta `addColumnIfMissing` — idempotente
+
+**Severidad:** baja (validado en código y tests).
+
+### R5. Caveman en 14 agents = 14 lugares de mantenimiento
+
+**Riesgo:** El snippet caveman puede volverse inconsistente si se edita en un agent y no en los otros.
+
+**Mitigación:**
+1. Snippet exacto documentado en spec (sección 7.7)
+2. Si cambia, buscar/replace en 14 archivos
+
+**Severidad:** baja (diff mecánico).
+
+### R6. Foreman sin acceso a smiths — posible fricción
+
+**Riesgo:** Si el user pide al foreman "implementa X en Go" y el foreman no puede delegar a go-smith directamente, el user debe cambiar manualmente a craftsman.
+
+**Mitigación:**
+1. Foreman en Paso 1 sugiere craftsman temprano
+2. Foreman puede planificar y craftsman ejecuta — el user cambia una vez
+
+**Severidad:** media-baja (un switch manual adicional vs delegación automática).
+
+### R7. `task_escalate` sin uso directo en prompt
+
+**Riesgo:** El tool `task_escalate` existe como MCP tool pero el prompt del craftsman no lo invoca — en su lugar craftsman reporta `[FUERA DE MI DOMINIO]` y sugiere cambio manual a foreman.
+
+**Impacto:** El tool está disponible para uso programático/automatizado pero no forma parte del flujo normal craftsman→foreman. Si en el futuro se quiere escalation automática, el prompt del craftsman debe actualizarse para usar `task_escalate`.
+
+**Severidad:** baja (el tool funciona; falta integración en el prompt).
+
+---
+
+## 11. Referencias cruzadas
+
+### 11.1 Archivos clave
+
+| Archivo | Líneas relevantes | Estado |
+|---------|-------------------|--------|
+| `agents/foreman.md` | 1-286 (completo) | **IMPLEMENTED** — 4 pasos planner puro |
+| `agents/craftsman.md` | 1-249 (completo) | **IMPLEMENTED** — 4 estados + routing + trivium |
+| `src/db/schema.ts` | 467-583 (MIGRATIONS v6-v9) | **IMPLEMENTED** |
+| `src/db/types.ts` | Plan, PlanTask, PlanRow, TaskRow | **IMPLEMENTED** — extended con nuevos campos |
+| `src/db/plans.ts` | createPlan, updatePlanStatus, deletePlan | **IMPLEMENTED** |
+| `src/db/tasks.ts` | createTasksBatch, truncation 16KB | **IMPLEMENTED** — warning ≤5 tasks |
+| `src/db/plan-create.ts` | planCreateExecutor, ensureSession | **IMPLEMENTED** |
+| `src/db/plan-archive.ts` | serializePlanToMarkdown, archivePlan | **IMPLEMENTED** |
+| `src/db/migrations.ts` | addColumnIfMissing, runMigrations | **IMPLEMENTED** |
+| `src/plugin.ts` | 85-149 (escalateToForeman), 160-190 (reconcile), 756-766 (plan_delete), 941-963 (task_escalate), 1004-1014 (session_end) | **IMPLEMENTED** |
+| `src/db/plans.test.ts` | 160-234 (deletePlan tests) | **IMPLEMENTED** |
+| `src/db/plan-files.test.ts` | completo | **IMPLEMENTED** |
+| `src/db/migrations-v8.test.ts` | completo | **IMPLEMENTED** |
+| `src/plugin.test.ts` | 26-152 (escalateToForeman M2), 146-287 (reconcile M3) | **IMPLEMENTED** |
+| `docs/bugs/plan-create-orphan-fk.md` | 60-70, 88-103 | Bug conocido, no resuelto |
+
+### 11.2 Specs relacionados
+
+| Recurso | Relación |
+|---------|----------|
+| `docs/features/feature-flexible-builder-v1.md` | Spec original v1 (archivada). Define `builder` con 3 estados. |
+| `docs/features/feature-flexible-builder-v2.md` | Spec v2 (archivada). Define `craftsman` + foreman 4 pasos + migraciones v6/v7/v8. |
+| `agents/foreman.md` | Prompt actual del foreman (4 pasos planner puro). |
+| `agents/craftsman.md` | Prompt actual del craftsman (4 estados + routing + trivium). |
+| `docs/agents.md` | Documentación de agents con sección craftsman. |
+| `docs/workflows.md` | Árbol de decisión actualizado. |
+| `src/db/schema.ts` | Schema DB con migraciones v1-v9. |
+
+### 11.3 Árbol de decisión extendido (v3)
+
+```
+User envía prompt
+  │
+  ├─ ¿Tarea ≤2 archivos, ≤50 líneas, bien definida, sin dependencias externas?
+  │   → `craftsman` en TUI → Estado 1 (trivial, sin plan_db)
+  │   └─ Self-edit? ≤10 líneas, 1 file, 0 exports → directo
+  │   └─ >10 líneas o >1 file → delegar a sub-smith
+  │
+  ├─ ¿Tarea 3-5 archivos, multi-stack, necesita tracking?
+  │   → `craftsman` en TUI → Estado 2 (ad-hoc con plan_db)
+  │   └─ ¿>3 archivos o multi-stack o >100 líneas diff?
+  │       → Parallel dispatch: split en sub-tasks (1/stack), dispatch all
+  │       └─ 1/N fails → retry-1-then-isolate
+  │       └─ ≥2/N fails → fail-fast
+  │
+  ├─ ¿Tarea >5 archivos, diseño de arquitectura, o ambigua?
+  │   → `foreman` en TUI → 4 pasos: Aclaración → Exploración → Plan → Persistir
+  │   → Luego `craftsman` en TUI → Estado 3 (lee plan formal)
+  │   └─ Craftsman encuentra algo fuera de dominio?
+  │       → `task_escalate` (programático) o reportar [FUERA DE MI DOMINIO]
+  │
+  ├─ ¿Auditoría de PR existente o tarea read-only?
+  │   → `craftsman` o `scout` según necesite escribir
+  │
+  ├─ ¿Exploración read-only?
+  │   → `scout` en TUI
+  │
+  └─ ¿Terminar sesión regularmente?
+      → `session_end` → reconcile hook → planes ejecutando → abandoned
+```
+
+---
+
+## Apéndice A: Decisiones del grill
+
+| Decisión | Opción elegida | Alternativas descartadas |
+|----------|---------------|--------------------------|
+| Nombre del primary | `craftsman` | `builder` (v1), `implementer`, `artisan` |
+| Threshold | 2/5/1 (≤2 Estado 1, 3-5 Estado 2, >5 Estado 4) | 1/2-5 (v1), 1/3-5/6+ |
+| Estados del craftsman | 4 (trivial / multi-archivo / plan formal / fuera dominio) | 3 (v1) |
+| Foreman pasos | 4 (Aclaración / Exploración / Plan / Persistir) | 10 (v1), 6, 3 |
+| Painter routing | Solo craftsman | Foreman + craftsman |
+| Cross-session close | `created_by_agent` + `executed_by_agent` + `executed_by_session` | Solo `created_by` |
+| `plan_delete` fase | Phase 1 (priorizada) | Phase 3 (v1) |
+| Plan ≤5 steps | Soft warning (no bloqueo) | Bloqueo estricto |
+| Caveman snippet | Estándar en 14 agents | Caveman solo en prompt |
+
+---
+
+## Apéndice B: Relación con bugs existentes
+
+### Bug `ctx.sessionID` (`docs/bugs/plan-create-orphan-fk.md`)
+
+No se resuelve en este spec. Craftsman usa `plan_create` + `plan_update_status("completed")`:
+- `planCreateExecutor` ya tiene `ensureSession` automático (`src/db/plan-create.ts:39-41`)
+- `planUpdateStatus` solo chequea FK para status `executing`/`approved` (`src/db/plans.ts:122`)
+- Craftsman no usa `plan_approve`
+
+**Impacto:** El bug no afecta al flujo craftsman.
+
+### Truncation 16KB (`src/db/tasks.ts:109-121`)
+
+No se resuelve en este spec. Craftsman genera resultados pequeños (formato caveman). Si un sub-smith produce output grande, el truncation aplica igual que hoy.
+
+### plan_files multi-role PK (`src/db/schema.ts:481-486`)
+
+**Estado:** ⏳ PENDING — PK `(plan_id, file_path)` impide que un archivo tenga roles múltiples (`'input'` + `'modified'`). Resolución programada para Fase 3 (L7) del plan `flexible-builder-v3-lows`.
+
+---
+
+*Fin del feature spec v3 — documenta el estado post-merge del refactor Primary Craftsman*