[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7569JSFFT8456T7KTSN7T82":3,"skill-same:01M7569JSFFT8456T7KTSN7T82":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M7569JSFFT8456T7KTSN7T82","sdd-data-schemas",null,"Referencia canónica de todos los schemas de datos del sistema SDD. Cubre campo por campo cada archivo JSON del registro SDD, valores de status, convenciones de IDs, reglas de actualización y anti-patrones frecuentes. LECTURA OBLIGATORIA para cualquier agente que cree o modifique documentos SDD (api.json, schema.json, components.json, tasks.json, fixes.json, global.json, specs\u002Findex.json, cycle.json).","e-burgos\u002Fsdd-harness","e-burgos","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F71472902?v=4","01M728XDZXTGQMP76CXHXWT7B6","EstebanBurgos","01M7566FK459ADH43W2FWZZPNF",0,"MIT","https:\u002F\u002Fgithub.com\u002Fe-burgos\u002Fsdd-harness\u002Fblob\u002Fmain\u002Fsdd\u002Fskills\u002Fsdd-data-schemas\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: sdd-data-schemas\ndescription: >\n  Referencia canónica de todos los schemas de datos del sistema SDD.\n  Cubre campo por campo cada archivo JSON del registro SDD, valores de status,\n  convenciones de IDs, reglas de actualización y anti-patrones frecuentes.\n  LECTURA OBLIGATORIA para cualquier agente que cree o modifique documentos SDD\n  (api.json, schema.json, components.json, tasks.json, fixes.json, global.json,\n  specs\u002Findex.json, cycle.json).\n---\n\n# Skill: sdd-data-schemas\n\n> ⛔ **LECTURA OBLIGATORIA** para cualquier agente que escriba en un registro SDD.\n> Este skill cubre el **contenido** de los archivos. Para rutas y naming ver `sdd-file-structure`.\n\n> 🤖 **Fuente de verdad de máquina:** cada registro tiene un JSON Schema estricto en `sdd\u002Fschemas\u002F*.schema.json`\n> (`additionalProperties: false`) y declara `$schema`. Si este documento y el schema difieren, **gana el schema**.\n> Después de escribir cualquier registro: `pnpm sdd:validate`. Si tocaste tasks: `pnpm sdd:rebuild-tasks-index`.\n\n---\n\n## 0. Reglas globales antes de leer cualquier schema\n\n| Regla                        | Descripción                                                                                                                         |\n| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |\n| **Propiedades en inglés**    | Todos los campos JSON usan inglés. `start_date` ✅ `fecha_inicio` ❌                                                                |\n| **Nunca borrar entradas**    | Los registros son append-only o deprecate-only. Jamás eliminar un entry.                                                            |\n| **`updated_in_cycle: null`** | Se inicializa `null`. Solo cambia cuando hay una modificación posterior al ciclo de creación.                                       |\n| **`changelog: []`**          | Siempre empieza vacío. Se appends en cada actualización.                                                                            |\n| **Agrupación por app-key**   | `api.json`, `schema.json` y `components.json` tienen estructura `{ \"[app-key]\": { ... } }`. Nunca escribir en la raíz directamente. |\n\n### App-keys válidos\n\n| App-key              | Descripción                             |\n| -------------------- | --------------------------------------- |\n| `\"example-api\"`      | Spring Boot API (apps\u002Fexample-api)      |\n| `\"another-api\"`      | Otra API backend (apps\u002Fanother-api)     |\n| `\"apps\u002Fexample-app\"` | React app (apps\u002Fexample-app)            |\n| `\"libs\u002Fapi-client\"`  | Librería compartida (libs\u002Fapi-client)   |\n| `\"apps\u002Fexample-api\"` | Spring Boot template (apps\u002Fexample-api) |\n\n> Agregar nuevas apps\u002Flibs según `monorepo.apps` y `monorepo.libs` de `sdd\u002Fglobal.json`.\n> Ambos son mapas `nombre -> descripción`; el visor de `pnpm sdd:docs` descubre el contexto de\n> cada subproyecto a partir de ellos, así que una lib ausente del mapa no aparece listada.\n\n---\n\n## 1. `sdd\u002Fspecs\u002Findex.json` — Registro de specs\n\n**Responsable:** quien crea la spec (append-only, nunca editar entradas existentes).\n\n### SpecEntry — campos\n\n```json\n{\n  \"id\": \"spec-[gh-user]-[NNN]-[slug]\",\n  \"author\": \"[gh-user]\",\n  \"slug\": \"[slug]\",\n  \"folder\": \"sdd\u002Fspecs\u002Fspec-[gh-user]-[NNN]-[slug]\",\n  \"file\": \"sdd\u002Fspecs\u002Fspec-[gh-user]-[NNN]-[slug]\u002Fspec-[gh-user]-[NNN]-[slug].spec.md\",\n  \"module\": \"[nombre-módulo]\",\n  \"app\": \"apps\u002F[nombre-app]\",\n  \"status\": \"draft | in-progress | completed | cancelled\",\n  \"title\": \"Título legible (máx 80 chars)\",\n  \"created_at\": \"YYYY-MM-DD\",\n  \"completed_at\": \"YYYY-MM-DD | null\",\n  \"depends_on\": [\"spec-[gh-user]-[NNN]-[slug]\"]\n}\n```\n\n### Reglas de SpecEntry\n\n- `id` = nombre exacto de la carpeta bajo `sdd\u002Fspecs\u002F`\n- `[NNN]` = contador **personal del dev** (001, 002…). No global.\n- `depends_on` = array vacío `[]` si no hay dependencias\n- `status` nace `\"draft\"` (spec escrita o en escritura, sin ciclo abierto — desde v0.11.0;\n  `harness add spec` la crea así y registra el módulo en `pending_modules` de `sdd\u002Fglobal.json`).\n  El sdd-orchestrator la pasa a `\"in-progress\"` al crear `cycle-01` de esa spec. Índices previos\n  a v0.11.0 tienen `\"in-progress\"` para specs sin ciclo — el validador sugiere la migración, nunca reescribe datos.\n- `completed_at` = `null` mientras `status` es `draft` o `in-progress`\n- **Registrar ANTES de crear los archivos del ciclo**\n\n---\n\n## 2. `sdd\u002Fglobal.json` — Estado general del monorepo\n\n**Responsable:** sdd-orchestrator (al iniciar ciclo) + sdd-reviewer (al cerrar ciclo).\n\n### Estructura top-level\n\n```json\n{\n  \"$schema\": \".\u002Fschemas\u002Fglobal.schema.json\",\n  \"project\": \"[nombre-del-proyecto]\",\n  \"description\": \"...\",\n  \"version\": \"1.0.0\",\n  \"profile\": \"team\",\n  \"completed_modules\": [],\n  \"in_progress_modules\": [],\n  \"pending_modules\": [],\n  \"monorepo\": {\n    \"tool\": \"Nx\",\n    \"package_manager\": \"pnpm\",\n    \"apps\": {},\n    \"libs\": {}\n  }\n}\n```\n\n> ⚠️ Ya **no existe `current_cycle` global** — la numeración de ciclos es per-spec (`cycles\u002Fcycle-XX`).\n\n- `profile` (opcional, desde v0.13.0): `\"team\"` (default si falta) abre ciclos `flow: \"full\"`;\n  `\"solo\"` abre `flow: \"lite\"` (un solo actor, `plan.md`). Lo cambia el **sdd-steward** a pedido\n  del dev; el prefijo `[LITE]`\u002F`[FULL]` del pedido gana sobre el perfil. Detalle:\n  `sdd\u002Fdual-harness\u002Frules\u002Fsdd-gates.md` § Flow.\n- `github` (opcional, desde v0.20.0): `branch_per_cycle` (`\"on\"` | `\"off\"`; si falta, `team` ⇒ on y\n  `solo` ⇒ off) y `default_branch` (base de los PRs de ciclo, default `main`). Lo leen\n  `pnpm sdd:branch` y `pnpm sdd:pr`; ver `sdd-gates.md` § Ramas y PRs por ciclo.\n\n### ModuleEntry — campos\n\n```json\n{\n  \"module\": \"[nombre-módulo]\",\n  \"spec\": \"spec-[gh-user]-[NNN]-[slug]\",\n  \"apps\": [\"apps\u002F[nombre-app]\"],\n  \"cycles_completed\": 1,\n  \"completed_at\": \"YYYY-MM-DD\",\n  \"description\": \"Qué hace este módulo (1-2 oraciones)\"\n}\n```\n\n- `apps` es **siempre array** (aunque el módulo toque una sola app).\n- `cycles_completed` = cantidad de ciclos de ESA spec con `status: \"completed\"`.\n- `completed_at` y `description` son obligatorios solo en `completed_modules`.\n\n### Ciclo de vida de un módulo en global.json\n\n```\npending_modules → in_progress_modules → completed_modules\n```\n\n| Evento                 | Quién            | Acción                                                  |\n| ---------------------- | ---------------- | ------------------------------------------------------- |\n| Se planifica el módulo | sdd-orchestrator | Agregar a `pending_modules`                             |\n| Se inicia el ciclo     | sdd-orchestrator | Mover de `pending` a `in_progress`                      |\n| Se cierra el ciclo     | sdd-reviewer     | Mover de `in_progress` a `completed` con `completed_at` |\n\n> ⛔ Regla de concurrencia: **un ciclo activo por spec**. Varios devs pueden tener módulos\n> en `in_progress_modules` a la vez (modelo multi-developer), pero una misma spec nunca\n> tiene dos ciclos abiertos. Varias specs sí pueden estar en curso a la vez, cada una atada a su\n> sesión (`pnpm sdd:use`, ver `sdd\u002Fdual-harness\u002Frules\u002Fsdd-gates.md` § Sesiones paralelas).\n\n> **`sdd\u002Fschemas\u002Fsession-binding.schema.json`** — atadura de una sesión a una unidad (ciclo o\n> fix). Es un archivo **local** (`\u003Cgit-common-dir>\u002Fsdd-sessions\u002Fsessions\u002F\u003Csession-id>.json`), no\n> vive en `sdd\u002F` ni en git, y `pnpm sdd:validate` no lo valida: lo escriben el mod de Claude Code\n> y el puente de Studio. No se edita a mano.\n\n> **`sdd\u002Fschemas\u002Ffile-lease.schema.json`** y **`session-request.schema.json`** — reserva de un\n> archivo de código por una sesión (`\u003Cgit-common-dir>\u002Fsdd-sessions\u002Flocks\u002F\u003Cclave>.json`) y mensaje\n> del buzón entre sesiones (`inbox\u002F\u003Csession-id>\u002F\u003Cid>.json`). También locales y fuera de\n> `sdd:validate`; los escriben el mod, el puente y `pnpm sdd:release`. No se editan a mano.\n\n---\n\n## 3. `sdd\u002Fapi.json` — Registro de endpoints\n\n**Responsable:** sdd-architect (status: `defined`) → sdd-implementor-back (status: `implemented`) → sdd-reviewer.\n\n### Estructura\n\n```json\n{\n  \"_comment\": \"...\",\n  \"_schema\": { ... },\n  \"[app-key]\": {\n    \"endpoints\": [ EndpointEntry ]\n  }\n}\n```\n\n### EndpointEntry — campos\n\n```json\n{\n  \"id\": \"EP-[NNN]\",\n  \"method\": \"GET | POST | PUT | PATCH | DELETE\",\n  \"path\": \"\u002Fruta\u002Fdel\u002Fendpoint\u002F{param}\",\n  \"module\": \"[nombre-módulo]\",\n  \"spec\": \"sdd\u002Fspecs\u002Fspec-[gh-user]-[NNN]-[slug]\",\n  \"status\": \"defined | implemented | updated | deprecated\",\n  \"created_in_cycle\": 1,\n  \"updated_in_cycle\": null,\n  \"description\": \"Qué hace el endpoint\",\n  \"path_params\": [\"param1\"],\n  \"required_headers\": [\"Authorization\", \"Content-Type\"],\n  \"request_body\": {},\n  \"responses\": {\n    \"200\": \"descripción de la respuesta OK\",\n    \"400\": \"descripción del error\"\n  },\n  \"changelog\": []\n}\n```\n\n### Reglas de EndpointEntry\n\n| Campo              | Regla                                                                                  |\n| ------------------ | -------------------------------------------------------------------------------------- |\n| `id`               | Correlativo por app-key: EP-001, EP-002… Nunca global entre apps                       |\n| `status`           | `defined` lo escribe el Arquitecto; `implemented` lo escribe el Implementador Back     |\n| `path_params`      | `[]` si el endpoint no tiene parámetros en la URL                                      |\n| `request_body`     | `{}` si es GET\u002FDELETE sin body                                                         |\n| `required_headers` | Listar solo headers que el endpoint **requiere** (no los opcionales)                   |\n| `changelog`        | Append al actualizar: `{ \"cycle\": N, \"date\": \"YYYY-MM-DD\", \"change\": \"descripción\" }`  |\n| Deprecar           | Cambiar `status: \"deprecated\"` y appendar en changelog. **Nunca eliminar la entrada.** |\n\n---\n\n## 4. `sdd\u002Fschema.json` — Registro de tablas de BD\n\n**Responsable:** sdd-architect (diseño) + sdd-implementor-back (migración) + sdd-reviewer.\n\n### Estructura\n\n```json\n{\n  \"_comment\": \"...\",\n  \"_schema\": { ... },\n  \"[app-key]\": {\n    \"tables\": {\n      \"[nombre_tabla]\": TableEntry\n    }\n  }\n}\n```\n\n> Solo apps backend tienen tablas. Apps frontend no tienen entradas en schema.json.\n\n### TableEntry — campos\n\n```json\n{\n  \"module\": \"[nombre-módulo]\",\n  \"spec\": \"sdd\u002Fspecs\u002Fspec-[gh-user]-[NNN]-[slug]\",\n  \"status\": \"defined | migrated | updated | deprecated\",\n  \"created_in_cycle\": 1,\n  \"updated_in_cycle\": null,\n  \"migration_file\": \"V1__create_[tabla].sql\",\n  \"columns\": {\n    \"[nombre_columna]\": {\n      \"type\": \"CHAR(36) | VARCHAR(255) | BIGINT | TEXT | DATETIME | BOOLEAN | DECIMAL(10,2)\",\n      \"constraints\": [\"PRIMARY KEY\", \"NOT NULL\", \"UNIQUE\", \"AUTO_INCREMENT\"],\n      \"notes\": \"Descripción del propósito de la columna\"\n    }\n  },\n  \"indexes\": [\n    { \"name\": \"idx_[tabla]_[campo]\", \"columns\": [\"campo1\"], \"unique\": false }\n  ],\n  \"changelog\": []\n}\n```\n\n### Reglas de TableEntry\n\n| Campo            | Regla                                                                                                     |\n| ---------------- | --------------------------------------------------------------------------------------------------------- |\n| `status`         | `defined` = diseñado; `migrated` = script Flyway aplicado                                                 |\n| `migration_file` | Formato Flyway: `V{N}__{accion}_{tabla}.sql`. Actualizar en cada ALTER.                                   |\n| `columns`        | Usar nombres en `snake_case`                                                                              |\n| `indexes`        | `[]` si no hay índices adicionales al PK                                                                  |\n| Deprecar tabla   | `status: \"deprecated\"` + append en changelog. No eliminar la entrada.                                     |\n| Agregar columna  | Actualizar `updated_in_cycle`, agregar columna en `columns`, nuevo `migration_file`, append en changelog. |\n\n### ColumnEntry — constraints válidos\n\n```\n\"PRIMARY KEY\"  \"NOT NULL\"  \"UNIQUE\"  \"AUTO_INCREMENT\"\n\"DEFAULT 'valor'\"  \"REFERENCES tabla(col)\"\n```\n\n---\n\n## 5. `sdd\u002Fcomponents.json` — Registro de componentes frontend\n\n**Responsable:** sdd-architect (status: `defined`) → sdd-implementor-front (status: `implemented`) → sdd-reviewer.\n\n### Estructura\n\n```json\n{\n  \"_comment\": \"...\",\n  \"_schema\": { ... },\n  \"[app-key]\": {\n    \"components\": [ ComponentEntry ]\n  }\n}\n```\n\n> Solo apps frontend tienen componentes. Usar `\"apps\u002Fexample-app\"` como app-key para apps frontend.\n\n### ComponentEntry — campos\n\n```json\n{\n  \"id\": \"COMP-[NNN]\",\n  \"name\": \"NombreComponente\",\n  \"type\": \"page | component | hook | layout\",\n  \"module\": \"[nombre-módulo]\",\n  \"spec\": \"sdd\u002Fspecs\u002Fspec-[gh-user]-[NNN]-[slug]\",\n  \"path\": \"src\u002Fpages\u002F[modulo]\u002FNombreComponente.tsx\",\n  \"status\": \"defined | implemented | updated | deprecated\",\n  \"created_in_cycle\": 1,\n  \"updated_in_cycle\": null,\n  \"description\": \"Qué hace el componente\",\n  \"consumes\": [\"EP-001\"],\n  \"created_at\": \"YYYY-MM-DD\",\n  \"changelog\": []\n}\n```\n\n### Reglas de ComponentEntry\n\n| Campo      | Regla                                                                                                              |\n| ---------- | ------------------------------------------------------------------------------------------------------------------ |\n| `id`       | Correlativo por app-key: COMP-001, COMP-002…                                                                       |\n| `name`     | PascalCase. Igual al nombre del archivo sin extensión.                                                             |\n| `type`     | `page` = ruta de router; `component` = componente reutilizable; `hook` = custom hook; `layout` = wrapper de layout |\n| `path`     | Relativo a la raíz del app (sin `apps\u002F[app]\u002F`)                                                                     |\n| `consumes` | Lista de IDs de endpoints que el componente consume vía API client                                                 |\n\n---\n\n## 6. Tasks — per-cycle `tasks.json` + índice `sdd\u002Ftasks.json`\n\n> ⛔ **Las tasks canónicas viven en `sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Ftasks.json`** (uno por ciclo).\n> `sdd\u002Ftasks.json` es **solo un índice liviano derivado** — nunca editar detalle de tasks ahí.\n> Schemas: `sdd\u002Fschemas\u002Fcycle-tasks.schema.json` y `sdd\u002Fschemas\u002Ftasks-index.schema.json`.\n\n### 6a. `cycles\u002Fcycle-[XX]\u002Ftasks.json` — archivo canónico del ciclo\n\n**Responsable:** sdd-planner (crea) → sdd-implementor-\\* (status por task) → sdd-reviewer (cierre).\n\n```json\n{\n  \"$schema\": \"..\u002F..\u002F..\u002F..\u002Fschemas\u002Fcycle-tasks.schema.json\",\n  \"spec\": \"spec-[gh-user]-[NNN]-[slug]\",\n  \"cycle\": 1,\n  \"module\": \"[nombre-módulo]\",\n  \"apps\": [\"apps\u002F[nombre-app]\"],\n  \"flow\": \"full\",\n  \"user_stories_generated\": true,\n  \"prerequisites\": { \"tasks_generated\": true },\n  \"tasks\": [ TaskEntry ]\n}\n```\n\n- `flow: \"reduced\"` = ciclo de refactor estructural sin HUs; `flow: \"lite\"` = ciclo de un solo actor\n  conducido por `plan.md`. En ambos las tasks pueden tener `user_stories: []`.\n- Cada developer\u002Fimplementador **solo escribe en el archivo de SU ciclo** → sin merge conflicts entre specs.\n\n### 6b. `sdd\u002Ftasks.json` — índice (generado)\n\n**Responsable:** sdd-orchestrator (alta de ciclo) + sdd-reviewer (cierre). Se regenera con `pnpm sdd:rebuild-tasks-index`.\n\n```json\n{\n  \"$schema\": \".\u002Fschemas\u002Ftasks-index.schema.json\",\n  \"sdd_version\": \"4.0\",\n  \"specs\": {\n    \"[spec-id]\": {\n      \"cycles\": {\n        \"cycle-[XX]\": {\n          \"file\": \"sdd\u002Fspecs\u002F[spec-id]\u002Fcycles\u002Fcycle-[XX]\u002Ftasks.json\",\n          \"module\": \"[nombre-módulo]\",\n          \"apps\": [\"apps\u002F[nombre-app]\"],\n          \"status\": \"in-progress | completed\",\n          \"tasks_total\": 10,\n          \"tasks_done\": 10\n        }\n      }\n    }\n  }\n}\n```\n\n> El índice **nunca es fuente de verdad**: si difiere de los per-cycle, regenerarlo.\n> `pnpm sdd:validate` falla si el índice está desactualizado.\n\n### TaskEntry — campos\n\n```json\n{\n  \"id\": \"TASK-[NNN]\",\n  \"title\": \"Título conciso de la task\",\n  \"user_stories\": [\"HU-01\", \"HU-02\"],\n  \"estimation_hours\": 2,\n  \"story_points\": 3,\n  \"depends_on\": [\"TASK-[NNN]\"],\n  \"status\": \"pending | in-progress | done | skipped\",\n  \"files\": [\"apps\u002F[app]\u002Fsrc\u002Fruta\u002FArchivo.java\"],\n  \"usage\": {\n    \"tokens_in\": 42000,\n    \"tokens_out\": 8000,\n    \"duration_minutes\": 25,\n    \"provider_model\": \"copilot\u002Fclaude-sonnet\",\n    \"effort\": \"medium\",\n    \"agent\": \"implementor-back\",\n    \"approx\": true,\n    \"source\": \"declared-estimate\",\n    \"recorded_at\": \"YYYY-MM-DD\"\n  }\n}\n```\n\n> ⛔ **TODOS los campos de TaskEntry son obligatorios excepto `usage`** (`additionalProperties: false`\n> en el schema). Una task sin `estimation_hours` o `story_points` no pasa `pnpm sdd:validate`.\n> `usage` es opcional en el schema para que los registros escritos antes de v0.9.0 sigan validando,\n> pero **desde v0.11.0 el protocolo lo exige**: ver §8.1. `provider_model` es el nombre vigente\n> del campo (`proveedor\u002Fmodelo`); `model_tier` es el alias legacy pre-0.11 — se sigue leyendo, ya\n> no se escribe. Cuando el harness reporta el consumo del subagente que ejecutó la task\n> (`agent-usage-notification`, ej. Claude Code `Agent`), quien recibe la notificación (típicamente\n> el orquestador) vuelca ese número exacto acá — `tokens_total` + split 85\u002F15 documentado en\n> `tokens_in`\u002F`tokens_out`, `approx: false`.\n\n### Reglas de TaskEntry\n\n| Campo              | Regla                                                                                                               | Responsable        |\n| ------------------ | ------------------------------------------------------------------------------------------------------------------- | ------------------ |\n| `id`               | Formato `TASK-[NNN]`: `TASK-001`, `TASK-002`… El scope es el archivo del ciclo — sin prefijo de spec ni ciclo.      | sdd-planner        |\n| `title`            | Conciso, en español, describe la acción técnica                                                                     | sdd-planner        |\n| `user_stories`     | Historias de usuario del `functional.md` (o `plan.md`) que cubre esta task. `[]` solo si `flow: \"reduced\"` o `\"lite\"`. | sdd-planner        |\n| `estimation_hours` | **Obligatorio.** Número decimal de horas estimadas (ej: `1`, `1.5`, `3`). Generado por sdd-planner en `planner.md`. | **sdd-planner**    |\n| `story_points`     | **Obligatorio.** Entero Fibonacci (1, 2, 3, 5, 8, 13). Escala orientativa: 0.5-1h→1SP, 2h→2SP, 3h→3SP, 4h→5SP.      | **sdd-planner**    |\n| `depends_on`       | `[]` si no tiene dependencias. Solo IDs del mismo archivo.                                                          | sdd-planner        |\n| `status`           | `pending` al crear; `in-progress`\u002F`done` durante la implementación. `skipped` = **resuelta \u002F no aplica** (requisito caído, trabajo absorbido por otra task, alcance movido): es un cierre válido, no un pendiente. | sdd-implementor-\\* |\n| `files`            | Lista todos los archivos creados o modificados. Completar al terminar la task.                                      | sdd-implementor-\\* |\n| `usage`            | Telemetría de la task: tokens + `provider_model` (`proveedor\u002Fmodelo`) + `agent` + `recorded_at`. Sin contador → estimación con `approx: true`. Ver §8.1. | sdd-implementor-\\* |\n| Marcar como done   | Cambiar `status: \"done\"`, completar `files[]` y correr `pnpm sdd:rebuild-tasks-index`                               | sdd-implementor-\\* |\n\n### Escala de Story Points recomendada\n\n| Horas estimadas | Story Points | Complejidad |\n| --------------- | ------------ | ----------- |\n| ≤ 1h            | 1 SP         | Trivial     |\n| 1.5 – 2h        | 2 SP         | Simple      |\n| 2.5 – 3h        | 3 SP         | Moderada    |\n| 3.5 – 4h        | 5 SP         | Alta        |\n| > 5h            | 8 SP         | Muy alta    |\n\n> Una task > 8h debe dividirse en subtasks.\n\n---\n\n## 7. `sdd\u002Ffixes.json` — Registro global de fixes\n\n**Responsable:** sdd-orchestrator (FIX GATE) + sdd-reviewer (cierre).\n\n### Estructura\n\n```json\n{\n  \"$schema\": \".\u002Fschemas\u002Ffixes.schema.json\",\n  \"_description\": \"...\",\n  \"_version\": \"3.0.0\",\n  \"_convention\": \"...\",\n  \"_keywords\": [\"[FIX]\", \"[BUGFIX]\", \"[HOTFIX]\", \"[IMPROVEMENT]\"],\n  \"fixes\": [ FixEntry ]\n}\n```\n\n### FixEntry — campos\n\n```json\n{\n  \"id\": \"FIX-[gh-user]-[seq] | FIX-[gh-user]-[spec-NNN]-[seq]\",\n  \"author\": \"[gh-user]\",\n  \"spec_id\": \"spec-[gh-user]-[NNN]-[slug] | null\",\n  \"fix_document\": \"sdd\u002Ffixes\u002Ffix-[gh-user]-[seq].md | sdd\u002Fspecs\u002F{spec-id}\u002Ffixes\u002Ffix-[...].md\",\n  \"type\": \"HOTFIX | BUGFIX | FIX | IMPROVEMENT\",\n  \"severity\": \"critical | high | medium | low\",\n  \"created_at\": \"YYYY-MM-DD\",\n  \"resolved_at\": \"YYYY-MM-DD | null\",\n  \"validated_at\": \"YYYY-MM-DD | null\",\n  \"title\": \"Título del fix (máx 120 chars)\",\n  \"estimation_hours\": 1.5,\n  \"description\": \"Explicación detallada del problema y la solución\",\n  \"justification\": \"Why this cannot wait for a full SDD cycle\",\n  \"related_modules\": [\"[módulo o app afectada]\"],\n  \"affected_files\": [\"path\u002Fto\u002Ffile1.ts\", \"path\u002Fto\u002Ffile2.java\"],\n  \"test_reference\": \"referencia al test que valida el fix | null\",\n  \"status\": \"pending | in-progress | implemented | validated | absorbed\",\n  \"cycle\": \"cycle-[XX] | null\",\n  \"usage\": {\n    \"tokens_in\": 15000,\n    \"tokens_out\": 3000,\n    \"provider_model\": \"claude\u002Fsonnet\",\n    \"effort\": \"medium\",\n    \"agent\": \"implementor-back\",\n    \"approx\": false,\n    \"source\": \"session-report\",\n    \"recorded_at\": \"YYYY-MM-DD\"\n  }\n}\n```\n\n### Ciclo de vida del status\n\n```\npending → in-progress → implemented (dev) → validated | absorbed (sdd-reviewer al cerrar el ciclo)\n```\n\n- `implemented` exige `resolved_at` (validado por `pnpm sdd:validate`)\n- `validated` = el Reviewer confirmó el fix; `absorbed` = la solución se formaliza en la próxima spec\n- `usage` — **obligatorio al resolver** (mismos campos que TaskEntry, ver §8.1). Lo registra\n  quien resuelve el fix, no el reviewer que lo absorbe. Si participó más de un agente, cada uno\n  va en `usage.by_agent[]` y el nivel superior (`tokens_in`\u002F`tokens_out`) es la suma\n\n### Convención de ID de fix\n\n| Tipo                  | Formato                          | Ejemplo            |\n| --------------------- | -------------------------------- | ------------------ |\n| Repo-level (sin spec) | `FIX-[gh-user]-[seq]`            | `FIX-jdoe-001`     |\n| Spec-scoped           | `FIX-[gh-user]-[spec-NNN]-[seq]` | `FIX-jdoe-002-001` |\n\n- `spec_id: null` → fix repo-level → archivo en `sdd\u002Ffixes\u002F`\n- `spec_id: \"spec-...\"` → fix spec-scoped → archivo en `sdd\u002Fspecs\u002F{spec-id}\u002Ffixes\u002F`\n- `[seq]` = número correlativo dentro de su scope (001, 002…)\n\n---\n\n## 8. `sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Fcycle.json` — Estado del ciclo\n\n**Responsable:** sdd-orchestrator (al iniciar, `status: \"in-progress\"`) → sdd-reviewer (al cerrar, `status: \"completed\"`).\n\n### Al INICIAR el ciclo (sdd-orchestrator)\n\n```json\n{\n  \"$schema\": \"..\u002F..\u002F..\u002F..\u002Fschemas\u002Fcycle.schema.json\",\n  \"cycle\": 1,\n  \"module\": \"[nombre-módulo]\",\n  \"spec\": \"spec-[gh-user]-[NNN]-[slug]\",\n  \"apps\": [\"apps\u002F[nombre-app]\"],\n  \"phase\": \"[nombre-fase]\",\n  \"status\": \"in-progress\",\n  \"started_at\": \"YYYY-MM-DD\",\n  \"completed_at\": null,\n  \"documents\": {\n    \"brief\": \"sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Fbrief.yaml\",\n    \"functional\": \"sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Ffunctional.md\",\n    \"planner\": \"sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Fplanner.md\",\n    \"architect\": \"sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Farchitect.md\",\n    \"tasks\": \"sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Ftasks.json\"\n  },\n  \"artifacts\": [],\n  \"metrics\": {\n    \"tasks_total\": 0,\n    \"tasks_completed\": 0,\n    \"story_points\": 0,\n    \"files_created\": [],\n    \"files_modified\": [],\n    \"files_deleted\": [],\n    \"usage\": { \"tokens_in\": 0, \"tokens_out\": 0, \"by_agent\": [] }\n  },\n  \"tables_created\": [],\n  \"endpoints_implemented\": [],\n  \"components_created\": [],\n  \"issues_found\": [],\n  \"reviewer_report\": null\n}\n```\n\n- `apps` es **siempre array**. Campos opcionales: `phase`, `flow` (`\"full\"` default · `\"reduced\"` refactor sin HUs · `\"lite\"` un solo actor con `plan.md`), `objectives`.\n- En `documents` solo se listan archivos que existen (un ciclo `flow: \"reduced\"` puede omitir functional\u002Fplanner\u002Farchitect; uno `\"lite\"` lista `plan` en lugar de esos cuatro).\n- **`metrics` no nace `null` desde v0.11.0**: el orquestador lo crea con contadores en 0 y\n  `usage.by_agent: []` al abrir el ciclo — es el receptáculo donde cada agente (functional,\n  planner, architect, cada task, el propio orquestador) hace push de su entrada al cerrar su\n  unidad de trabajo. `tokens_in`\u002F`tokens_out` son obligatorios dentro de `usage` por schema, por\n  eso arrancan en `0`; el reviewer los recalcula como suma de `by_agent` al cerrar (§8.1).\n\n### Al CERRAR el ciclo (sdd-reviewer)\n\n```json\n{\n  \"cycle\": 1,\n  \"module\": \"[nombre-módulo]\",\n  \"spec\": \"spec-[gh-user]-[NNN]-[slug]\",\n  \"app\": \"apps\u002F[nombre-app]\",\n  \"phase\": \"[nombre-fase]\",\n  \"status\": \"completed\",\n  \"started_at\": \"YYYY-MM-DD\",\n  \"completed_at\": \"YYYY-MM-DD\",\n  \"documents\": { ... },\n  \"artifacts\": [\"sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Fartifacts\u002Fdiagrama.png\"],\n  \"metrics\": {\n    \"tasks_total\": 8,\n    \"tasks_completed\": 7,\n    \"tasks_skipped\": 1,\n    \"story_points\": 13,\n    \"files_created\": [\"apps\u002F...\u002FArchivo.java\"],\n    \"files_modified\": [\"apps\u002F...\u002FOtroArchivo.java\"],\n    \"files_deleted\": [],\n    \"usage\": {\n      \"tokens_in\": 480000,\n      \"tokens_out\": 62000,\n      \"duration_minutes\": 190,\n      \"approx\": true,\n      \"source\": \"declared-estimate\",\n      \"by_agent\": [\n        { \"agent\": \"functional\", \"provider_model\": \"claude\u002Fsonnet\", \"effort\": \"medium\", \"tokens_in\": 30000, \"tokens_out\": 4000, \"approx\": false, \"source\": \"session-report\", \"recorded_at\": \"YYYY-MM-DD\" },\n        { \"agent\": \"implementor-back\", \"label\": \"TASK-001\", \"provider_model\": \"copilot\u002Fclaude-sonnet\", \"effort\": \"medium\", \"tokens_in\": 420000, \"tokens_out\": 55000, \"approx\": true, \"source\": \"declared-estimate\", \"recorded_at\": \"YYYY-MM-DD\" },\n        { \"agent\": \"reviewer\", \"provider_model\": \"claude\u002Fopus\", \"effort\": \"high\", \"tokens_in\": 30000, \"tokens_out\": 3000, \"approx\": false, \"source\": \"session-report\", \"recorded_at\": \"YYYY-MM-DD\" }\n      ],\n      \"by_tier\": {\n        \"claude\u002Fsonnet\": { \"tokens_in\": 30000, \"tokens_out\": 4000, \"approx\": false, \"source\": \"session-report\" },\n        \"copilot\u002Fclaude-sonnet\": { \"tokens_in\": 420000, \"tokens_out\": 55000, \"approx\": true, \"source\": \"declared-estimate\" },\n        \"claude\u002Fopus\": { \"tokens_in\": 30000, \"tokens_out\": 3000, \"approx\": false, \"source\": \"session-report\" }\n      }\n    }\n  },\n  \"tables_created\": [\"nombre_tabla\"],\n  \"endpoints_implemented\": [\"EP-001\"],\n  \"components_created\": [\"COMP-001\"],\n  \"issues_found\": [\"Descripción de issue encontrado y cómo se resolvió\"],\n  \"reviewer_report\": {\n    \"approved\": true,\n    \"date\": \"YYYY-MM-DD\",\n    \"ca_results\": {\n      \"CA-001\": \"PASS | FAIL — descripción\"\n    },\n    \"tests\": {\n      \"NombreTest\": \"N\u002FN PASS\"\n    },\n    \"notes\": \"Resumen del ciclo\"\n  }\n}\n```\n\n### Reglas de cycle.json\n\n- `cycle.json` **DEBE CREARSE antes de que cualquier agente implementador escriba código**\n- `status: \"in-progress\"` → creado por sdd-orchestrator\n- `status: \"completed\"` → solo el sdd-reviewer puede setearlo\n- `artifacts: []` → listar solo archivos de soporte del ciclo, no los archivos implementados\n- `tables_created` → nombres de tabla (coinciden con keys en `sdd\u002Fschema.json`)\n- `endpoints_implemented` → IDs de EP (coinciden con `id` en `sdd\u002Fapi.json`)\n- `components_created` → IDs de COMP (coinciden con `id` en `sdd\u002Fcomponents.json`)\n- `tasks_skipped` → tasks cerradas como `skipped` (resueltas \u002F no aplican). Ausente se lee como `0`.\n  En un ciclo `completed`, `tasks_completed + tasks_skipped` debe igualar `tasks_total`\n\n---\n\n## 8.1 Telemetría de uso (`usage`) — OBLIGATORIA al cerrar\n\n> Alimenta el dashboard de **Costos** del visor SDD, que compara la estimación tradicional\n> (horas × tarifa) contra el costo real del modo agéntico. Sin telemetría, el ahorro que\n> justifica la metodología no tiene evidencia.\n\nEl bloque `usage` vive en tres lugares:\n\n| Dónde                       | Campo                                      | Quién lo escribe                                              | Cuándo              |\n| ---------------------------- | ------------------------------------------- | --------------------------------------------------------------- | -------------------- |\n| `tasks.json` (por task)      | `usage` (+`provider_model`, `agent`)        | sdd-implementor-\\* (o el orquestador si captura la notificación del subagente) | al cerrar la task    |\n| `sdd\u002Ffixes.json` (por fix)   | `usage` (+`provider_model`, `agent`)        | quien resuelve el fix                                            | al resolverlo        |\n| `cycle.json`                 | `metrics.usage` (+`by_agent`, `by_tier`)    | cada agente hace push de su entrada en `by_agent`; sdd-reviewer cierra | al terminar cada documento \u002F al cerrar el ciclo |\n\n> **Quien ejecuta registra; nadie reconstruye al final.** `functional`, `planner` y `architect`\n> no tienen fila propia en `tasks.json` — al terminar su documento hacen push de su entrada en\n> `cycle.json → metrics.usage.by_agent[]` (el orquestador ya creó `metrics` con `by_agent: []` al\n> abrir el ciclo, ver §8). `by_agent` es la **fuente de verdad**: una entrada por unidad de\n> trabajo (cada task, cada documento, la coordinación del orquestador, la revisión del reviewer).\n> `by_tier` se **deriva** de `by_agent` agrupando por `provider_model` — nunca se llena a mano\n> por separado. El reviewer, al cerrar, verifica que `by_agent` tenga una entrada por task `done`\n> + una por documento + orquestador + reviewer, deriva `by_tier`, y solo entonces suma\n> `tokens_in`\u002F`tokens_out` de nivel superior. Su propia estimación cubre únicamente lo que\n> ninguna unidad registró. Una suma que mezcla medido con estimado queda `approx: true` en esa\n> entrada de `by_tier`: un total es tan honesto como su parte más floja.\n\n### Campos\n\n| Campo             | Regla                                                                                                       |\n| ----------------- | ----------------------------------------------------------------------------------------------------------- |\n| `tokens_in\u002Fout`   | **Obligatorios** dentro de `usage`. Enteros ≥ 0.                                                            |\n| `tokens_total`    | Total exacto cuando la fuente reporta un único número (`agent-usage-notification`). `tokens_in`\u002F`tokens_out` llevan igual el split documentado 85\u002F15 para que la fórmula de costo funcione; el visor muestra `tokens_total`. |\n| `duration_minutes`| Opcional.                                                                                                    |\n| `provider_model` \u002F `model_tier` | **Proveedor y modelo son obligatorios.** Claves `proveedor\u002Fmodelo`: `claude\u002Fopus`, `gemini\u002Fpro`, `copilot\u002Fclaude-sonnet`. Antigravity registra bajo `gemini\u002F*` (corre modelos Gemini). Claves legacy sueltas (`haiku`, `sonnet`, `opus`, `fable`) se leen como `claude\u002F*`. `model_tier` es el alias legacy pre-0.11: se sigue leyendo, ya no se escribe. |\n| `effort`          | Nivel de esfuerzo\u002Frazonamiento **declarado antes de ejecutar** (regla ⚙️): `low\\|medium\\|high\\|xhigh\\|max` en Claude, `minimal\\|low\\|medium\\|high` en Gemini. |\n| `agent`           | Rol SDD que hizo el trabajo (`functional\\|planner\\|architect\\|implementor-back\\|implementor-front\\|reviewer\\|orchestrator\\|steward\\|hermes\\|custom`). Obligatorio en `by_agent[]`; `custom` lleva `label`. |\n| `recorded_at`     | Fecha (o datetime ISO) en que se cerró la unidad. |\n| `approx`          | `true` = estimación declarada; `false`\u002Fausente = leído de un contador. El visor muestra **estimado** en la columna Origen. |\n| `source`          | `session-report` (Claude Code) · `stats-command` (`\u002Fstats` de Gemini CLI) · `api-usage` · `agent-usage-notification` (Claude Code: conteo exacto que el harness reporta al padre al terminar un subagente — `\u003Cusage>\u003Csubagent_tokens>N\u003C\u002Fsubagent_tokens>…\u003C\u002Fusage>`, `approx: false`) · `declared-estimate` (Copilot, Antigravity, o cualquier caso sin contador — `approx: true` obligatorio). |\n\n### La regla que reemplaza al \"ante la duda, omitir\"\n\n**Nunca se omite la telemetría por no tener un contador exacto.** El modelo siempre se conoce\n—es el que estás usando— y el orden de magnitud del consumo también. Los arneses sin contador\npor sesión (**GitHub Copilot**, **Antigravity**) registran una estimación declarada:\n\n```json\n\"usage\": { \"tokens_in\": 480000, \"tokens_out\": 62000, \"provider_model\": \"copilot\u002Fclaude-sonnet\", \"effort\": \"medium\", \"agent\": \"implementor-back\", \"approx\": true, \"source\": \"declared-estimate\", \"recorded_at\": \"YYYY-MM-DD\" }\n```\n\n`\u002Fstats` (Gemini CLI) y el reporte de uso de la sesión (Claude Code) son comandos del cliente:\nun agente **no puede ejecutarlos**. Pedíselos al dev si querés el número medido; si no están a\nmano, registrá la estimación y seguí — un ciclo cerrado sin `usage` es un cierre incompleto.\n\nEn Claude Code, cuando un agente dispara un subagente con la tool `Agent`, la notificación de\ncierre trae el conteo exacto (`agent-usage-notification`) — quien la recibe (orquestador o\nreviewer) lo vuelca directo en `tasks[].usage` y en `by_agent`, sin pedirle nada al dev.\n\nLo único prohibido es **inventar un número preciso y presentarlo como medido**: `approx: false`\nsin contador detrás (y `approx: false` combinado con `source: declared-estimate` es un error\ndel validador, no un warning). `pnpm sdd:validate` marca **error** si un ciclo `completed` (o un\nfix resuelto) desde el 2026-09-02 no tiene `usage` con proveedor\u002Fmodelo y tokens; **warning** si\n`by_agent` falta o `sum(by_agent) ≠ by_tier`. Registros anteriores a esa fecha solo generan warning.\n\n---\n\n## 9. Valores de status por registro\n\n| Registro                | Status válidos                                                   | Progresión                                                  |\n| ----------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------- |\n| `index.json` (specs)    | `draft`, `in-progress`, `completed`, `cancelled`                 | draft → in-progress (orquestador al abrir cycle-01) → completed |\n| `api.json` (endpoints)  | `defined`, `implemented`, `updated`, `deprecated`                | defined → implemented → updated\\*                           |\n| `schema.json` (tablas)  | `defined`, `migrated`, `updated`, `deprecated`                   | defined → migrated → updated\\*                              |\n| `components.json`       | `defined`, `implemented`, `updated`, `deprecated`                | defined → implemented → updated\\*                           |\n| tasks per-cycle (tasks) | `pending`, `in-progress`, `done`, `skipped`                      | pending → in-progress → done \\| skipped\\*\\*                   |\n| `fixes.json` (fixes)    | `pending`, `in-progress`, `implemented`, `validated`, `absorbed` | pending → in-progress → implemented → validated \\| absorbed |\n| `cycle.json`            | `in-progress`, `completed`                                       | in-progress → completed                                     |\n\n> \\* `updated` se puede repetir múltiples veces (con nuevo `updated_in_cycle` y entrada en `changelog`).\n>\n> \\*\\* `done` y `skipped` son ambos **terminales**: una task `skipped` está resuelta (no aplica),\n> no pendiente. El ciclo cierra cuando `tasks_completed + tasks_skipped == tasks_total`, y el visor\n> la cuenta como resuelta en el progreso.\n\n---\n\n## 10. Convenciones de IDs\n\n| Tipo                | Formato                          | Scope                                               | Ejemplo                            |\n| ------------------- | -------------------------------- | --------------------------------------------------- | ---------------------------------- |\n| Spec                | `spec-[gh-user]-[NNN]-[slug]`    | Personal por dev                                    | `spec-jdoe-001-enrollment-request` |\n| Endpoint            | `EP-[NNN]`                       | Correlativo por app-key                             | `EP-001`, `EP-002`                 |\n| Tabla               | nombre directo (key en `tables`) | Por app-key                                         | `enrollment_requests`              |\n| Componente          | `COMP-[NNN]`                     | Correlativo por app-key                             | `COMP-001`, `COMP-002`             |\n| Task                | `TASK-[NNN]`                     | Por archivo de ciclo (`cycles\u002Fcycle-XX\u002Ftasks.json`) | `TASK-001`, `TASK-002`             |\n| Fix repo-level      | `FIX-[gh-user]-[seq]`            | Global del repo                                     | `FIX-jdoe-001`                     |\n| Fix spec-level      | `FIX-[gh-user]-[spec-NNN]-[seq]` | Por spec                                            | `FIX-jdoe-002-001`                 |\n| Historia usuario    | `HU-[NN]`                        | Por ciclo                                           | `HU-01`, `HU-02`                   |\n| Criterio aceptación | `CA-[NNN]`                       | Por ciclo                                           | `CA-001`, `CA-002`                 |\n\n---\n\n## 11. Anti-patrones frecuentes (EVITAR)\n\n| Anti-patrón                                              | Correcto                                                                                                   |\n| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |\n| Escribir en la raíz de `api.json` (fuera del app-key)    | Siempre bajo `{ \"[app-key]\": { \"endpoints\": [...] } }`                                                     |\n| Usar `fecha_inicio`, `estado`, `ciclo`                   | Usar `start_date`, `status`, `cycle`                                                                       |\n| Eliminar una entrada de cualquier registro               | Usar `status: \"deprecated\"` + entrada en `changelog`                                                       |\n| `updated_in_cycle: 1` cuando se crea en ciclo 1          | `updated_in_cycle: null` al crear, solo actualizar en ciclos posteriores                                   |\n| `cycle.json` con `status: \"completed\"` creado al inicio  | Siempre `status: \"in-progress\"` al crear; solo sdd-reviewer cambia a `\"completed\"`                         |\n| `changelog` con datos en la primera entrada del registro | `changelog: []` al crear; solo appendar en actualizaciones posteriores                                     |\n| Crear cycle.json después de empezar la implementación    | cycle.json DEBE existir ANTES de cualquier código                                                          |\n| Usar el mismo contador NNN entre devs                    | El contador `[NNN]` es personal de cada dev (no global)                                                    |\n| Mezclar fixes repo-level con spec-level                  | Repo-level → `sdd\u002Ffixes\u002F`; spec-level → `sdd\u002Fspecs\u002F{spec-id}\u002Ffixes\u002F`                                       |\n| Task sin `estimation_hours` o `story_points`             | sdd-planner DEBE generar ambos campos en `planner.md` antes de hacer merge                                 |\n| Editar detalle de tasks en `sdd\u002Ftasks.json`              | El índice es generado — editar el `tasks.json` del ciclo y correr `pnpm sdd:rebuild-tasks-index`           |\n| Inventar campos nuevos en un registro                    | Los schemas usan `additionalProperties: false` — un campo nuevo requiere actualizar `sdd\u002Fschemas\u002F` primero |\n| Escribir un registro y no validar                        | Correr `pnpm sdd:validate` después de CUALQUIER escritura en `sdd\u002F**\u002F*.json`                               |\n\n---\n\n## 12. Regla de sincronización entre registros\n\nCuando el sdd-reviewer cierra un ciclo, **todos estos archivos deben actualizarse en la misma operación**:\n\n```\ncycle.json                        → status: \"completed\", completed_at, metrics, reviewer_report\nglobal.json                       → mover módulo de in_progress a completed\nspecs\u002Findex.json                  → status: \"completed\" + completed_at (si era el último ciclo de la spec)\napi.json                          → status: \"implemented\" en endpoints del ciclo\nschema.json                       → status: \"migrated\" en tablas del ciclo\ncomponents.json                   → status: \"implemented\" en componentes del ciclo\ncycles\u002Fcycle-XX\u002Ftasks.json        → status: \"done\" en todas las tasks del ciclo\nsdd\u002Ftasks.json                    → regenerar: pnpm sdd:rebuild-tasks-index\ncontext\u002F[apps|libs|tools]\u002F[nombre]\u002Fupdates\u002FYYYY-MM-DD-[spec-id]-cycle-[XX].md\n                                  → fragmento aditivo con el delta del ciclo (mecanismo 🧩;\n                                    los archivos base solo los toca la consolidación)\n```\n\n> ⛔ Si `cycle.json` queda en `status: \"completed\"` sin que los demás registros estén actualizados,\n> el sistema SDD pierde consistencia. El sdd-reviewer es responsable de la sincronización completa.\n> **El cierre no es válido hasta que `pnpm sdd:validate` esté en verde.**\n\n---\n\n## 13. Skills relacionados\n\n| Skill                   | Relación con este skill                                                                      |\n| ----------------------- | -------------------------------------------------------------------------------------------- |\n| `sdd-orchestrator`      | Escribe en `global.json` §5, `cycle.json` §8, `specs\u002Findex.json` §9                          |\n| `sdd-planner`           | Escribe en `tasks.json` §6 — responsable de `estimation_hours` y `story_points`              |\n| `sdd-architect`         | Escribe en `api.json` §2 y `schema.json` §3                                                  |\n| `sdd-reviewer`          | Valida y cierra todos los registros del ciclo; único autorizado a marcar `status: completed` |\n| `sdd-implementor-back`  | Actualiza `api.json` §2 al implementar endpoints                                             |\n| `sdd-implementor-front` | Registra en `components.json` §4                                                             |\n| `sdd-functional`        | Sus HUs quedan referenciadas en `tasks.json` campo `user_stories`                            |\n| `sdd-file-structure`    | Complementario — define **dónde** van los archivos; este skill define **qué va dentro**      |\n","# Skill: sdd-data-schemas\n\n> ⛔ **LECTURA OBLIGATORIA** para cualquier agente que escriba en un registro SDD.\n> Este skill cubre el **contenido** de los archivos. Para rutas y naming ver `sdd-file-structure`.\n\n> 🤖 **Fuente de verdad de máquina:** cada registro tiene un JSON Schema estricto en `sdd\u002Fschemas\u002F*.schema.json`\n> (`additionalProperties: false`) y declara `$schema`. Si este documento y el schema difieren, **gana el schema**.\n> Después de escribir cualquier registro: `pnpm sdd:validate`. Si tocaste tasks: `pnpm sdd:rebuild-tasks-index`.\n\n---\n\n## 0. Reglas globales antes de leer cualquier schema\n\n| Regla                        | Descripción                                                                                                                         |\n| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |\n| **Propiedades en inglés**    | Todos los campos JSON usan inglés. `start_date` ✅ `fecha_inicio` ❌                                                                |\n| **Nunca borrar entradas**    | Los registros son append-only o deprecate-only. Jamás eliminar un entry.                                                            |\n| **`updated_in_cycle: null`** | Se inicializa `null`. Solo cambia cuando hay una modificación posterior al ciclo de creación.                                       |\n| **`changelog: []`**          | Siempre empieza vacío. Se appends en cada actualización.                                                                            |\n| **Agrupación por app-key**   | `api.json`, `schema.json` y `components.json` tienen estructura `{ \"[app-key]\": { ... } }`. Nunca escribir en la raíz directamente. |\n\n### App-keys válidos\n\n| App-key              | Descripción                             |\n| -------------------- | --------------------------------------- |\n| `\"example-api\"`      | Spring Boot API (apps\u002Fexample-api)      |\n| `\"another-api\"`      | Otra API backend (apps\u002Fanother-api)     |\n| `\"apps\u002Fexample-app\"` | React app (apps\u002Fexample-app)            |\n| `\"libs\u002Fapi-client\"`  | Librería compartida (libs\u002Fapi-client)   |\n| `\"apps\u002Fexample-api\"` | Spring Boot template (apps\u002Fexample-api) |\n\n> Agregar nuevas apps\u002Flibs según `monorepo.apps` y `monorepo.libs` de `sdd\u002Fglobal.json`.\n> Ambos son mapas `nombre -> descripción`; el visor de `pnpm sdd:docs` descubre el contexto de\n> cada subproyecto a partir de ellos, así que una lib ausente del mapa no aparece listada.\n\n---\n\n## 1. `sdd\u002Fspecs\u002Findex.json` — Registro de specs\n\n**Responsable:** quien crea la spec (append-only, nunca editar entradas existentes).\n\n### SpecEntry — campos\n\n```json\n{\n  \"id\": \"spec-[gh-user]-[NNN]-[slug]\",\n  \"author\": \"[gh-user]\",\n  \"slug\": \"[slug]\",\n  \"folder\": \"sdd\u002Fspecs\u002Fspec-[gh-user]-[NNN]-[slug]\",\n  \"file\": \"sdd\u002Fspecs\u002Fspec-[gh-user]-[NNN]-[slug]\u002Fspec-[gh-user]-[NNN]-[slug].spec.md\",\n  \"module\": \"[nombre-módulo]\",\n  \"app\": \"apps\u002F[nombre-app]\",\n  \"status\": \"draft | in-progress | completed | cancelled\",\n  \"title\": \"Título legible (máx 80 chars)\",\n  \"created_at\": \"YYYY-MM-DD\",\n  \"completed_at\": \"YYYY-MM-DD | null\",\n  \"depends_on\": [\"spec-[gh-user]-[NNN]-[slug]\"]\n}\n```\n\n### Reglas de SpecEntry\n\n- `id` = nombre exacto de la carpeta bajo `sdd\u002Fspecs\u002F`\n- `[NNN]` = contador **personal del dev** (001, 002…). No global.\n- `depends_on` = array vacío `[]` si no hay dependencias\n- `status` nace `\"draft\"` (spec escrita o en escritura, sin ciclo abierto — desde v0.11.0;\n  `harness add spec` la crea así y registra el módulo en `pending_modules` de `sdd\u002Fglobal.json`).\n  El sdd-orchestrator la pasa a `\"in-progress\"` al crear `cycle-01` de esa spec. Índices previos\n  a v0.11.0 tienen `\"in-progress\"` para specs sin ciclo — el validador sugiere la migración, nunca reescribe datos.\n- `completed_at` = `null` mientras `status` es `draft` o `in-progress`\n- **Registrar ANTES de crear los archivos del ciclo**\n\n---\n\n## 2. `sdd\u002Fglobal.json` — Estado general del monorepo\n\n**Responsable:** sdd-orchestrator (al iniciar ciclo) + sdd-reviewer (al cerrar ciclo).\n\n### Estructura top-level\n\n```json\n{\n  \"$schema\": \".\u002Fschemas\u002Fglobal.schema.json\",\n  \"project\": \"[nombre-del-proyecto]\",\n  \"description\": \"...\",\n  \"version\": \"1.0.0\",\n  \"profile\": \"team\",\n  \"completed_modules\": [],\n  \"in_progress_modules\": [],\n  \"pending_modules\": [],\n  \"monorepo\": {\n    \"tool\": \"Nx\",\n    \"package_manager\": \"pnpm\",\n    \"apps\": {},\n    \"libs\": {}\n  }\n}\n```\n\n> ⚠️ Ya **no existe `current_cycle` global** — la numeración de ciclos es per-spec (`cycles\u002Fcycle-XX`).\n\n- `profile` (opcional, desde v0.13.0): `\"team\"` (default si falta) abre ciclos `flow: \"full\"`;\n  `\"solo\"` abre `flow: \"lite\"` (un solo actor, `plan.md`). Lo cambia el **sdd-steward** a pedido\n  del dev; el prefijo `[LITE]`\u002F`[FULL]` del pedido gana sobre el perfil. Detalle:\n  `sdd\u002Fdual-harness\u002Frules\u002Fsdd-gates.md` § Flow.\n- `github` (opcional, desde v0.20.0): `branch_per_cycle` (`\"on\"` | `\"off\"`; si falta, `team` ⇒ on y\n  `solo` ⇒ off) y `default_branch` (base de los PRs de ciclo, default `main`). Lo leen\n  `pnpm sdd:branch` y `pnpm sdd:pr`; ver `sdd-gates.md` § Ramas y PRs por ciclo.\n\n### ModuleEntry — campos\n\n```json\n{\n  \"module\": \"[nombre-módulo]\",\n  \"spec\": \"spec-[gh-user]-[NNN]-[slug]\",\n  \"apps\": [\"apps\u002F[nombre-app]\"],\n  \"cycles_completed\": 1,\n  \"completed_at\": \"YYYY-MM-DD\",\n  \"description\": \"Qué hace este módulo (1-2 oraciones)\"\n}\n```\n\n- `apps` es **siempre array** (aunque el módulo toque una sola app).\n- `cycles_completed` = cantidad de ciclos de ESA spec con `status: \"completed\"`.\n- `completed_at` y `description` son obligatorios solo en `completed_modules`.\n\n### Ciclo de vida de un módulo en global.json\n\n```\npending_modules → in_progress_modules → completed_modules\n```\n\n| Evento                 | Quién            | Acción                                                  |\n| ---------------------- | ---------------- | ------------------------------------------------------- |\n| Se planifica el módulo | sdd-orchestrator | Agregar a `pending_modules`                             |\n| Se inicia el ciclo     | sdd-orchestrator | Mover de `pending` a `in_progress`                      |\n| Se cierra el ciclo     | sdd-reviewer     | Mover de `in_progress` a `completed` con `completed_at` |\n\n> ⛔ Regla de concurrencia: **un ciclo activo por spec**. Varios devs pueden tener módulos\n> en `in_progress_modules` a la vez (modelo multi-developer), pero una misma spec nunca\n> tiene dos ciclos abiertos. Varias specs sí pueden estar en curso a la vez, cada una atada a su\n> sesión (`pnpm sdd:use`, ver `sdd\u002Fdual-harness\u002Frules\u002Fsdd-gates.md` § Sesiones paralelas).\n\n> **`sdd\u002Fschemas\u002Fsession-binding.schema.json`** — atadura de una sesión a una unidad (ciclo o\n> fix). Es un archivo **local** (`\u003Cgit-common-dir>\u002Fsdd-sessions\u002Fsessions\u002F\u003Csession-id>.json`), no\n> vive en `sdd\u002F` ni en git, y `pnpm sdd:validate` no lo valida: lo escriben el mod de Claude Code\n> y el puente de Studio. No se edita a mano.\n\n> **`sdd\u002Fschemas\u002Ffile-lease.schema.json`** y **`session-request.schema.json`** — reserva de un\n> archivo de código por una sesión (`\u003Cgit-common-dir>\u002Fsdd-sessions\u002Flocks\u002F\u003Cclave>.json`) y mensaje\n> del buzón entre sesiones (`inbox\u002F\u003Csession-id>\u002F\u003Cid>.json`). También locales y fuera de\n> `sdd:validate`; los escriben el mod, el puente y `pnpm sdd:release`. No se editan a mano.\n\n---\n\n## 3. `sdd\u002Fapi.json` — Registro de endpoints\n\n**Responsable:** sdd-architect (status: `defined`) → sdd-implementor-back (status: `implemented`) → sdd-reviewer.\n\n### Estructura\n\n```json\n{\n  \"_comment\": \"...\",\n  \"_schema\": { ... },\n  \"[app-key]\": {\n    \"endpoints\": [ EndpointEntry ]\n  }\n}\n```\n\n### EndpointEntry — campos\n\n```json\n{\n  \"id\": \"EP-[NNN]\",\n  \"method\": \"GET | POST | PUT | PATCH | DELETE\",\n  \"path\": \"\u002Fruta\u002Fdel\u002Fendpoint\u002F{param}\",\n  \"module\": \"[nombre-módulo]\",\n  \"spec\": \"sdd\u002Fspecs\u002Fspec-[gh-user]-[NNN]-[slug]\",\n  \"status\": \"defined | implemented | updated | deprecated\",\n  \"created_in_cycle\": 1,\n  \"updated_in_cycle\": null,\n  \"description\": \"Qué hace el endpoint\",\n  \"path_params\": [\"param1\"],\n  \"required_headers\": [\"Authorization\", \"Content-Type\"],\n  \"request_body\": {},\n  \"responses\": {\n    \"200\": \"descripción de la respuesta OK\",\n    \"400\": \"descripción del error\"\n  },\n  \"changelog\": []\n}\n```\n\n### Reglas de EndpointEntry\n\n| Campo              | Regla                                                                                  |\n| ------------------ | -------------------------------------------------------------------------------------- |\n| `id`               | Correlativo por app-key: EP-001, EP-002… Nunca global entre apps                       |\n| `status`           | `defined` lo escribe el Arquitecto; `implemented` lo escribe el Implementador Back     |\n| `path_params`      | `[]` si el endpoint no tiene parámetros en la URL                                      |\n| `request_body`     | `{}` si es GET\u002FDELETE sin body                                                         |\n| `required_headers` | Listar solo headers que el endpoint **requiere** (no los opcionales)                   |\n| `changelog`        | Append al actualizar: `{ \"cycle\": N, \"date\": \"YYYY-MM-DD\", \"change\": \"descripción\" }`  |\n| Deprecar           | Cambiar `status: \"deprecated\"` y appendar en changelog. **Nunca eliminar la entrada.** |\n\n---\n\n## 4. `sdd\u002Fschema.json` — Registro de tablas de BD\n\n**Responsable:** sdd-architect (diseño) + sdd-implementor-back (migración) + sdd-reviewer.\n\n### Estructura\n\n```json\n{\n  \"_comment\": \"...\",\n  \"_schema\": { ... },\n  \"[app-key]\": {\n    \"tables\": {\n      \"[nombre_tabla]\": TableEntry\n    }\n  }\n}\n```\n\n> Solo apps backend tienen tablas. Apps frontend no tienen entradas en schema.json.\n\n### TableEntry — campos\n\n```json\n{\n  \"module\": \"[nombre-módulo]\",\n  \"spec\": \"sdd\u002Fspecs\u002Fspec-[gh-user]-[NNN]-[slug]\",\n  \"status\": \"defined | migrated | updated | deprecated\",\n  \"created_in_cycle\": 1,\n  \"updated_in_cycle\": null,\n  \"migration_file\": \"V1__create_[tabla].sql\",\n  \"columns\": {\n    \"[nombre_columna]\": {\n      \"type\": \"CHAR(36) | VARCHAR(255) | BIGINT | TEXT | DATETIME | BOOLEAN | DECIMAL(10,2)\",\n      \"constraints\": [\"PRIMARY KEY\", \"NOT NULL\", \"UNIQUE\", \"AUTO_INCREMENT\"],\n      \"notes\": \"Descripción del propósito de la columna\"\n    }\n  },\n  \"indexes\": [\n    { \"name\": \"idx_[tabla]_[campo]\", \"columns\": [\"campo1\"], \"unique\": false }\n  ],\n  \"changelog\": []\n}\n```\n\n### Reglas de TableEntry\n\n| Campo            | Regla                                                                                                     |\n| ---------------- | --------------------------------------------------------------------------------------------------------- |\n| `status`         | `defined` = diseñado; `migrated` = script Flyway aplicado                                                 |\n| `migration_file` | Formato Flyway: `V{N}__{accion}_{tabla}.sql`. Actualizar en cada ALTER.                                   |\n| `columns`        | Usar nombres en `snake_case`                                                                              |\n| `indexes`        | `[]` si no hay índices adicionales al PK                                                                  |\n| Deprecar tabla   | `status: \"deprecated\"` + append en changelog. No eliminar la entrada.                                     |\n| Agregar columna  | Actualizar `updated_in_cycle`, agregar columna en `columns`, nuevo `migration_file`, append en changelog. |\n\n### ColumnEntry — constraints válidos\n\n```\n\"PRIMARY KEY\"  \"NOT NULL\"  \"UNIQUE\"  \"AUTO_INCREMENT\"\n\"DEFAULT 'valor'\"  \"REFERENCES tabla(col)\"\n```\n\n---\n\n## 5. `sdd\u002Fcomponents.json` — Registro de componentes frontend\n\n**Responsable:** sdd-architect (status: `defined`) → sdd-implementor-front (status: `implemented`) → sdd-reviewer.\n\n### Estructura\n\n```json\n{\n  \"_comment\": \"...\",\n  \"_schema\": { ... },\n  \"[app-key]\": {\n    \"components\": [ ComponentEntry ]\n  }\n}\n```\n\n> Solo apps frontend tienen componentes. Usar `\"apps\u002Fexample-app\"` como app-key para apps frontend.\n\n### ComponentEntry — campos\n\n```json\n{\n  \"id\": \"COMP-[NNN]\",\n  \"name\": \"NombreComponente\",\n  \"type\": \"page | component | hook | layout\",\n  \"module\": \"[nombre-módulo]\",\n  \"spec\": \"sdd\u002Fspecs\u002Fspec-[gh-user]-[NNN]-[slug]\",\n  \"path\": \"src\u002Fpages\u002F[modulo]\u002FNombreComponente.tsx\",\n  \"status\": \"defined | implemented | updated | deprecated\",\n  \"created_in_cycle\": 1,\n  \"updated_in_cycle\": null,\n  \"description\": \"Qué hace el componente\",\n  \"consumes\": [\"EP-001\"],\n  \"created_at\": \"YYYY-MM-DD\",\n  \"changelog\": []\n}\n```\n\n### Reglas de ComponentEntry\n\n| Campo      | Regla                                                                                                              |\n| ---------- | ------------------------------------------------------------------------------------------------------------------ |\n| `id`       | Correlativo por app-key: COMP-001, COMP-002…                                                                       |\n| `name`     | PascalCase. Igual al nombre del archivo sin extensión.                                                             |\n| `type`     | `page` = ruta de router; `component` = componente reutilizable; `hook` = custom hook; `layout` = wrapper de layout |\n| `path`     | Relativo a la raíz del app (sin `apps\u002F[app]\u002F`)                                                                     |\n| `consumes` | Lista de IDs de endpoints que el componente consume vía API client                                                 |\n\n---\n\n## 6. Tasks — per-cycle `tasks.json` + índice `sdd\u002Ftasks.json`\n\n> ⛔ **Las tasks canónicas viven en `sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Ftasks.json`** (uno por ciclo).\n> `sdd\u002Ftasks.json` es **solo un índice liviano derivado** — nunca editar detalle de tasks ahí.\n> Schemas: `sdd\u002Fschemas\u002Fcycle-tasks.schema.json` y `sdd\u002Fschemas\u002Ftasks-index.schema.json`.\n\n### 6a. `cycles\u002Fcycle-[XX]\u002Ftasks.json` — archivo canónico del ciclo\n\n**Responsable:** sdd-planner (crea) → sdd-implementor-\\* (status por task) → sdd-reviewer (cierre).\n\n```json\n{\n  \"$schema\": \"..\u002F..\u002F..\u002F..\u002Fschemas\u002Fcycle-tasks.schema.json\",\n  \"spec\": \"spec-[gh-user]-[NNN]-[slug]\",\n  \"cycle\": 1,\n  \"module\": \"[nombre-módulo]\",\n  \"apps\": [\"apps\u002F[nombre-app]\"],\n  \"flow\": \"full\",\n  \"user_stories_generated\": true,\n  \"prerequisites\": { \"tasks_generated\": true },\n  \"tasks\": [ TaskEntry ]\n}\n```\n\n- `flow: \"reduced\"` = ciclo de refactor estructural sin HUs; `flow: \"lite\"` = ciclo de un solo actor\n  conducido por `plan.md`. En ambos las tasks pueden tener `user_stories: []`.\n- Cada developer\u002Fimplementador **solo escribe en el archivo de SU ciclo** → sin merge conflicts entre specs.\n\n### 6b. `sdd\u002Ftasks.json` — índice (generado)\n\n**Responsable:** sdd-orchestrator (alta de ciclo) + sdd-reviewer (cierre). Se regenera con `pnpm sdd:rebuild-tasks-index`.\n\n```json\n{\n  \"$schema\": \".\u002Fschemas\u002Ftasks-index.schema.json\",\n  \"sdd_version\": \"4.0\",\n  \"specs\": {\n    \"[spec-id]\": {\n      \"cycles\": {\n        \"cycle-[XX]\": {\n          \"file\": \"sdd\u002Fspecs\u002F[spec-id]\u002Fcycles\u002Fcycle-[XX]\u002Ftasks.json\",\n          \"module\": \"[nombre-módulo]\",\n          \"apps\": [\"apps\u002F[nombre-app]\"],\n          \"status\": \"in-progress | completed\",\n          \"tasks_total\": 10,\n          \"tasks_done\": 10\n        }\n      }\n    }\n  }\n}\n```\n\n> El índice **nunca es fuente de verdad**: si difiere de los per-cycle, regenerarlo.\n> `pnpm sdd:validate` falla si el índice está desactualizado.\n\n### TaskEntry — campos\n\n```json\n{\n  \"id\": \"TASK-[NNN]\",\n  \"title\": \"Título conciso de la task\",\n  \"user_stories\": [\"HU-01\", \"HU-02\"],\n  \"estimation_hours\": 2,\n  \"story_points\": 3,\n  \"depends_on\": [\"TASK-[NNN]\"],\n  \"status\": \"pending | in-progress | done | skipped\",\n  \"files\": [\"apps\u002F[app]\u002Fsrc\u002Fruta\u002FArchivo.java\"],\n  \"usage\": {\n    \"tokens_in\": 42000,\n    \"tokens_out\": 8000,\n    \"duration_minutes\": 25,\n    \"provider_model\": \"copilot\u002Fclaude-sonnet\",\n    \"effort\": \"medium\",\n    \"agent\": \"implementor-back\",\n    \"approx\": true,\n    \"source\": \"declared-estimate\",\n    \"recorded_at\": \"YYYY-MM-DD\"\n  }\n}\n```\n\n> ⛔ **TODOS los campos de TaskEntry son obligatorios excepto `usage`** (`additionalProperties: false`\n> en el schema). Una task sin `estimation_hours` o `story_points` no pasa `pnpm sdd:validate`.\n> `usage` es opcional en el schema para que los registros escritos antes de v0.9.0 sigan validando,\n> pero **desde v0.11.0 el protocolo lo exige**: ver §8.1. `provider_model` es el nombre vigente\n> del campo (`proveedor\u002Fmodelo`); `model_tier` es el alias legacy pre-0.11 — se sigue leyendo, ya\n> no se escribe. Cuando el harness reporta el consumo del subagente que ejecutó la task\n> (`agent-usage-notification`, ej. Claude Code `Agent`), quien recibe la notificación (típicamente\n> el orquestador) vuelca ese número exacto acá — `tokens_total` + split 85\u002F15 documentado en\n> `tokens_in`\u002F`tokens_out`, `approx: false`.\n\n### Reglas de TaskEntry\n\n| Campo              | Regla                                                                                                               | Responsable        |\n| ------------------ | ------------------------------------------------------------------------------------------------------------------- | ------------------ |\n| `id`               | Formato `TASK-[NNN]`: `TASK-001`, `TASK-002`… El scope es el archivo del ciclo — sin prefijo de spec ni ciclo.      | sdd-planner        |\n| `title`            | Conciso, en español, describe la acción técnica                                                                     | sdd-planner        |\n| `user_stories`     | Historias de usuario del `functional.md` (o `plan.md`) que cubre esta task. `[]` solo si `flow: \"reduced\"` o `\"lite\"`. | sdd-planner        |\n| `estimation_hours` | **Obligatorio.** Número decimal de horas estimadas (ej: `1`, `1.5`, `3`). Generado por sdd-planner en `planner.md`. | **sdd-planner**    |\n| `story_points`     | **Obligatorio.** Entero Fibonacci (1, 2, 3, 5, 8, 13). Escala orientativa: 0.5-1h→1SP, 2h→2SP, 3h→3SP, 4h→5SP.      | **sdd-planner**    |\n| `depends_on`       | `[]` si no tiene dependencias. Solo IDs del mismo archivo.                                                          | sdd-planner        |\n| `status`           | `pending` al crear; `in-progress`\u002F`done` durante la implementación. `skipped` = **resuelta \u002F no aplica** (requisito caído, trabajo absorbido por otra task, alcance movido): es un cierre válido, no un pendiente. | sdd-implementor-\\* |\n| `files`            | Lista todos los archivos creados o modificados. Completar al terminar la task.                                      | sdd-implementor-\\* |\n| `usage`            | Telemetría de la task: tokens + `provider_model` (`proveedor\u002Fmodelo`) + `agent` + `recorded_at`. Sin contador → estimación con `approx: true`. Ver §8.1. | sdd-implementor-\\* |\n| Marcar como done   | Cambiar `status: \"done\"`, completar `files[]` y correr `pnpm sdd:rebuild-tasks-index`                               | sdd-implementor-\\* |\n\n### Escala de Story Points recomendada\n\n| Horas estimadas | Story Points | Complejidad |\n| --------------- | ------------ | ----------- |\n| ≤ 1h            | 1 SP         | Trivial     |\n| 1.5 – 2h        | 2 SP         | Simple      |\n| 2.5 – 3h        | 3 SP         | Moderada    |\n| 3.5 – 4h        | 5 SP         | Alta        |\n| > 5h            | 8 SP         | Muy alta    |\n\n> Una task > 8h debe dividirse en subtasks.\n\n---\n\n## 7. `sdd\u002Ffixes.json` — Registro global de fixes\n\n**Responsable:** sdd-orchestrator (FIX GATE) + sdd-reviewer (cierre).\n\n### Estructura\n\n```json\n{\n  \"$schema\": \".\u002Fschemas\u002Ffixes.schema.json\",\n  \"_description\": \"...\",\n  \"_version\": \"3.0.0\",\n  \"_convention\": \"...\",\n  \"_keywords\": [\"[FIX]\", \"[BUGFIX]\", \"[HOTFIX]\", \"[IMPROVEMENT]\"],\n  \"fixes\": [ FixEntry ]\n}\n```\n\n### FixEntry — campos\n\n```json\n{\n  \"id\": \"FIX-[gh-user]-[seq] | FIX-[gh-user]-[spec-NNN]-[seq]\",\n  \"author\": \"[gh-user]\",\n  \"spec_id\": \"spec-[gh-user]-[NNN]-[slug] | null\",\n  \"fix_document\": \"sdd\u002Ffixes\u002Ffix-[gh-user]-[seq].md | sdd\u002Fspecs\u002F{spec-id}\u002Ffixes\u002Ffix-[...].md\",\n  \"type\": \"HOTFIX | BUGFIX | FIX | IMPROVEMENT\",\n  \"severity\": \"critical | high | medium | low\",\n  \"created_at\": \"YYYY-MM-DD\",\n  \"resolved_at\": \"YYYY-MM-DD | null\",\n  \"validated_at\": \"YYYY-MM-DD | null\",\n  \"title\": \"Título del fix (máx 120 chars)\",\n  \"estimation_hours\": 1.5,\n  \"description\": \"Explicación detallada del problema y la solución\",\n  \"justification\": \"Why this cannot wait for a full SDD cycle\",\n  \"related_modules\": [\"[módulo o app afectada]\"],\n  \"affected_files\": [\"path\u002Fto\u002Ffile1.ts\", \"path\u002Fto\u002Ffile2.java\"],\n  \"test_reference\": \"referencia al test que valida el fix | null\",\n  \"status\": \"pending | in-progress | implemented | validated | absorbed\",\n  \"cycle\": \"cycle-[XX] | null\",\n  \"usage\": {\n    \"tokens_in\": 15000,\n    \"tokens_out\": 3000,\n    \"provider_model\": \"claude\u002Fsonnet\",\n    \"effort\": \"medium\",\n    \"agent\": \"implementor-back\",\n    \"approx\": false,\n    \"source\": \"session-report\",\n    \"recorded_at\": \"YYYY-MM-DD\"\n  }\n}\n```\n\n### Ciclo de vida del status\n\n```\npending → in-progress → implemented (dev) → validated | absorbed (sdd-reviewer al cerrar el ciclo)\n```\n\n- `implemented` exige `resolved_at` (validado por `pnpm sdd:validate`)\n- `validated` = el Reviewer confirmó el fix; `absorbed` = la solución se formaliza en la próxima spec\n- `usage` — **obligatorio al resolver** (mismos campos que TaskEntry, ver §8.1). Lo registra\n  quien resuelve el fix, no el reviewer que lo absorbe. Si participó más de un agente, cada uno\n  va en `usage.by_agent[]` y el nivel superior (`tokens_in`\u002F`tokens_out`) es la suma\n\n### Convención de ID de fix\n\n| Tipo                  | Formato                          | Ejemplo            |\n| --------------------- | -------------------------------- | ------------------ |\n| Repo-level (sin spec) | `FIX-[gh-user]-[seq]`            | `FIX-jdoe-001`     |\n| Spec-scoped           | `FIX-[gh-user]-[spec-NNN]-[seq]` | `FIX-jdoe-002-001` |\n\n- `spec_id: null` → fix repo-level → archivo en `sdd\u002Ffixes\u002F`\n- `spec_id: \"spec-...\"` → fix spec-scoped → archivo en `sdd\u002Fspecs\u002F{spec-id}\u002Ffixes\u002F`\n- `[seq]` = número correlativo dentro de su scope (001, 002…)\n\n---\n\n## 8. `sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Fcycle.json` — Estado del ciclo\n\n**Responsable:** sdd-orchestrator (al iniciar, `status: \"in-progress\"`) → sdd-reviewer (al cerrar, `status: \"completed\"`).\n\n### Al INICIAR el ciclo (sdd-orchestrator)\n\n```json\n{\n  \"$schema\": \"..\u002F..\u002F..\u002F..\u002Fschemas\u002Fcycle.schema.json\",\n  \"cycle\": 1,\n  \"module\": \"[nombre-módulo]\",\n  \"spec\": \"spec-[gh-user]-[NNN]-[slug]\",\n  \"apps\": [\"apps\u002F[nombre-app]\"],\n  \"phase\": \"[nombre-fase]\",\n  \"status\": \"in-progress\",\n  \"started_at\": \"YYYY-MM-DD\",\n  \"completed_at\": null,\n  \"documents\": {\n    \"brief\": \"sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Fbrief.yaml\",\n    \"functional\": \"sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Ffunctional.md\",\n    \"planner\": \"sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Fplanner.md\",\n    \"architect\": \"sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Farchitect.md\",\n    \"tasks\": \"sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Ftasks.json\"\n  },\n  \"artifacts\": [],\n  \"metrics\": {\n    \"tasks_total\": 0,\n    \"tasks_completed\": 0,\n    \"story_points\": 0,\n    \"files_created\": [],\n    \"files_modified\": [],\n    \"files_deleted\": [],\n    \"usage\": { \"tokens_in\": 0, \"tokens_out\": 0, \"by_agent\": [] }\n  },\n  \"tables_created\": [],\n  \"endpoints_implemented\": [],\n  \"components_created\": [],\n  \"issues_found\": [],\n  \"reviewer_report\": null\n}\n```\n\n- `apps` es **siempre array**. Campos opcionales: `phase`, `flow` (`\"full\"` default · `\"reduced\"` refactor sin HUs · `\"lite\"` un solo actor con `plan.md`), `objectives`.\n- En `documents` solo se listan archivos que existen (un ciclo `flow: \"reduced\"` puede omitir functional\u002Fplanner\u002Farchitect; uno `\"lite\"` lista `plan` en lugar de esos cuatro).\n- **`metrics` no nace `null` desde v0.11.0**: el orquestador lo crea con contadores en 0 y\n  `usage.by_agent: []` al abrir el ciclo — es el receptáculo donde cada agente (functional,\n  planner, architect, cada task, el propio orquestador) hace push de su entrada al cerrar su\n  unidad de trabajo. `tokens_in`\u002F`tokens_out` son obligatorios dentro de `usage` por schema, por\n  eso arrancan en `0`; el reviewer los recalcula como suma de `by_agent` al cerrar (§8.1).\n\n### Al CERRAR el ciclo (sdd-reviewer)\n\n```json\n{\n  \"cycle\": 1,\n  \"module\": \"[nombre-módulo]\",\n  \"spec\": \"spec-[gh-user]-[NNN]-[slug]\",\n  \"app\": \"apps\u002F[nombre-app]\",\n  \"phase\": \"[nombre-fase]\",\n  \"status\": \"completed\",\n  \"started_at\": \"YYYY-MM-DD\",\n  \"completed_at\": \"YYYY-MM-DD\",\n  \"documents\": { ... },\n  \"artifacts\": [\"sdd\u002Fspecs\u002F{spec-id}\u002Fcycles\u002Fcycle-[XX]\u002Fartifacts\u002Fdiagrama.png\"],\n  \"metrics\": {\n    \"tasks_total\": 8,\n    \"tasks_completed\": 7,\n    \"tasks_skipped\": 1,\n    \"story_points\": 13,\n    \"files_created\": [\"apps\u002F...\u002FArchivo.java\"],\n    \"files_modified\": [\"apps\u002F...\u002FOtroArchivo.java\"],\n    \"files_deleted\": [],\n    \"usage\": {\n      \"tokens_in\": 480000,\n      \"tokens_out\": 62000,\n      \"duration_minutes\": 190,\n      \"approx\": true,\n      \"source\": \"declared-estimate\",\n      \"by_agent\": [\n        { \"agent\": \"functional\", \"provider_model\": \"claude\u002Fsonnet\", \"effort\": \"medium\", \"tokens_in\": 30000, \"tokens_out\": 4000, \"approx\": false, \"source\": \"session-report\", \"recorded_at\": \"YYYY-MM-DD\" },\n        { \"agent\": \"implementor-back\", \"label\": \"TASK-001\", \"provider_model\": \"copilot\u002Fclaude-sonnet\", \"effort\": \"medium\", \"tokens_in\": 420000, \"tokens_out\": 55000, \"approx\": true, \"source\": \"declared-estimate\", \"recorded_at\": \"YYYY-MM-DD\" },\n        { \"agent\": \"reviewer\", \"provider_model\": \"claude\u002Fopus\", \"effort\": \"high\", \"tokens_in\": 30000, \"tokens_out\": 3000, \"approx\": false, \"source\": \"session-report\", \"recorded_at\": \"YYYY-MM-DD\" }\n      ],\n      \"by_tier\": {\n        \"claude\u002Fsonnet\": { \"tokens_in\": 30000, \"tokens_out\": 4000, \"approx\": false, \"source\": \"session-report\" },\n        \"copilot\u002Fclaude-sonnet\": { \"tokens_in\": 420000, \"tokens_out\": 55000, \"approx\": true, \"source\": \"declared-estimate\" },\n        \"claude\u002Fopus\": { \"tokens_in\": 30000, \"tokens_out\": 3000, \"approx\": false, \"source\": \"session-report\" }\n      }\n    }\n  },\n  \"tables_created\": [\"nombre_tabla\"],\n  \"endpoints_implemented\": [\"EP-001\"],\n  \"components_created\": [\"COMP-001\"],\n  \"issues_found\": [\"Descripción de issue encontrado y cómo se resolvió\"],\n  \"reviewer_report\": {\n    \"approved\": true,\n    \"date\": \"YYYY-MM-DD\",\n    \"ca_results\": {\n      \"CA-001\": \"PASS | FAIL — descripción\"\n    },\n    \"tests\": {\n      \"NombreTest\": \"N\u002FN PASS\"\n    },\n    \"notes\": \"Resumen del ciclo\"\n  }\n}\n```\n\n### Reglas de cycle.json\n\n- `cycle.json` **DEBE CREARSE antes de que cualquier agente implementador escriba código**\n- `status: \"in-progress\"` → creado por sdd-orchestrator\n- `status: \"completed\"` → solo el sdd-reviewer puede setearlo\n- `artifacts: []` → listar solo archivos de soporte del ciclo, no los archivos implementados\n- `tables_created` → nombres de tabla (coinciden con keys en `sdd\u002Fschema.json`)\n- `endpoints_implemented` → IDs de EP (coinciden con `id` en `sdd\u002Fapi.json`)\n- `components_created` → IDs de COMP (coinciden con `id` en `sdd\u002Fcomponents.json`)\n- `tasks_skipped` → tasks cerradas como `skipped` (resueltas \u002F no aplican). Ausente se lee como `0`.\n  En un ciclo `completed`, `tasks_completed + tasks_skipped` debe igualar `tasks_total`\n\n---\n\n## 8.1 Telemetría de uso (`usage`) — OBLIGATORIA al cerrar\n\n> Alimenta el dashboard de **Costos** del visor SDD, que compara la estimación tradicional\n> (horas × tarifa) contra el costo real del modo agéntico. Sin telemetría, el ahorro que\n> justifica la metodología no tiene evidencia.\n\nEl bloque `usage` vive en tres lugares:\n\n| Dónde                       | Campo                                      | Quién lo escribe                                              | Cuándo              |\n| ---------------------------- | ------------------------------------------- | --------------------------------------------------------------- | -------------------- |\n| `tasks.json` (por task)      | `usage` (+`provider_model`, `agent`)        | sdd-implementor-\\* (o el orquestador si captura la notificación del subagente) | al cerrar la task    |\n| `sdd\u002Ffixes.json` (por fix)   | `usage` (+`provider_model`, `agent`)        | quien resuelve el fix                                            | al resolverlo        |\n| `cycle.json`                 | `metrics.usage` (+`by_agent`, `by_tier`)    | cada agente hace push de su entrada en `by_agent`; sdd-reviewer cierra | al terminar cada documento \u002F al cerrar el ciclo |\n\n> **Quien ejecuta registra; nadie reconstruye al final.** `functional`, `planner` y `architect`\n> no tienen fila propia en `tasks.json` — al terminar su documento hacen push de su entrada en\n> `cycle.json → metrics.usage.by_agent[]` (el orquestador ya creó `metrics` con `by_agent: []` al\n> abrir el ciclo, ver §8). `by_agent` es la **fuente de verdad**: una entrada por unidad de\n> trabajo (cada task, cada documento, la coordinación del orquestador, la revisión del reviewer).\n> `by_tier` se **deriva** de `by_agent` agrupando por `provider_model` — nunca se llena a mano\n> por separado. El reviewer, al cerrar, verifica que `by_agent` tenga una entrada por task `done`\n> + una por documento + orquestador + reviewer, deriva `by_tier`, y solo entonces suma\n> `tokens_in`\u002F`tokens_out` de nivel superior. Su propia estimación cubre únicamente lo que\n> ninguna unidad registró. Una suma que mezcla medido con estimado queda `approx: true` en esa\n> entrada de `by_tier`: un total es tan honesto como su parte más floja.\n\n### Campos\n\n| Campo             | Regla                                                                                                       |\n| ----------------- | ----------------------------------------------------------------------------------------------------------- |\n| `tokens_in\u002Fout`   | **Obligatorios** dentro de `usage`. Enteros ≥ 0.                                                            |\n| `tokens_total`    | Total exacto cuando la fuente reporta un único número (`agent-usage-notification`). `tokens_in`\u002F`tokens_out` llevan igual el split documentado 85\u002F15 para que la fórmula de costo funcione; el visor muestra `tokens_total`. |\n| `duration_minutes`| Opcional.                                                                                                    |\n| `provider_model` \u002F `model_tier` | **Proveedor y modelo son obligatorios.** Claves `proveedor\u002Fmodelo`: `claude\u002Fopus`, `gemini\u002Fpro`, `copilot\u002Fclaude-sonnet`. Antigravity registra bajo `gemini\u002F*` (corre modelos Gemini). Claves legacy sueltas (`haiku`, `sonnet`, `opus`, `fable`) se leen como `claude\u002F*`. `model_tier` es el alias legacy pre-0.11: se sigue leyendo, ya no se escribe. |\n| `effort`          | Nivel de esfuerzo\u002Frazonamiento **declarado antes de ejecutar** (regla ⚙️): `low\\|medium\\|high\\|xhigh\\|max` en Claude, `minimal\\|low\\|medium\\|high` en Gemini. |\n| `agent`           | Rol SDD que hizo el trabajo (`functional\\|planner\\|architect\\|implementor-back\\|implementor-front\\|reviewer\\|orchestrator\\|steward\\|hermes\\|custom`). Obligatorio en `by_agent[]`; `custom` lleva `label`. |\n| `recorded_at`     | Fecha (o datetime ISO) en que se cerró la unidad. |\n| `approx`          | `true` = estimación declarada; `false`\u002Fausente = leído de un contador. El visor muestra **estimado** en la columna Origen. |\n| `source`          | `session-report` (Claude Code) · `stats-command` (`\u002Fstats` de Gemini CLI) · `api-usage` · `agent-usage-notification` (Claude Code: conteo exacto que el harness reporta al padre al terminar un subagente — `\u003Cusage>\u003Csubagent_tokens>N\u003C\u002Fsubagent_tokens>…\u003C\u002Fusage>`, `approx: false`) · `declared-estimate` (Copilot, Antigravity, o cualquier caso sin contador — `approx: true` obligatorio). |\n\n### La regla que reemplaza al \"ante la duda, omitir\"\n\n**Nunca se omite la telemetría por no tener un contador exacto.** El modelo siempre se conoce\n—es el que estás usando— y el orden de magnitud del consumo también. Los arneses sin contador\npor sesión (**GitHub Copilot**, **Antigravity**) registran una estimación declarada:\n\n```json\n\"usage\": { \"tokens_in\": 480000, \"tokens_out\": 62000, \"provider_model\": \"copilot\u002Fclaude-sonnet\", \"effort\": \"medium\", \"agent\": \"implementor-back\", \"approx\": true, \"source\": \"declared-estimate\", \"recorded_at\": \"YYYY-MM-DD\" }\n```\n\n`\u002Fstats` (Gemini CLI) y el reporte de uso de la sesión (Claude Code) son comandos del cliente:\nun agente **no puede ejecutarlos**. Pedíselos al dev si querés el número medido; si no están a\nmano, registrá la estimación y seguí — un ciclo cerrado sin `usage` es un cierre incompleto.\n\nEn Claude Code, cuando un agente dispara un subagente con la tool `Agent`, la notificación de\ncierre trae el conteo exacto (`agent-usage-notification`) — quien la recibe (orquestador o\nreviewer) lo vuelca directo en `tasks[].usage` y en `by_agent`, sin pedirle nada al dev.\n\nLo único prohibido es **inventar un número preciso y presentarlo como medido**: `approx: false`\nsin contador detrás (y `approx: false` combinado con `source: declared-estimate` es un error\ndel validador, no un warning). `pnpm sdd:validate` marca **error** si un ciclo `completed` (o un\nfix resuelto) desde el 2026-09-02 no tiene `usage` con proveedor\u002Fmodelo y tokens; **warning** si\n`by_agent` falta o `sum(by_agent) ≠ by_tier`. Registros anteriores a esa fecha solo generan warning.\n\n---\n\n## 9. Valores de status por registro\n\n| Registro                | Status válidos                                                   | Progresión                                                  |\n| ----------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------- |\n| `index.json` (specs)    | `draft`, `in-progress`, `completed`, `cancelled`                 | draft → in-progress (orquestador al abrir cycle-01) → completed |\n| `api.json` (endpoints)  | `defined`, `implemented`, `updated`, `deprecated`                | defined → implemented → updated\\*                           |\n| `schema.json` (tablas)  | `defined`, `migrated`, `updated`, `deprecated`                   | defined → migrated → updated\\*                              |\n| `components.json`       | `defined`, `implemented`, `updated`, `deprecated`                | defined → implemented → updated\\*                           |\n| tasks per-cycle (tasks) | `pending`, `in-progress`, `done`, `skipped`                      | pending → in-progress → done \\| skipped\\*\\*                   |\n| `fixes.json` (fixes)    | `pending`, `in-progress`, `implemented`, `validated`, `absorbed` | pending → in-progress → implemented → validated \\| absorbed |\n| `cycle.json`            | `in-progress`, `completed`                                       | in-progress → completed                                     |\n\n> \\* `updated` se puede repetir múltiples veces (con nuevo `updated_in_cycle` y entrada en `changelog`).\n>\n> \\*\\* `done` y `skipped` son ambos **terminales**: una task `skipped` está resuelta (no aplica),\n> no pendiente. El ciclo cierra cuando `tasks_completed + tasks_skipped == tasks_total`, y el visor\n> la cuenta como resuelta en el progreso.\n\n---\n\n## 10. Convenciones de IDs\n\n| Tipo                | Formato                          | Scope                                               | Ejemplo                            |\n| ------------------- | -------------------------------- | --------------------------------------------------- | ---------------------------------- |\n| Spec                | `spec-[gh-user]-[NNN]-[slug]`    | Personal por dev                                    | `spec-jdoe-001-enrollment-request` |\n| Endpoint            | `EP-[NNN]`                       | Correlativo por app-key                             | `EP-001`, `EP-002`                 |\n| Tabla               | nombre directo (key en `tables`) | Por app-key                                         | `enrollment_requests`              |\n| Componente          | `COMP-[NNN]`                     | Correlativo por app-key                             | `COMP-001`, `COMP-002`             |\n| Task                | `TASK-[NNN]`                     | Por archivo de ciclo (`cycles\u002Fcycle-XX\u002Ftasks.json`) | `TASK-001`, `TASK-002`             |\n| Fix repo-level      | `FIX-[gh-user]-[seq]`            | Global del repo                                     | `FIX-jdoe-001`                     |\n| Fix spec-level      | `FIX-[gh-user]-[spec-NNN]-[seq]` | Por spec                                            | `FIX-jdoe-002-001`                 |\n| Historia usuario    | `HU-[NN]`                        | Por ciclo                                           | `HU-01`, `HU-02`                   |\n| Criterio aceptación | `CA-[NNN]`                       | Por ciclo                                           | `CA-001`, `CA-002`                 |\n\n---\n\n## 11. Anti-patrones frecuentes (EVITAR)\n\n| Anti-patrón                                              | Correcto                                                                                                   |\n| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |\n| Escribir en la raíz de `api.json` (fuera del app-key)    | Siempre bajo `{ \"[app-key]\": { \"endpoints\": [...] } }`                                                     |\n| Usar `fecha_inicio`, `estado`, `ciclo`                   | Usar `start_date`, `status`, `cycle`                                                                       |\n| Eliminar una entrada de cualquier registro               | Usar `status: \"deprecated\"` + entrada en `changelog`                                                       |\n| `updated_in_cycle: 1` cuando se crea en ciclo 1          | `updated_in_cycle: null` al crear, solo actualizar en ciclos posteriores                                   |\n| `cycle.json` con `status: \"completed\"` creado al inicio  | Siempre `status: \"in-progress\"` al crear; solo sdd-reviewer cambia a `\"completed\"`                         |\n| `changelog` con datos en la primera entrada del registro | `changelog: []` al crear; solo appendar en actualizaciones posteriores                                     |\n| Crear cycle.json después de empezar la implementación    | cycle.json DEBE existir ANTES de cualquier código                                                          |\n| Usar el mismo contador NNN entre devs                    | El contador `[NNN]` es personal de cada dev (no global)                                                    |\n| Mezclar fixes repo-level con spec-level                  | Repo-level → `sdd\u002Ffixes\u002F`; spec-level → `sdd\u002Fspecs\u002F{spec-id}\u002Ffixes\u002F`                                       |\n| Task sin `estimation_hours` o `story_points`             | sdd-planner DEBE generar ambos campos en `planner.md` antes de hacer merge                                 |\n| Editar detalle de tasks en `sdd\u002Ftasks.json`              | El índice es generado — editar el `tasks.json` del ciclo y correr `pnpm sdd:rebuild-tasks-index`           |\n| Inventar campos nuevos en un registro                    | Los schemas usan `additionalProperties: false` — un campo nuevo requiere actualizar `sdd\u002Fschemas\u002F` primero |\n| Escribir un registro y no validar                        | Correr `pnpm sdd:validate` después de CUALQUIER escritura en `sdd\u002F**\u002F*.json`                               |\n\n---\n\n## 12. Regla de sincronización entre registros\n\nCuando el sdd-reviewer cierra un ciclo, **todos estos archivos deben actualizarse en la misma operación**:\n\n```\ncycle.json                        → status: \"completed\", completed_at, metrics, reviewer_report\nglobal.json                       → mover módulo de in_progress a completed\nspecs\u002Findex.json                  → status: \"completed\" + completed_at (si era el último ciclo de la spec)\napi.json                          → status: \"implemented\" en endpoints del ciclo\nschema.json                       → status: \"migrated\" en tablas del ciclo\ncomponents.json                   → status: \"implemented\" en componentes del ciclo\ncycles\u002Fcycle-XX\u002Ftasks.json        → status: \"done\" en todas las tasks del ciclo\nsdd\u002Ftasks.json                    → regenerar: pnpm sdd:rebuild-tasks-index\ncontext\u002F[apps|libs|tools]\u002F[nombre]\u002Fupdates\u002FYYYY-MM-DD-[spec-id]-cycle-[XX].md\n                                  → fragmento aditivo con el delta del ciclo (mecanismo 🧩;\n                                    los archivos base solo los toca la consolidación)\n```\n\n> ⛔ Si `cycle.json` queda en `status: \"completed\"` sin que los demás registros estén actualizados,\n> el sistema SDD pierde consistencia. El sdd-reviewer es responsable de la sincronización completa.\n> **El cierre no es válido hasta que `pnpm sdd:validate` esté en verde.**\n\n---\n\n## 13. Skills relacionados\n\n| Skill                   | Relación con este skill                                                                      |\n| ----------------------- | -------------------------------------------------------------------------------------------- |\n| `sdd-orchestrator`      | Escribe en `global.json` §5, `cycle.json` §8, `specs\u002Findex.json` §9                          |\n| `sdd-planner`           | Escribe en `tasks.json` §6 — responsable de `estimation_hours` y `story_points`              |\n| `sdd-architect`         | Escribe en `api.json` §2 y `schema.json` §3                                                  |\n| `sdd-reviewer`          | Valida y cierra todos los registros del ciclo; único autorizado a marcar `status: completed` |\n| `sdd-implementor-back`  | Actualiza `api.json` §2 al implementar endpoints                                             |\n| `sdd-implementor-front` | Registra en `components.json` §4                                                             |\n| `sdd-functional`        | Sus HUs quedan referenciadas en `tasks.json` campo `user_stories`                            |\n| `sdd-file-structure`    | Complementario — define **dónde** van los archivos; este skill define **qué va dentro**      |\n",{"name":5,"description":7},"main","ac03b85c624ed09bacf7ef24fed29f1ee335ebd5","sdd\u002Fskills\u002Fsdd-data-schemas",1,"https:\u002F\u002Fgithub.com\u002Fe-burgos\u002Fsdd-harness","https:\u002F\u002Fgithub.com\u002Fe-burgos","https:\u002F\u002Festebanburgos.com.ar\u002F","More than 12 years of experience in different technology companies, I am oriented to design and develop productive and profitable software solutions. ","2026-11-13 23:47:30",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add e-burgos\u002Fsdd-harness --skill sdd-data-schemas",{"tool":39,"command":40},"bunx","bunx skills add e-burgos\u002Fsdd-harness --skill sdd-data-schemas",{"tool":42,"command":43},"pnpm","pnpm dlx skills add e-burgos\u002Fsdd-harness --skill sdd-data-schemas","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fe-burgos\u002Fsdd-harness\u002Fblob\u002Fmain\u002Fsdd\u002Fskills\u002Fsdd-data-schemas\u002FSKILL.md",true,[],[48,56,63,70,75,80],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":55},"01M7BBZKCM7DEC558A5RZ974NF","tucu-ui-pro","Usar siempre que un frontend React\u002FNext use (o vaya a usar) @e-burgos\u002Ftucu-ui — montarlo en Vite, Next 16 o una app con Tailwind propio, elegir ThemeProvider\u002Flayout\u002Fpreset, tematizar con customPaletteColor y tokens --tucu-*, elegir el componente correcto con sus props válidos y esquivar las trampas que rompen en runtime, con o sin el MCP tucu-ui conectado.","https:\u002F\u002Fgithub.com\u002Fe-burgos\u002Fsdd-harness\u002Fblob\u002Fmain\u002Fsdd\u002Fskills\u002Ftucu-ui-pro\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":55},"01M7BBZ522PTJHBT5DZF18P940","nx-migration","Usar al migrar un workspace Nx a una mayor nueva (22 a 23, 23 a 24), actualizar la versión de Nx de un monorepo, resolver errores después de `nx migrate`, o decidir si subir TypeScript 7 — método de un salto de mayor a la vez, registro como fix en el SDD, checklist de verificación por salto, trampas conocidas por versión y el comando `pnpm sdd:nx-migrate`.","https:\u002F\u002Fgithub.com\u002Fe-burgos\u002Fsdd-harness\u002Fblob\u002Fmain\u002Fsdd\u002Fskills\u002Fnx-migration\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":55},"01M7BBYZR3QV90GQ1XYR6CTJWJ","design-languages","Usar al diseñar o rediseñar la UI de un frontend (app, dashboard, landing, auth, storefront) o cuando el pedido nombra un look (\"como Display Ads\", \"liquid glass\", \"cristal líquido\", \"oscuro tipo consola\", \"estilo Apple\") — elegir o derivar un lenguaje visual completo (tokens, tipografía, superficies, escena, componentes firma, motion, accesibilidad), aplicarlo con tucu-ui y verificarlo. Trae dos lenguajes probados en producción listos para replicar.","https:\u002F\u002Fgithub.com\u002Fe-burgos\u002Fsdd-harness\u002Fblob\u002Fmain\u002Fsdd\u002Fskills\u002Fdesign-languages\u002FSKILL.md",[],[],{"skillNo":71,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":55},"01M7BBYTZQWQ37Y3PD1ND8ZW4C","https:\u002F\u002Fgithub.com\u002Fe-burgos\u002Fsdd-harness\u002Fblob\u002Fmain\u002Fapps\u002Fcli\u002Ftemplates\u002Fsdd\u002Fskills\u002Ftucu-ui-pro\u002FSKILL.md",[],[],{"skillNo":76,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":55},"01M7BBY8PA7H8W63APVEKZ33KY","https:\u002F\u002Fgithub.com\u002Fe-burgos\u002Fsdd-harness\u002Fblob\u002Fmain\u002Fapps\u002Fcli\u002Ftemplates\u002Fsdd\u002Fskills\u002Fnx-migration\u002FSKILL.md",[],[],{"skillNo":81,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":55},"01M7BBY3DQERGM7ENJSKP0E8CF","https:\u002F\u002Fgithub.com\u002Fe-burgos\u002Fsdd-harness\u002Fblob\u002Fmain\u002Fapps\u002Fcli\u002Ftemplates\u002Fsdd\u002Fskills\u002Fdesign-languages\u002FSKILL.md",[],[]]