PRD — syv-character-kit

Visión General

• El producto es documentación, no una aplicación. Este kit entrega la especificación completa necesaria para que cualquier equipo construya un sistema de personajes y combate de escuadras del universo Subordinación y Valor (SyV) — sin imponer lenguaje, framework, infraestructura ni stack.
• Scripts mínimos: Sólo se admiten scripts mínimos como apoyo a la documentación (ej. samplers de referencia), todos sujetos a futura eliminación. No hay servidor, no hay UI, no hay base de datos en este repo. Hay archivos: schemas, catálogos, protocolos, mocks y reglas.
• Convenciones: Idioma: castellano rioplatense, voseo sobrio. Tags en notación punto. Payloads YAML en snake_case_castellano.

1. Propósito

Este PRD ordena el trabajo de documentar cinco entregables:

1. Protocolo y reglas de construcción de personaje. Schema, mutabilidad, derivaciones, sistema de tags.
2. Generador procedural con elementos estocásticos. Algoritmo determinístico por rango + sampler de identidad + prosa LLM.
3. Contrato de API CRUD. Endpoints, payloads, formas dinámicas; agnóstico al runtime.
4. Estructura MOCK inicial. Dos escuadras casi simétricas (Confederación Argentina y Ejército Rojo), 11 personajes cada una, que sirven de plantilla viva para futuros ejércitos.
5. Reglas del motor de batalla y encuentros — alcance squad vs squad. Sistema balanceado, comprensible, replicable en papel, escrito como protocolos.

Lo que se entrega es la documentación que permite construir todo lo anterior. La aplicación es responsabilidad de otro proyecto.

1.1. Contexto del universo SyV

El kit existe dentro del universo de Subordinación y Valor. Contexto mínimo necesario para que las decisiones de schema y motor de batalla mantengan fidelidad al lore — detalle completo en las fuentes canónicas al pie:

• Año 2178. La guerra arrastra dieciocho años. El frente es la Zanja de Alsina, una franja de tierra arrasada que cruza el Valle de la Patagonia. Niebla helada, comunicaciones rotas, ningún bando logra ruptura.
• Confederación Argentina (azul). Estado centralizado con base en Ciudad Dársena. Ejército Confederado: escuadras regulares de once, lideradas por un Sargento, cadena de mando formal.
• Ejército Rojo (rojo). Conglomerado de milicias obreras y portuarias nacidas de la revolución fabril de Bahía Blanca. Sin uniformes estandarizados. Cada célula obedece a un Camarada Puntero elegido por convicción política más que por rango.
• Anatema Mecánico. Prohibición universal de tecnología avanzada. Ambos bandos lo cumplen — la Confederación por decreto (Inquisición y Exorcistas), el Ejército Rojo por doctrina. El kit asume el Anatema: no hay drones, no hay computación en campo, no hay armamento "smart". Las armas son mecánicas; la coordinación es voz, gesto y banderín.
• Tres facciones secundarias existen en el lore (Pueblos del Pantano, Salvajes, Poseídos) pero están fuera del MVP del kit.

2. Mapa de artefactos

Toda referencia desde el PRD a un detalle del schema, del flujo o del motor se hace por link al archivo correspondiente. El PRD no duplica reglas.

3. Principios de diseño

