ndomo 0.1.0

package/docs/agents.md

@@ -0,0 +1,375 @@
+# Agent Reference
+
+## Overview
+
+ndomo defines 22 agents grouped by function (4 primaries + 18 subagents). All agent definitions live as Markdown files in `agents/` with YAML frontmatter specifying model, temperature, permissions, and mode.
+
+## Primaries
+
+Four primary agents operate independently. The user switches between them manually via TUI.
+
+### foreman
+
+**Planner puro.** Analiza, explora, planifica y persiste planes en DB. No implementa. Solo planifica; la ejecución es del craftsman.
+
+- **Model:** minimax/MiniMax-M3 (default), deepseek-v4-flash (budget)
+- **Temperature:** 0.3
+- **Permissions:** edit (ask), write (ask), bash (ask), question (allow)
+- **Delegates to:** scout, scribe, sage, guild (exploración y análisis únicamente)
+- **File:** `agents/foreman.md`
+
+Flow (4 pasos):
+1. **Aclaración** — identifica intención, pregunta si ambigüo, sugiere craftsman si ≤5 archivos
+2. **Exploración** — memory search + scout/scribe/sage/guild según necesidad
+3. **Plan Atómico** — desglosa en ≤5 steps con archivos esperados y dependencias
+4. **Persistir** — `plan_create` + `task_create_batch` en DB
+
+### craftsman
+
+**Implementador artesano.** Primary agent para bugs, features pequeñas y refactors acotados. Opera en 4 estados según alcance.
+
+- **Model:** opencode-go/deepseek-v4-flash
+- **Temperature:** 0.1
+- **Permissions:** edit (allow), write (allow), bash (ask con permit list), question (allow)
+- **Delegates to:** smiths, painter, chronicler, inspector, scout, scribe (por routing interno)
+- **File:** `agents/craftsman.md`
+
+**Cuándo usar:**
+- **Ad-hoc (cambio directo):** Tareas ≤5 archivos, bien definidas — cambiar a craftsman en TUI sin pasar por foreman
+- **Plan formal:** Foreman creó un plan con tasks asignadas a `craftsman` — craftsman lee `plan_get`/`task_next_for_agent` y ejecuta
+- **Diferencia con foreman:** Foreman planifica (solo DB writes), craftsman implementa (code + DB writes). Foreman NO delega a smiths; craftsman sí.
+
+**Threshold 2/5/1:**
+| Estado | Archivos | Comportamiento |
+|--------|----------|----------------|
+| 1 — Trivial | ≤2 | Implementación directa, sin `plan_db` |
+| 2 — Multi-archivo acotado | 3-5 | Crea `plan_create` + `task_create_batch` propio |
+| 3 — Plan formal | — | Lee plan existente del foreman y ejecuta |
+| 4 — Fuera de dominio | >5 | **Rechaza** — "fuera de mi dominio" → cambiar a foreman |
+
+**Routing interno (por extensión de archivo):**
+| 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` (solo vía craftsman) |
+| Documentación / markdown | `chronicler` |
+| Auditoría / seguridad | `inspector` |
+| Sin match | `smith` (genérico) |
+
+`task.metadata.stack` actúa como override explícito sobre la extensión. Si no hay match, usa `smith`.
+
+**Painter solo craftsman:** El agente UI/UX `painter` solo es invocable desde craftsman, no desde foreman. Craftsman decide: painter si `stack="vue"` y `type="design"`, o vue-smith para implementación lógica.
+
+### warden
+
+**Custodio de operaciones.** Primary agent para CI/CD, deploy, releases, monitoring, secrets, branch strategy y security ops. Opera en paralelo con foreman (planificación) y craftsman (implementación) — su dominio es exclusivamente ops.
+
+- **Model:** opencode-go/deepseek-v4-flash
+- **Temperature:** 0.3
+- **Permissions:** edit (ask), write (ask), bash (ask con read-only allow), webfetch (allow), question (allow), task (allow)
+- **Delegates to:** ci-smith, deploy-smith, release-smith, ops-scout (own fleet), sage, inspector (reused)
+- **File:** `agents/warden.md`
+
+**Cuándo usar:**
+- **Ad-hoc (cambio directo):** Ops simple — cambiar a warden en TUI sin pasar por foreman. Ej: bump version, restart service, audit one-off.
+- **Plan formal:** Warden crea plan con `metadata.category="ops"`, dispatcha via `task_create_batch` con agent="ci-smith"/"deploy-smith"/etc.
+- **Dispatched:** Foreman crea plan code+ops, dispatcha warden para portions ops. Warden hereda `plan_id` via session.
+
+**Regla de oro:** Warden NUNCA dispatcha a craftsman/smith/foreman. Si la tarea es code+ops → pedir al usuario que foreman planifique primero.
+
+### ranger
+
+**Analyst / Cartographer / Onboarding.** Primary agent para análisis profundo, mapeo estructural y context-loading. NO implementa lógica de negocio. NO crea planes — produce filas en tabla `analyses` (linkable a planes via `source_plan_id`).
+
+- **Model:** minimax/MiniMax-M3
+- **Temperature:** 0.3
+- **Permissions:** edit (deny código fuente, allow `docs/analyses/**`), write (ask), bash (ask con read-only allow), webfetch (ask), question (allow), task (scout/sage/scribe)
+- **Delegates to:** scout, sage, scribe (exploración y análisis únicamente)
+- **File:** `agents/ranger.md`
+
+**Cuándo usar:**
+- **Ad-hoc:** Análisis directo sin plan — onboarding de proyecto, auditoría exploratoria, context-loading rápido. Cambiar a ranger en TUI sin pasar por foreman.
+- **Plan-mode (consumidor):** Foreman/craftsman/warden crea plan con task agent="ranger". Ranger hereda plan_id y produce analysis linkeada a `source_plan_id`.
+- **Dispatched:** Analysis standalone consultable por otros primaries via `analysis_get`/`analysis_search`.
+
+**Tres roles híbridos:**
+| Rol | Output típico |
+|---|---|
+| Analyst | Auditoría arquitectura, deuda técnica, security review, performance hotspots — findings con severity + location + recommendation |
+| Cartographer | Dependency graphs, module maps, convention detection, symbol indexes |
+| Onboarding | Stack detection, conventions extraction, entry points, context-load denso para humanos/AI nuevos |
+
+**Routing interno (sub-agentes permitidos):**
+| Sub-agente | Uso |
+|---|---|
+| `scout` | Mapear repo, localizar archivos, dependency graphs |
+| `sage` | Evaluar arquitectura, trade-offs, debugging complejo |
+| `scribe` | Research docs externas, APIs, versiones |
+
+**NO delega a:** smiths, painter, chronicler, inspector, foreman, craftsman, warden, guild.
+
+**Regla de oro:** ranger analiza y mapea. Craftsman implementa. Warden opera. Foreman planifica.
+
+## Explorers
+
+Read-only agents for investigation and research.
+
+### scout
+
+Codebase reconnaissance. Navigates repositories at maximum speed: maps structures, locates symbols, finds patterns, traces dependencies.
+
+- **Model:** opencode-go/minimax-m2.7
+- **Temperature:** 0.3
+- **Permissions:** edit (deny), bash (allow), question (allow)
+- **File:** `agents/scout.md`
+- **Use when:** "find where X is defined", "map the auth flow", "what calls this function"
+
+### scribe
+
+External knowledge retrieval. Searches documentation, APIs, libraries, and web resources. Does not modify code.
+
+- **Model:** opencode-go/minimax-m2.7
+- **Temperature:** 0.3
+- **Permissions:** edit (deny), bash (allow), question (allow)
+- **File:** `agents/scribe.md`
+- **Use when:** "research best practices for X", "find docs for this library", "what version of Y should we use"
+
+## Builders
+
+Write code. Divided into generic smith and stack-specific smiths.
+
+### painter
+
+UI/UX designer. Handles visual composition, component design, and frontend styling. Triggered only when `stack === "vue"` and `type === "design"`.
+
+- **Model:** opencode-go/kimi-k2.6
+- **Temperature:** 0.2
+- **Permissions:** edit (allow), write (allow), bash (allow), question (allow)
+- **File:** `agents/painter.md`
+- **Use when:** "design a login page", "create a dashboard layout", "style this component"
+
+### smith
+
+Generic fast implementation specialist. Stack-agnostic — handles well-defined tasks in any language. Default fallback for unknown stacks.
+
+- **Model:** opencode-go/deepseek-v4-flash
+- **Temperature:** 0.1
+- **Permissions:** edit (allow), write (allow), bash (allow), question (allow)
+- **File:** `agents/smith.md`
+- **Use when:** small fixes, config changes, simple features, mechanical refactors in any language
+
+### go-smith
+
+Go implementation specialist. Idiomatic Go patterns, testing with table-driven tests, concurrency, error handling.
+
+- **Model:** xiaomi/mimo-v2.5-pro
+- **Temperature:** 0.1
+- **Permissions:** edit (allow), write (allow), bash (allow)
+- **File:** `agents/go-smith.md`
+
+### js-smith
+
+JavaScript/TypeScript implementation specialist. Frontend and backend JS/TS, modern patterns, typing.
+
+- **Model:** xiaomi/mimo-v2.5-pro
+- **Temperature:** 0.1
+- **Permissions:** edit (allow), write (allow), bash (allow)
+- **File:** `agents/js-smith.md`
+
+### python-smith
+
+Python implementation specialist. Pythonic idioms, type hints, testing with pytest.
+
+- **Model:** xiaomi/mimo-v2.5-pro
+- **Temperature:** 0.1
+- **Permissions:** edit (allow), write (allow), bash (allow)
+- **File:** `agents/python-smith.md`
+
+### vue-smith
+
+Vue 3 / Pinia implementation specialist. Composition API, `<script setup>`, Vue Router, Pinia stores.
+
+- **Model:** xiaomi/mimo-v2.5-pro
+- **Temperature:** 0.1
+- **Permissions:** edit (allow), write (allow), bash (allow)
+- **File:** `agents/vue-smith.md`
+
+### zig-smith
+
+Zig 0.16 implementation specialist. Systems programming, Zig idioms, memory management.
+
+- **Model:** xiaomi/mimo-v2.5-pro
+- **Temperature:** 0.1
+- **Permissions:** edit (allow), write (allow), bash (allow)
+- **File:** `agents/zig-smith.md`
+
+### rust-smith
+
+Rust implementation specialist. Ownership, lifetimes, traits, async/Tokio, zero-cost abstractions, compile-time SQL checks.
+
+- **Model:** opencode-go/mimo-v2.5-pro
+- **Temperature:** 0.1
+- **Permissions:** edit (allow), write (allow), bash (allow)
+- **File:** `agents/rust-smith.md`
+- **Skills:** `rust-patterns`, `rust-testing`
+
+## Advisors
+
+Provide analysis, guidance, and multi-perspective evaluation. Read-only (edit denied).
+
+### sage
+
+Architecture advisor and high-risk debugger. Deep reasoning for complex problems, trade-off analysis, architecture decisions.
+
+- **Model:** opencode-go/deepseek-v4-pro
+- **Temperature:** 0.2
+- **Permissions:** edit (deny), bash (allow), question (allow)
+- **File:** `agents/sage.md`
+- **Use when:** "review this architecture", "debug this complex issue", "what's the best approach for X"
+- **Manual call:** `sage <question>`
+- **Auto-triggered:** when `type === "debug" && risk === "high"`, or `high risk implement` (as advisory parallel to the stack-smith)
+
+### guild
+
+Multi-LLM consensus and architectural debate. Simulates multiple perspectives to reach consensus on high-risk decisions.
+
+- **Model:** opencode-go/deepseek-v4-pro
+- **Temperature:** 0.3
+- **Permissions:** edit (deny), bash (allow), question (allow)
+- **File:** `agents/guild.md`
+- **Use when:** "should we use X or Y architecture", "is this design safe"
+- **Note:** Manual delegation only — never auto-routed by the scheduler. The foreman only delegates to guild on explicit user request (`type: "debate"`).
+
+## Quality
+
+Review and documentation agents. Invoked after implementation phases.
+
+### inspector
+
+Code quality and security auditor. Reviews diffs for bugs, anti-patterns, security issues, and style violations.
+
+- **Model:** opencode-go/deepseek-v4-pro
+- **Temperature:** 0.2
+- **Permissions:** edit (deny), bash (allow), question (allow)
+- **File:** `agents/inspector.md`
+- **Use when:** "review this diff", "audit this PR", "check for security issues"
+- **Auto-triggered:** craftsman invokes inspector on the resulting diff before closing any task
+
+### chronicler
+
+Technical documentation writer. Analyzes code and generates Markdown documentation. Read-only on existing code; writes documentation files.
+
+- **Model:** opencode-go/deepseek-v4-flash
+- **Temperature:** 0.2
+- **Permissions:** edit (allow), write (allow), bash (deny)
+- **File:** `agents/chronicler.md`
+- **Use when:** "document this API", "generate README", "write migration guide"
+
+## Ops Sub-Agents
+
+Warden delega en 4 sub-agentes especializados en operaciones:
+
+### ci-smith
+
+**CI/CD pipeline specialist.** Crea/modifica GitHub Actions, GitLab CI, CircleCI workflows.
+
+- **Model:** opencode-go/deepseek-v4-flash
+- **Temperature:** 0.5
+- **Permissions:** edit (allow for `.github/workflows/*.yml`), bash (allow for `gh workflow*`)
+- **Delegates to:** none (focused specialist)
+- **File:** `agents/ci-smith.md`
+
+### deploy-smith
+
+**Deployment automation specialist.** Scripts de deploy, Docker, k8s, rollback procedures.
+
+- **Model:** opencode-go/deepseek-v4-flash
+- **Temperature:** 0.5
+- **Permissions:** edit (allow for `scripts/deploy*`, `Dockerfile*`, `k8s/`)
+- **Delegates to:** none
+- **File:** `agents/deploy-smith.md`
+
+### release-smith
+
+**Release management specialist.** Semver, CHANGELOG, GitHub releases, branch strategy enforcement.
+
+- **Model:** opencode-go/deepseek-v4-flash
+- **Temperature:** 0.3
+- **Permissions:** edit (allow for `CHANGELOG.md`, `package.json`)
+- **Delegates to:** none
+- **File:** `agents/release-smith.md`
+
+### ops-scout
+
+**Infrastructure reconnaissance specialist.** Audit de CI/CD/deploy/monitoring/secrets. Read-only.
+
+- **Model:** opencode-go/deepseek-v4-flash
+- **Temperature:** 0.5
+- **Permissions:** edit (deny), write (deny), bash (allow read-only)
+- **Delegates to:** none
+- **File:** `agents/ops-scout.md`
+- **Note:** Cross-primary — único sub-agent dispatchable por warden O foreman.
+
+## Routing Tables
+
+Routing is split across two tiers: foreman (planner) and craftsman (implementer). The old centralized scheduler in `src/orchestrator/scheduler.ts` is deprecated.
+
+### Foreman Routing (planning only)
+
+Foreman delegates exclusively to exploration/analysis agents:
+
+| Petición | Delegar a |
+|----------|-----------|
+| Localizar código / mapear repo / detectar stack | `scout` |
+| Research docs / APIs / libraries / versiones | `scribe` |
+| Arquitectura / debugging difícil / trade-offs | `sage` |
+| Consenso multi-modelo / debate arquitectónico | `guild` (solo manual) |
+
+**NO delegar a:** smiths, painter, chronicler, inspector — esos van al craftsman. **ranger es primary peer** (no sub-agente de foreman) — foreman puede crear planes con `task agent="ranger"` para análisis pre-implement, pero NO lo dispatcha como sub-agente de exploración.
+
+### Craftsman Routing (implementation)
+
+Craftsman selecciona sub-agente por extensión de archivo (`task.files`) con `task.metadata.stack` como override:
+
+| Extensión | 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 / diff review | `inspector` |
+| Sin match | `smith` (genérico) |
+
+Si no hay match por extensión ni stack, usa `smith` como fallback genérico.
+
+### Cross-Primary Routing (ranger)
+
+Ranger es primary peer. Craftsman, foreman y warden pueden **invocar** ranger vía:
+
+| Mecanismo | Uso |
+|---|---|
+| `analysis_*` tools | Consumir analyses existentes (read) — todos los primaries |
+| `task_create_batch` con `agent: "ranger"` | Dispatchar análisis como task en un plan (foreman/craftsman) |
+| `session_start({planId})` (ranger hereda) | Análisis linkeado a plan via `source_plan_id` |
+
+**Cuándo craftsman invoca ranger:**
+- Pre-implement context-loading profundo (antes de refactor multi-archivo)
+- Auditoría de deuda técnica antes de fix
+- Validación de assumptions arquitectónicas
+
+**Cuándo warden invoca ranger:**
+- Auditoría de proyecto pre-CI overhaul
+- Security scan profundo pre-deploy
+
+## Custom Agents
+
+See [configuration.md](configuration.md#custom-agents) for instructions on adding new specialist agents to the routing table.

package/docs/bugs/plan-create-orphan-fk.md

@@ -0,0 +1,131 @@
+# Bug: Plan orphaned in `draft` — `plan_approve` / `plan_update_status` fail with FK session validation
+
+## Resumen
+
+Planes creados mediante `plan_create` no pueden transicionar a `approved` ni a ningún estado terminal porque `plan_approve` y `plan_update_status` validan que `ctx.sessionID` exista en la tabla `sessions` (`src/db/plans.ts:118-121`, `src/db/plans.ts:159-162`). Dicho ID nunca se inserta en `sessions` porque corresponde a la sesión del harness (OpenCode), no a un `session_start` explícito. El plan queda bloqueado permanentemente en `draft`.
+
+## Entorno
+
+| Atributo | Valor |
+|---|---|
+| Sistema | ndomo plugin (OpenCode) |
+| Fecha de detección | 2026-06-19 |
+| Plan afectado | `7e6659fd-1e54-415d-84d5-ca52804145c5` / `test-plan-creation-2026-06-19` |
+| Sesión smoke test | `ses_test_smoke_2026-06-19` |
+| Sesión OpenCode (no insertada) | `ses_11ef21ff8ffeC9CTJhd8nlcgBP` |
+| Estado actual del plan | `draft` (irreversible) |
+
+## Reproducción
+
+1. Crear plan:
+   ```
+   plan_create({slug: "test-plan-creation-2026-06-19", title: "...", overview: "..."})
+   ```
+   → Plan creado en status `draft`.
+
+2. Crear tareas (opcional, no interfiere):
+   ```
+   task_create_batch({planId: "7e6659fd-...", tasks: [...]})
+   ```
+   → `task_create_batch` funciona correctamente (no valida sessionId).
+
+3. Intentar aprobar:
+   ```
+   plan_approve({id: "7e6659fd-1e54-415d-84d5-ca52804145c5"})
+   ```
+   → Error:
+   ```
+   ndomo: session_id does not exist: ses_11ef21ff8ffeC9CTJhd8nlcgBP
+   ```
+
+4. Intentar cerrar (alternativa, mismo error):
+   ```
+   plan_update_status({id: "7e6659fd-...", status: "completed"})
+   ```
+   → Error idéntico:
+   ```
+   ndomo: session_id does not exist: ses_11ef21ff8ffeC9CTJhd8nlcgBP
+   ```
+
+## Comportamiento esperado vs observado
+
+| Operación | Esperado | Observado |
+|---|---|---|
+| `plan_approve` | Plan transiciona a `approved` con `approved_at` seteado | Error `session_id does not exist`; plan permanece `draft` |
+| `plan_update_status` | Plan transiciona a `completed`/`failed`/`abandoned` y se auto-archiva | Error `session_id does not exist`; plan permanece `draft` |
+| Auto-archive en terminal status | Markdown generado en `<project>/.ndomo/archives/plans/` | Nunca se invoca (bloqueado por error previo) |
+
+## Causa raíz
+
+El bug es un side-effect del **Fix #1** (validación FK de `session_id` introducida para integridad referencial entre `plans` y `sessions`). Las tools MCP pasan `ctx.sessionID` (ID de sesión interno del harness OpenCode) como `opts.sessionId` a las funciones de transición:
+
+- `plan_approve` → `src/plugin.ts:649-651`: llama `approvePlan(db, args.id, {sessionId: ctx.sessionID, ...})`.
+- `plan_update_status` → `src/plugin.ts:672-675`: llama `updatePlanStatus(db, args.id, args.status, {sessionId: ctx.sessionID, ...})`.
+
+Ambas funciones en `src/db/plans.ts` ejecutan la validación FK:
+
+- `updatePlanStatus` → `src/db/plans.ts:118-121`: `SELECT 1 FROM sessions WHERE id = ?` — si no existe fila, lanza error.
+- `approvePlan` → `src/db/plans.ts:159-162`: idéntica validación.
+
+La tabla `sessions` solo recibe filas mediante `session_start` explícito (`src/db/sessions.ts:24-38`). El `ctx.sessionID` del harness OpenCode (`ses_11ef21ff8ffeC9CTJhd8nlcgBP`) **nunca es insertado** en `sessions`. Por tanto, cualquier transición de estado que pase `ctx.sessionID` falla.
+
+`plan_create` no se ve afectado porque su implementación no valida `sessionId` contra la tabla (`src/plugin.ts:556-592`). `task_create_batch` tampoco valida — solo pasa `planId`.
+
+## Workarounds
+
+1. **Ninguno desde user-side**: El harness OpenCode no expone control sobre `ctx.sessionID`, por lo que no es posible invocar `session_start` con un ID que coincida antes de `plan_approve`.
+
+2. **SQL directo (acceso a DB)**: Si se tiene acceso al archivo `.ndomo/state.db`, se puede insertar manualmente la fila faltante:
+   ```sql
+    INSERT INTO sessions (id, started_at, last_checkpoint, goal, state, agent_history)
+    VALUES ('ses_11ef21ff8ffeC9CTJhd8nlcgBP', 1729300000000, 1729300000000, 'fix orphan plan FK', '{}', '[]');
+   ```
+   Luego `plan_approve` y `plan_update_status` funcionarán. No es aplicable en producción / entorno multi-agente.
+
+3. **No recomendado**: Deshabilitar la validación FK localmente editando `src/db/plans.ts`. Rompe la integridad referencial y se pierde en el próximo pull.
+
+## Fix propuesto
+
+Tres opciones, ordenadas por impacto/costo descendente:
+
+### a) Auto-insertar fila en `sessions` al primer `plan_create`
+
+Capturar `ctx.sessionID` en `plan_create` e insertar automáticamente un registro en `sessions` si no existe. Zero-touch para el usuario. Garantiza que toda tool posterior que use el mismo `ctx.sessionID` encuentre la fila. Costo: ~5 líneas en `src/plugin.ts:plan_create`.
+
+### b) Relajar validación con upsert automático (lazy)
+
+En `approvePlan` y `updatePlanStatus`, si `opts.sessionId` no existe en `sessions`, hacer un `INSERT OR IGNORE` automático antes de la transición. Similar a (a) pero diferido al momento de la primera transición. Menos intrusivo, pero permite que se cree la fila sin goal ni metadata.
+
+### c) Documentar requisito de `session_start` previo
+
+Exigir que toda transición de plan esté precedida por un `session_start` explícito en el mismo flujo. Workaround oficial pero no práctico para el foreman — añade un paso manual frágil.
+
+**Opción recomendada**: (a) por simplicidad y cobertura total del lifecycle.
+
+## Impacto
+
+- Todo plan creado por el foreman (o cualquier agente) en una sesión de OpenCode sin `session_start` previo queda bloqueado en `draft`.
+- La DB acumula planes `draft` no cerrables que nunca reciben auto-archive.
+- El `plan_update_status` con status terminal (`completed`, `failed`, `abandoned`) nunca se ejecuta, por lo que el auto-archive a markdown (`src/plugin.ts:677-688`) no se dispara.
+- El lifecycle de 10 pasos del foreman (`docs/database.md:202-219`) se rompe en el paso 3 (`plan_approve`).
+- No hay pérdida de datos — los planes existen en DB — pero no se pueden gestionar programáticamente.
+
+## Referencias
+
+- Código tool MCP `plan_approve`: `src/plugin.ts:644-655`
+- Código tool MCP `plan_update_status`: `src/plugin.ts:657-689`
+- Validación FK en `updatePlanStatus`: `src/db/plans.ts:117-121`
+- Validación FK en `approvePlan`: `src/db/plans.ts:158-162`
+- Inserción de sesiones solo vía `session_start`: `src/db/sessions.ts:24-38`
+- Tool MCP `plan_create`: `src/plugin.ts:556-592`
+- Plan afectado: `7e6659fd-1e54-415d-84d5-ca52804145c5` / `test-plan-creation-2026-06-19`
+- Sesión OpenCode no insertada: `ses_11ef21ff8ffeC9CTJhd8nlcgBP`
+- Mensaje original del error: `msg_ee10e0bab001kwzDMkf5gpxY7T`
+
+## Status
+
+| Campo | Valor |
+|---|---|
+| Estado | `Detected` |
+| Workaround | `none user-side` |
+| Fix | `pending` |

package/docs/bugs/task_create_batch-order-index-collision.md

@@ -0,0 +1,158 @@
+# Bug: `task_create_batch` UNIQUE constraint collision on retries/splits
+
+## Resumen
+
+`task_create_batch` falla con `UNIQUE constraint failed: plan_tasks.plan_id, plan_tasks.order_index` cuando el caller invoca la tool 2+ veces para el mismo plan (retry post-abort, dispatch cross-step, o re-creación tras abort). El bug también se manifiesta en splits cross-stack cuando los decimales generados colisionan con order_indices existentes.
+
+## Entorno
+
+| Atributo | Valor |
+|---|---|
+| Sistema | ndomo plugin (OpenCode) |
+| Fecha de detección | 2026-06-22 |
+| Plan de evidencia | `18252705-9c4e-4f5b-85a8-4f7153ceb101` |
+| Plan de fix | `ca69222a-808a-41b0-9dae-05f7641be308` |
+| Sesión de fix | `ses_craftsman_ca69222a` |
+| Archivos afectados | `src/db/tasks.ts`, `tools/task_create_batch.ts`, `src/plugin.ts` |
+
+## Reproducción
+
+1. Crear plan y poblar con 1 task (1ra invocación de `task_create_batch`):
+   ```
+   plan_create({slug: "feat-x", title: "...", overview: "..."})
+   task_create_batch({planId: "...", tasks: [{description: "task 0", agent: "craftsman"}]})
+   ```
+   → Task creada en `order_index=0`. OK.
+
+2. Invocar `task_create_batch` nuevamente para el mismo plan (2da invocación):
+   ```
+   task_create_batch({planId: "...", tasks: [
+     {description: "task A", agent: "craftsman"},
+     {description: "task B", agent: "js-smith"},
+     ...
+   ]})
+   ```
+   → Error:
+   ```
+   UNIQUE constraint failed: plan_tasks.plan_id, plan_tasks.order_index
+   ```
+
+3. El bug también ocurre en splits cross-stack: si un task con files multi-stack genera sub-tasks con `orderIndex = parentOrder + 0.1 * stackIdx`, los decimales pueden colisionar con order_indices existentes.
+
+## Comportamiento esperado vs observado
+
+| Operación | Esperado | Observado |
+|---|---|---|
+| 2da invocación de `task_create_batch` | Nuevas tasks asignadas a order_index secuenciales sin colisión | `UNIQUE constraint failed` — transacción abortada |
+| Split cross-stack con decimales ocupados | Sub-tasks reasignadas a slots libres | `UNIQUE constraint failed` si decimal colisiona |
+| Caller pasa `orderIndex` explícito que colisiona | Core reasigna a slot libre | `UNIQUE constraint failed` |
+
+## Causa raíz
+
+Doble causa: callers + core confiaban en `orderIndex` del caller sin validación contra DB existente.
+
+### Caller: `orderIndex: idx` forzado
+
+Los callers en `tools/task_create_batch.ts:47` y `src/plugin.ts:965` pasaban `orderIndex: idx` desde `array.map((t, idx) => ...)`:
+
+```typescript
+// tools/task_create_batch.ts (ANTES del fix)
+args.tasks.map((t, idx) => ({
+  orderIndex: idx,  // ← solo único intra-batch, no considera tasks existentes
+  ...
+}))
+```
+
+`idx` es 0, 1, 2... dentro del batch, pero no considera tasks ya persistidas en el plan. En la 2da invocación, `idx=0` colisiona con la task existente en `order_index=0`.
+
+### Core: `createTasksBatch` confiaba en caller's `orderIndex`
+
+`src/db/tasks.ts:createTasksBatch` usaba `effectiveTask.orderIndex ?? i` como autoridad directa para el INSERT, sin validar contra `plan_tasks` existentes:
+
+```typescript
+// src/db/tasks.ts (ANTES del fix)
+const orderIndex = effectiveTask.orderIndex ?? i;
+db.query(`INSERT INTO plan_tasks ... VALUES (...)`).run(id, planId, orderIndex, ...);
+```
+
+Sin pre-loop `SELECT MAX(order_index)`, sin set de order_indices usados, sin retry on UNIQUE violation.
+
+### Split cross-stack: decimales sin validación
+
+El split M7 generaba `orderIndex = (t.orderIndex ?? results.length) + stackIdx * 0.1` sin verificar si los decimales ya existían en la DB.
+
+## Workaround histórico
+
+Mientras el fix no estaba aplicado, el foreman usó INSERT directo via `bun:sqlite` con `order_index` explícito pre-calculado desde `MAX+1`:
+
+```typescript
+const db = new Database('.ndomo/state.db');
+const maxRow = db.query("SELECT MAX(order_index) as m FROM plan_tasks WHERE plan_id = ? AND archived_at IS NULL").get(planId);
+let order = (maxRow?.m ?? -1) + 1;
+// for each task: INSERT with order_index=order++ en transacción
+```
+
+4 tasks del plan `ca69222a` fueron creadas via este workaround. Sus metadatos fueron actualizados con `{bugWorkaroundApplied: true, bugSlug: "task_create_batch-order-index-collision", originalInsertMethod: "bun-sqlite3-direct", fixedIn: "ca69222a-..."}`.
+
+## Fix aplicado
+
+**Estrategia**: defense-in-depth en `createTasksBatch` — el core es la autoridad para `order_index`, no el caller.
+
+### Cambios en `src/db/tasks.ts:createTasksBatch`
+
+1. **Pre-loop `SELECT MAX(order_index)`**: calcula `nextFreeInteger` desde el MAX de tasks no-archived.
+2. **`usedOrderIndices` set**: recolecta TODOS los order_indices existentes (incluyendo archived) para collision detection. El `UNIQUE(plan_id, order_index)` no filtra por `archived_at`.
+3. **`allocateOrderIndex(preferred)` helper**: intenta el slot preferido del caller; si está ocupado o undefined, cae a `nextFreeInteger` e incrementa hasta encontrar slot libre.
+4. **`allocateSplitOrderIndex(parentOrder, stackIdx)` helper**: `stackIdx=0` → parentOrder (ya alocado); `stackIdx>0` → `parentOrder + stackIdx * 0.1`; si decimal ocupado → escala a siguiente integer libre.
+5. **Try/catch SQLITE_CONSTRAINT UNIQUE con retry**: defense-in-depth — si una race condition o edge case produce colisión, reasigna y reintenta (hasta 10 intentos).
+6. **Signature change**: `orderIndex` ahora es optional en el input type (`Omit<PlanTask, ... | "orderIndex"> & { orderIndex?: number }`).
+
+### Cambios en callers
+
+- `tools/task_create_batch.ts`: eliminado `orderIndex: idx` del `.map()`.
+- `src/plugin.ts`: eliminado `orderIndex: idx` del `.map()`.
+
+Los callers ahora pasan `orderIndex: undefined` (implícito), y el core aloca dinámicamente.
+
+## Tests de regresión
+
+7 tests añadidos a `src/db/tasks.test.ts`:
+
+| Test | Escenario |
+|---|---|
+| (a) | Plan pre-poblado (task en 0) + nueva task con `orderIndex=0` → reasigna a 1 |
+| (b) | Split cross-stack con plan pre-poblado → parent=1, decimal=1.1 |
+| (c) | Split cross-stack con decimales ocupados (0.1, 0.2) → escala a integers 1, 2 |
+| (d) | Caller pasa `orderIndex` colisionante → core reasigna |
+| (e) | Reproduce bug exacto: 1st batch OK, 2nd batch 4 tasks con `orderIndex` colisionante → todas reasignadas |
+| (f) | Caller omite `orderIndex` → core asigna secuencial desde MAX+1 |
+| (g) | Archived task ocupa slot → nueva task evita colisión |
+
+## Lección replicable
+
+> Any tool que mapea `array → unique-constraint-key` es unsafe para re-invocación sobre mismo parent. Always: lookup current max/sequence BEFORE generating keys, never trust caller-provided sequential indices.
+
+El patrón `array.map((item, idx) => ({ orderIndex: idx, ... }))` es seguro solo intra-batch. Para safety cross-batch, el core debe:
+1. Query DB state antes de generar keys
+2. Tratar caller-provided keys como hints, no como autoridad
+3. Retry on constraint violation con reasignación
+
+## Referencias
+
+- Schema constraint: `src/db/schema.ts:53` — `UNIQUE(plan_id, order_index)`
+- Core fix: `src/db/tasks.ts:createTasksBatch` — pre-loop MAX + allocateOrderIndex + allocateSplitOrderIndex + try/catch retry
+- Caller fix (tools): `tools/task_create_batch.ts:44` — eliminado `orderIndex: idx`
+- Caller fix (plugin): `src/plugin.ts:962` — eliminado `orderIndex: idx`
+- Tests: `src/db/tasks.test.ts` — describe "order_index collision-safe allocation"
+- Plan de fix: `ca69222a-808a-41b0-9dae-05f7641be308`
+- Plan de evidencia: `18252705-9c4e-4f5b-85a8-4f7153ceb101`
+
+## Status
+
+| Campo | Valor |
+|---|---|
+| Estado | `Resolved` |
+| Workaround | `bun:sqlite direct INSERT con order_index manual` (obsoleto post-fix) |
+| Fix | `ca69222a-808a-41b0-9dae-05f7641be308` — applied 2026-06-22 |
+| Tests | 7 regression tests — 49/49 pass (42 existing + 7 new) |
+| Suite | 356/356 pass (full project) |