siesa-agents 2.1.88 → 2.1.89

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siesa-agents",
-  "version": "2.1.88",
+  "version": "2.1.89",
   "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
   "main": "index.js",
   "bin": {

package/siesa-agents/bmm/workflows/3-solutioning/create-epics-and-stories/templates/epics-template.md

@@ -16,9 +16,9 @@ Add the following block inside each Epic section, **after the Epic goal statemen
   These criteria validate the COMPLETE epic functionality.
 -->
 
-- [ ] **AC-E{{N}}.1:** {{high_level_criterion_1}}
-- [ ] **AC-E{{N}}.2:** {{high_level_criterion_2}}
-- [ ] **AC-E{{N}}.3:** {{high_level_criterion_3}}
+- [ ] **AC-E{{NNN}}-{{E}}.1:** {{high_level_criterion_1}}
+- [ ] **AC-E{{NNN}}-{{E}}.2:** {{high_level_criterion_2}}
+- [ ] **AC-E{{NNN}}-{{E}}.3:** {{high_level_criterion_3}}
 
 **FRs covered:** {{epic_frs}}
 ```
@@ -41,6 +41,8 @@ Add the following block inside each Epic section, **after the Epic goal statemen
 
 ## Numbering Convention
 
-- Epic N → criteria are `AC-E{N}.1`, `AC-E{N}.2`, `AC-E{N}.3`
+Epic and story IDs follow the centralized convention in `@_siesa-agents/resources/conventions/epic-story-naming-convention.md`.
+
+- Epic `{NNN}-{E}` → criteria are `AC-E{NNN}-{E}.1`, `AC-E{NNN}-{E}.2`, `AC-E{NNN}-{E}.3` (e.g., Epic 16-1 → `AC-E16-1.1`)
 - Minimum 3, maximum 5 criteria per epic
 - Each criterion must map to at least one story within the epic

package/siesa-agents/bmm/workflows/3-solutioning/create-epics-and-stories/workflow_ext.md

@@ -52,27 +52,26 @@ Una vez confirmada la lista de features, inyectar las siguientes reglas de estru
 
 ### Reglas de estructura para el documento `epics.md`:
 
+> **Convención de IDs (OBLIGATORIA):** Los IDs de épicas e historias siguen la convención centralizada definida en `@_siesa-agents/resources/conventions/epic-story-naming-convention.md`. Formato: épicas `{NNN}-{E}`, historias `{NNN}-{E}.{HH}`, donde `NNN` es el número del feature (sin ceros a la izquierda, tomado del PRD/shard `feat-{NNN}-*`).
+
 1. **Agrupación por Feature**: Cada feature confirmado será un heading `##` en el documento. Las épicas de ese feature van DENTRO como `###`. Las stories van como `####`.
 
 2. **Jerarquía de headings obligatoria**:
    - `## {Feature Name}` — agrupa las épicas de un feature
-   - `### Epic {N}: {Title}` — cada épica dentro del feature
-   - `#### Story {N}.{M}: {Title}` — cada story dentro de la épica
+   - `### Epic {NNN}-{E}: {Title}` — cada épica dentro del feature (ej: `### Epic 16-1: ...`)
+   - `#### Story {NNN}-{E}.{HH}: {Title}` — cada story dentro de la épica (ej: `#### Story 16-1.01: ...`)
 
    Nota: La generación del documento de epicas no se realiza por DOMINIO sino por FEATURE.
 
-3. **Numeración de épicas GLOBAL y CONSECUTIVA**: La numeración de épicas NO se reinicia por feature. Es un consecutivo único a lo largo de todo el documento. Ejemplo:
+3. **Numeración de épicas POR FEATURE con prefijo de feature**: El número de épica (`E`) es secuencial DENTRO de cada feature, comenzando en `1`. El prefijo `{NNN}-` garantiza la unicidad global del ID. Ejemplo (feature 16 y feature 17):
    ```
-   ## Measurement Units
-   ### Epic 1: ...
-   ### Epic 2: ...
-
-   ## Cost Models
-   ### Epic 3: ...    ← continúa desde 3, NO reinicia en 1
-   ### Epic 4: ...
+   ## Measurement Units          ← feat-016
+   ### Epic 16-1: ...
+   ### Epic 16-2: ...
 
-   ## Storages
-   ### Epic 5: ...
+   ## Cost Models                ← feat-017
+   ### Epic 17-1: ...    ← reinicia en 1, el prefijo 17- lo hace único
+   ### Epic 17-2: ...
    ```
 
 4. **Secciones generales** (`## Overview`, `## Requirements Inventory`, etc.) permanecen igual que en el template estándar, al nivel `##`.
@@ -82,16 +81,16 @@ Una vez confirmada la lista de features, inyectar las siguientes reglas de estru
    ```
    ## Epic List
 
-   ### {Feature Name 1}
-   - Epic 1: [Title] — FRs: FR1, FR2
-   - Epic 2: [Title] — FRs: FR3
+   ### {Feature Name 1}         ← feat-016
+   - Epic 16-1: [Title] — FRs: FR1, FR2
+   - Epic 16-2: [Title] — FRs: FR3
 
-   ### {Feature Name 2}
-   - Epic 3: [Title] — FRs: FR4, FR5
-   - Epic 4: [Title] — FRs: FR6
+   ### {Feature Name 2}         ← feat-017
+   - Epic 17-1: [Title] — FRs: FR4, FR5
+   - Epic 17-2: [Title] — FRs: FR6
    ```
 
-6. **Step 3 (Stories)**: Al generar épicas y stories, escribir cada feature como sección `##`, con sus épicas como `###` y stories como `####`. La numeración de stories sigue el patrón `{epic_num}.{story_num}` (ej: Story 3.1, Story 3.2 para Epic 3).
+6. **Step 3 (Stories)**: Al generar épicas y stories, escribir cada feature como sección `##`, con sus épicas como `###` y stories como `####`. La numeración de stories sigue el patrón `{NNN}-{E}.{HH}` con `HH` de dos dígitos (ej: Story 16-3.01, Story 16-3.02 para Epic 16-3).
 
 7. **Marcador `FEATURE_CODE_JIRA`**: Cada archivo shard de épica debe comenzar con la siguiente línea como **primera línea del archivo**, antes de cualquier heading:
    ```
@@ -159,11 +158,13 @@ For EACH epic, after the goal statement, add **3-5 high-level Acceptance Criteri
 
 ```markdown
 #### Acceptance Criteria (QA Validation)
-- [ ] **AC-E{N}.1:** [High-level criterion from user perspective]
-- [ ] **AC-E{N}.2:** [High-level criterion from user perspective]
-- [ ] **AC-E{N}.3:** [High-level criterion from user perspective]
+- [ ] **AC-E{NNN}-{E}.1:** [High-level criterion from user perspective]
+- [ ] **AC-E{NNN}-{E}.2:** [High-level criterion from user perspective]
+- [ ] **AC-E{NNN}-{E}.3:** [High-level criterion from user perspective]
 ```
 
+Donde `{NNN}-{E}` es el ID de la épica según la convención centralizada (ej: `AC-E16-1.1`, `AC-E16-1.2`). Ver `@_siesa-agents/resources/conventions/epic-story-naming-convention.md`.
+
 **🎯 WRITING GUIDELINES:**
 
 ✅ **DO (Business language, user perspective):**
@@ -190,10 +191,10 @@ Template reference: `@_siesa-agents/bmm/workflows/3-solutioning/create-epics-and
 After all epics and stories are generated, validate that every Epic AC has at least one supporting story:
 
 ```
-Epic N: [Title]
-├── AC-EN.1: [Criterion] → Supported by: Story N.X, Story N.Y
-├── AC-EN.2: [Criterion] → Supported by: Story N.Z
-└── AC-EN.3: [Criterion] → Supported by: Story N.X, Story N.W
+Epic 16-1: [Title]
+├── AC-E16-1.1: [Criterion] → Supported by: Story 16-1.01, Story 16-1.02
+├── AC-E16-1.2: [Criterion] → Supported by: Story 16-1.03
+└── AC-E16-1.3: [Criterion] → Supported by: Story 16-1.01, Story 16-1.04
 ```
 
 **🚨 VALIDATION RULES:**

package/siesa-agents/core/tasks/shard-doc.md

@@ -24,7 +24,7 @@ The agent determines the sharding mode by analyzing the document content:
 | Signal | Detected Mode |
 |--------|--------------|
 | Contains `### feature —` or `### feature -` headings | **PRD Mode** |
-| Contains `## Epic` headings with story subsections (`### Story`) | **Epic Mode** |
+| Contains `### Epic` headings with story subsections (`#### Story`) | **Epic Mode** |
 | Neither detected | **Generic Mode** (standard `##` level sharding) |
 
 The agent MUST confirm the detected mode with the user before proceeding.
@@ -119,32 +119,34 @@ Section Map (PRD Mode):
 
 ## Mode 2: Epic Sharding
 
+> **Epic/Story ID convention (MANDATORY):** Epic and story IDs follow the centralized convention defined in `@_siesa-agents/resources/conventions/epic-story-naming-convention.md`: epics `{NNN}-{E}`, stories `{NNN}-{E}.{HH}` (e.g., `Epic 16-1`, `Story 16-1.01`). Sharding MUST preserve these IDs as-is in the shard content and use them in the index.
+
 ### When It Applies
 
 The source document is an epics breakdown organized by feature, where each feature groups its epics under a `##` heading:
 
 ```markdown
-# Project Name - Epic Breakdown
+# feat-016 — Project Name - Epic Breakdown
 
 ## Overview
 ...
 
 ## Measurement Units
 
-### Epic 1: Core Entity & CRUD API
-#### Story 1.1: Domain Entity & Database Schema
+### Epic 16-1: Core Entity & CRUD API
+#### Story 16-1.01: Domain Entity & Database Schema
 ...
-#### Story 1.2: API Setup & Secure Create Endpoint
+#### Story 16-1.02: API Setup & Secure Create Endpoint
 ...
 
-### Epic 2: Business Rules & Integrity
-#### Story 2.1: Usage Detection Service
+### Epic 16-2: Business Rules & Integrity
+#### Story 16-2.01: Usage Detection Service
 ...
 
 ## Cost Models
 
-### Epic 1: Entity & Creation API
-#### Story 1.1: Database & Entity Infrastructure
+### Epic 16-3: Entity & Creation API
+#### Story 16-3.01: Database & Entity Infrastructure
 ...
 ```
 
@@ -152,9 +154,10 @@ The source document is an epics breakdown organized by feature, where each featu
 
 Before generating filenames, the agent MUST resolve the feature number (`NNN`) by following this priority order:
 
-1. **Source filename pattern**: Look for `feat-{digits}` in the filename (e.g., `epics-feat-016-name.md` → `16`, `epic-feat-083.md` → `83`). Strip leading zeros.
-2. **Document title**: Look for `feat-{digits}` in the first `#` heading (e.g., `# feat-016 — Proyecciones Financieros` → `16`).
-3. **Not found**: Ask the user: *"¿Cuál es el número del feature (`NNN`) para este documento de épicas?"*
+1. **Epic ID prefix**: If the epic headings already follow the centralized convention (`### Epic {NNN}-{E}: ...`, e.g., `### Epic 16-1:`), take `NNN` directly from the epic IDs. If different `##` sections carry different `NNN` prefixes (multi-feature document), resolve `NNN` **per section** from its own epic IDs.
+2. **Source filename pattern**: Look for `feat-{digits}` in the filename (e.g., `epics-feat-016-name.md` → `16`, `epic-feat-083.md` → `83`). Strip leading zeros.
+3. **Document title**: Look for `feat-{digits}` in the first `#` heading (e.g., `# feat-016 — Proyecciones Financieros` → `16`).
+4. **Not found**: Ask the user: *"¿Cuál es el número del feature (`NNN`) para este documento de épicas?"*
 
 ### Naming Convention
 
@@ -322,7 +325,7 @@ Intelligent Shard Complete ({MODE} Mode):
 
 Applied to heading text to generate filenames:
 
-1. Remove the prefix (`feature — `, `Epic N:`, numbering like `1.`, `2.`, etc.)
+1. Remove the prefix (`feature — `, `Epic {NNN}-{E}:`, numbering like `1.`, `2.`, etc.)
 2. Lowercase all text
 3. Replace spaces with hyphens
 4. Remove special characters: `&`, `,`, `(`, `)`, `/`, `'`, `"`, `:`, `;`
@@ -338,4 +341,4 @@ Applied to heading text to generate filenames:
 3. **Mixed content before first subsection**: Include intro text in index.md
 4. **Empty sections**: Skip sections with no content (heading only)
 5. **Deep nesting**: Only shard at the detection level. Everything below stays inside the shard
-6. **Epic feature number (`NNN`) not detectable**: If neither the filename nor the document title contain a `feat-{digits}` pattern, the agent MUST ask the user before proceeding — never assume or default to `0`.
+6. **Epic feature number (`NNN`) not detectable**: If none of the detection sources (epic ID prefixes, filename, document title) yield a feature number, the agent MUST ask the user before proceeding — never assume or default to `0`.

package/siesa-agents/resources/conventions/epic-story-naming-convention.md

@@ -0,0 +1,130 @@
+# Convención de Nomenclatura para Épicas e Historias
+
+> **Fuente centralizada.** Todo workflow, task o skill que genere, shardee o referencie épicas e historias DEBE seguir esta convención. Referenciar este archivo como:
+> `@_siesa-agents/resources/conventions/epic-story-naming-convention.md`
+
+## Objetivo
+
+Definir un estándar de numeración que vincule cada épica e historia con su feature de origen, garantizando trazabilidad y unicidad global en todo el proyecto. Cada ID es auto-descriptivo: al leer `16-3.02` se sabe inmediatamente que pertenece al Feature 016, Épica 3, Historia 02.
+
+---
+
+## 1. Formato de IDs
+
+### Épicas
+
+```
+{NNN}-{E}
+```
+
+| Componente | Descripción | Ejemplo |
+|------------|-------------|---------|
+| `NNN` | Número del feature (sin ceros a la izquierda) | `16` |
+| `E` | Número secuencial de la épica dentro del feature | `1`, `48`, `56` |
+
+**Ejemplos:** `16-1`, `16-48`, `83-1`
+
+### Historias
+
+```
+{NNN}-{E}.{HH}
+```
+
+| Componente | Descripción | Ejemplo |
+|------------|-------------|---------|
+| `NNN` | Número del feature (sin ceros a la izquierda) | `16` |
+| `E` | Número de la épica dentro del feature | `1`, `48` |
+| `HH` | Número secuencial de la historia (con cero a la izquierda si < 10) | `01`, `12` |
+
+**Ejemplos:** `16-1.01`, `16-48.02`, `83-3.05`
+
+### Acceptance Criteria de épica
+
+```
+AC-E{NNN}-{E}.{X}
+```
+
+**Ejemplos:** `AC-E16-49.1`, `AC-E16-56.5`
+
+---
+
+## 2. Ejemplo Visual Completo
+
+```
+feat-016 — Proyecciones Financieros Segmentos
+
+    Epic 16-1: Company Retrieval Feature
+        Historia 16-1.01: Establish Company Domain & Schema
+        Historia 16-1.02: List Companies Endpoint
+        Historia 16-1.03: Get & Search Endpoints
+
+    Epic 16-2: Operation Center Core Availability
+        Historia 16-2.01: Domain Entity & DB Schema
+        Historia 16-2.02: Read-Only Repository
+```
+
+---
+
+## 3. Nombres de Archivo por Artefacto
+
+| Artefacto | Ubicación | Patrón |
+|-----------|-----------|--------|
+| Épicas consolidadas (shard por feature) | `planning-artifacts/epics/` | `epic-feat-{NNN}-{slug}.md` |
+| Stories | `implementation-artifacts/stories/` | `story-{NNN}-{E}.{HH}-{slug}.md` |
+| Reviews | `implementation-artifacts/reviews/` | `review-{NNN}-{E}.{HH}-{slug}.md` |
+
+**Ejemplos:**
+- `epic-feat-16-measurement-units.md`
+- `story-16-1.01-establish-company-domain-schema.md`
+- `review-16-1.01-company-domain-schema.md`
+
+---
+
+## 4. Uso del ID en el Contenido
+
+### Encabezados en el documento de épicas
+
+```markdown
+### Epic 16-1: Company Retrieval Feature
+#### Story 16-1.01: Establish Company Domain & Schema
+```
+
+### Rangos de épicas (frontmatter, secciones, tablas)
+
+```markdown
+activeEpics: "16-49 to 16-56"
+## §4.2 Accounting Infrastructure (Epics 16-1 – 16-4)
+```
+
+### Título de una story individual
+
+```markdown
+# Story 16-1.01: Establish Company Domain & Schema
+```
+
+### IDs en YAML (`sprint-status.yaml`)
+
+```yaml
+- id: "16-1"          # épica — SIEMPRE entre comillas (contiene guión)
+  stories:
+    - id: "16-1.01"
+      file: "story-16-1.01-establish-company-domain-schema.md"
+```
+
+### Labels de Acceptance Criteria dentro de una story
+
+```markdown
+1. **Entity Definition:** ... [AC: 16-1.01.1]
+```
+
+---
+
+## 5. Reglas
+
+1. **El número del feature (`NNN`) se toma del PRD** correspondiente (ej: `feat-016` → `16`, `feat-083` → `83`). Se escribe sin ceros a la izquierda en los IDs.
+2. **La numeración de épicas (`E`) es secuencial dentro de cada feature**, comenzando en `1`. NO es un consecutivo global del documento: el prefijo `{NNN}-` garantiza la unicidad global.
+3. **La numeración de historias (`HH`) es secuencial dentro de cada épica**, comenzando en `01` (con cero a la izquierda para valores < 10).
+4. **No se reutilizan números** de épicas o historias eliminadas.
+5. **Los IDs en YAML deben ir entre comillas** (`"16-1"`) ya que contienen guión.
+6. **Las referencias posicionales internas** (`AC: 1, 2, 3` dentro de subtasks de la misma story) **no se modifican** — solo usan el formato completo las referencias con ID de épica/historia (`{NNN}-{E}` o `{NNN}-{E}.{HH}`).
+7. **Consistencia total:** la convención aplica a todos los artefactos (épicas, stories, reviews, sprint-status, referencias cruzadas), no solo a archivos individuales.