• El PRD es contrato; el repo es la documentación. Este documento define forma y alcance. Cómo se implemente, dónde corra, qué stack use — fuera de scope.
• SOLID y open/close. El schema extiende sin romper. Nuevos perks, tipos de hito, categorías de tag, facciones — sin migraciones, sin breaking changes.
• Tags como modelo de primera clase. Lo que puede ser tag, es tag. Rasgos, skills, traits, perks, equipo, lealtades a facciones/escuadras. La frontera con los campos estructurales (identidad, atributos, aliados, nemesis, historial, historia, metadatos) está fijada en docs/hoja-modelo.md y docs/tag-modelo.md.
• Customs libres + enums abiertos. El producto acepta tags, sub-categorías y tipos de hito fuera del canon. El motor downstream interpreta. Tensión documentada en T-01.
• Stats determinísticos por rango; identidad sorteada. En creación, {fis, tac, men} se derivan de una tabla fija (GDDR-01 §3). Cero aleatoriedad en stats. Nombre, género, edad, rasgos, skills/traits/perks, equipo e historia sí se sortean.
• Memoria viva como naturaleza del canonizado. Un canonizado existe in el tiempo: nace, pelea, cambia. La ficha vigente no es la original. Mutaciones vía hitos en historial[].
• Reproducibilidad por seed para efímeros. (seed, faccion, rango) produce el mismo personaje. Los canonizados pierden esta propiedad tras el primer hito (T-05).
• LLM solo para prosa, solo una vez. El modelo generativo escribe historia en la creación. Al canonizar, se congela.
• Mocks separados de canonizados. Los 22 mocks son fixtures inmutables; los canonizados son entidades vivas de la API. No hay sincronización ni promoción mock → canonizado.
• Agnosis al renderer. El schema describe qué tiene un personaje, no cómo se muestra. Las categorías de tag son metadato semántico, no instrucción de presentación.
• Agnosis al sistema de azar. Todas las probabilidades y modificadores se expresan en porcentaje sobre atributos en escala 0–9. Cualquier sistema de resolución (dados, cartas, digital) puede mapearlo a su moneda local. Ver AGENTS.md §"Aleatoriedad".
• GDDR como puente de diseño. El diseño de juego precede al software. Las decisiones de mecánicas y uso de recursos viven en gddr/ y se referencian con los schemas/catálogos.

4. Schema y reglas

Forma de la hoja: seis bloques estructurales (identidad, atributos, historia, historial, metadatos, extras) + dos colecciones persistidas (aliados, nemesis) + la lista plana tags[]. Definición autoritativa: docs/hoja-modelo.md.

Sistema de tags: notación punto <categoria>[.<subcategoria>].<slug>, multiset, catálogo extensible, requires como documentación ejecutable. Definición autoritativa: docs/tag-modelo.md.

Mutabilidad: el estado vigente del personaje cambia vía hitos en historial[]. Tabla de campos mutables / inmutables / derivados en docs/hoja-modelo.md §8. Catálogo sugerido de tipo de hito en docs/hoja-modelo.md §5. Los hitos agregar_tag / quitar_tag son el mecanismo central de evolución.

Atributos y stats calculadas: vocabulario canónico (FISICO, TACTICO, MENTAL, INICIATIVA, MORAL, FATIGA, MOVIMIENTO, ESTRESS) y su semántica de combate en docs/atributos-y-efectos.md. Los efectos de los tags se declaran contra este vocabulario.

Generador procedural: flujo obligatorio de creación, fases, sorteos ponderados, tabla determinística por rango en gddr/01-flujo-obligatorio-creacion.md.

5. Mocks — dos escuadras canon

22 personajes, distribuidos en dos escuadras simétricas. Composición de cada escuadra: 1 + 1 + 1 + 1 + 4 + 3 (líder, segundo, apuntador, artillero, 4 fusileros, 3 reclutas). FZA total de escuadra completa: 2+2+2+2+(4×1)+(3×1) = 15 (derivado de rol.combate.* — ver §4). Fixtures en mock/personajes/{faccion}/{nn}_{rango}_{apellido}.yaml.

Identificadores de Fixtures

La columna fixture_id representa el identificador del archivo en mock/personajes/, NO el personaje.identidad.slug. El slug del personaje es una patente opaca [A-Z0-9]{8} que se asigna al persistir. Los fixtures ya fueron migrados a este formato.

5.1. Escuadra Confederación Argentina (11)

5.2. Escuadra Ejército Rojo (11)

Inmutabilidad. Los 22 mocks no aceptan hitos vía API (POST /character/{slug}/event → 409). Su evolución, si la hay, ocurre por reescritura del fixture.

6. API y casos de uso

Endpoints: definidos en API.md. Si una ruta no figura ahí, no existe en el contrato. La convención GET /meta/{categoria} expone catálogos curados sin requerir edición del contrato cuando aparecen categorías nuevas — la dinámica del catálogo de tags se traslada al endpoint.

Casos de uso: catálogo de UCs (UC-01..UC-27) y mapping inverso a endpoints en docs/user-stories.md.

Modelo de persistencia: entidades y constraints en MODEL.md. Sincronía estricta con API.md.

7. Motor de batalla — squad vs squad

Entregable pendiente. Sin documento todavía. Cuando se redacte, vivirá en gddr/02-motor-batalla.md y deberá:

• Definir el ciclo de turno (iniciativa → orden → resolución → desgaste).
• Especificar cómo se aplican los efectos declarados en los tags (docs/atributos-y-efectos.md) durante el combate.
• Modelar la escuadra como unidad táctica: composición, fza_aportada agregada, moral de grupo, movimiento al ritmo del más lento.
• Establecer las condiciones de victoria/derrota de un encuentro squad vs squad.
• Ser replicable en papel: las reglas se escriben como protocolos secuenciales, no como pseudocódigo. Cualquier persona con la documentación debe poder arbitrar una batalla sin software.

Hasta que ese GDDR exista, las stats calculadas y su mecánica de resolución descritas en docs/atributos-y-efectos.md §2 son el punto de partida.

8. Alcance

Cubierto por este PRD (entregables documentales)

• Schema completo de la hoja de personaje.
• Sistema de tags categorizado con catálogo curado y extensible.
• Vocabulario canónico de atributos y stats calculadas.
• Flujo obligatorio de creación (GDDR-01, Fases 1–3).
• 2 facciones jugables con sus subfacciones (pelicanos, ejercito_revolucionario_del_pueblo).
• 8 rangos operativos canon más ciudadano.
• 22 mocks (dos escuadras simétricas) migrados a patentes opacas de 8-char y lista plana de tags.
• Contrato de API HTTP (API.md).
• Contrato de persistencia (MODEL.md).
• Catálogos /meta/* dinámicos por categoría de tag.
• Schema completo e implementación mock de la entidad escuadra (OQ-06).

Pendiente dentro de este PRD

• GDDR-01 Fase 4 (tags adicionales, prosa, historial, metadatos en el flujo de creación).
• GDDR-02: motor de batalla squad vs squad.

Fuera de este PRD

• Implementación de la API (cualquier lenguaje, framework o stack).
• Persistencia concreta (motor de base, hosting, despliegue).
• Autenticación, autorización, rate limiting.
• UI, CLI de usuario final, dashboards.
• Las 3 facciones secundarias del lore.
• PJs civiles fuera del rol ciudadano.
• Generación de escuadras completas en una sola llamada.
• Edición arbitraria de canonizados fuera del mecanismo de hitos.
• Reverso de hitos.
• Versionado de la prosa congelada.

Cuando alguno de estos elementos se vuelva relevante, irá a un PRD separado.

9. Tensiones, open questions y arquitectura

Consolidado en la página Notion del proyecto. Tres secciones:

• Tensiones asumidas (T-01..T-10) — decisiones con costo conocido.
• Open questions (OQ-01..OQ-14) — sin decisión todavía.
• Notas de arquitectura (N-01..N-04) — no normativas; insumo para implementadores eventuales.

10. Política editorial

Convenciones de trabajo, identificadores, idioma, expresión de azar en porcentajes, rolling release y trato a los mocks: AGENTS.md.

Fuente canónica del universo (referencia de lore, no copiada):

• /Dev/SyV/syv/src/content/docs/ — documentación del universo Subordinación y Valor: trasfondo, atlas, personajes, diégesis, aventuras, media. Única fuente válida de lore del universo. Repo público: https://github.com/kodexArg/syv.

El kit no depende de ningún otro repo para definirse: el schema, los catálogos, las reglas de generación y las reglas del motor de batalla viven íntegramente acá. La cita al canon es para fidelidad narrativa, no dependencia técnica.