siesa-agents 2.1.92 → 2.1.93

package/package.json

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

package/siesa-agents/bmm/data/git-flow-siesa.md

@@ -34,16 +34,56 @@ Identificar el folder actual para usarlo en la generacion del worktree de la sig
 ---
 
 ## 3. Estándar de Mensajes de Commit
-Se adopta el formato de **Conventional Commits** para mejorar la legibilidad y automatización.
+Se adopta **Conventional Commits** enriquecido con trazabilidad obligatoria a **feature** y **épica**. Todo commit generado por un agente debe seguir EXACTAMENTE esta plantilla. Ningún campo se inventa: todos se derivan del `story_key` (ver Sección 6).
 
-| Tipo | Formato del Mensaje | Uso |
-| :--- | :--- | :--- |
-| **Feature** | `feat: descripción clara del cambio` | Nuevas funcionalidades. |
-| **Fix** | `fix: descripción del error corregido` | Corrección de errores (bugs). |
+### 3.1. Plantilla obligatoria
+
+```
+<tipo>(<feature_scope>): <descripción>
+
+Epic: <NNN>-<E> — <título de la épica>
+Story: <NNN>-<E>.<HH> — <título de la historia>
+```
+
+| Parte | Valor |
+| :--- | :--- |
+| `<tipo>` | `feat` (nueva funcionalidad) o `fix` (corrección de bug). Ante la duda → `feat`. |
+| `<feature_scope>` | **Feature** de origen. **Prioridad:** el código de sincronización con Jira `FEATURE_CODE_JIRA` (issue key real, ej: `PROY-123`) **si ya fue sincronizado**; si no, el fallback `feat-<NNN3>`. Ver Sección 6. |
+| `Epic:` | **Épica** (trailer obligatorio): `<NNN>-<E>` + título literal de la épica. |
+| `Story:` | Historia (trailer obligatorio): `<NNN>-<E>.<HH>` + título literal de la historia. |
+
+- La **descripción** va en minúsculas, en imperativo y ≤ 72 caracteres.
+- Los trailers `Epic:` y `Story:` son máquina-parseables (`git log --format=%(trailers)`); NO se omiten ni se reordenan.
+- El `—` es un guión largo (em dash). Si no se conoce el título literal de la épica, usar solo `Epic: <NNN>-<E>` sin `— título` (NUNCA inventar un título).
+
+### 3.2. Ejemplo — feature YA sincronizado con Jira (`FEATURE_CODE_JIRA=PROY-123`)
+
+story_key `16-1.01`, épica `16-1: Company Retrieval Feature`. El scope usa el issue key de Jira:
+
+```
+feat(PROY-123): establecer dominio y esquema de company
+
+Epic: 16-1 — Company Retrieval Feature
+Story: 16-1.01 — Establish Company Domain & Schema
+```
+
+Comando:
+```bash
+git commit -m "feat(PROY-123): establecer dominio y esquema de company" \
+           -m "Epic: 16-1 — Company Retrieval Feature" \
+           -m "Story: 16-1.01 — Establish Company Domain & Schema"
+```
+
+### 3.3. Ejemplo — feature NO sincronizado (`FEATURE_CODE_JIRA=PENDING:...` o ausente → fallback)
+
+story_key `83-3.05`. Al no haber issue key de Jira, el scope cae al fallback `feat-<NNN3>`:
 
-**Ejemplos:**
-* `git commit -m "feat: implementar validación de identidad mediante SSO"`.
-* `git commit -m "fix: corregir cálculo de nómina en rama legacy"`.
+```
+fix(feat-083): corregir cálculo de nómina en rama legacy
+
+Epic: 83-3 — Payroll Corrections
+Story: 83-3.05 — Fix Overtime Rounding
+```
 
 ---
 ## 4. Cambio de ramas
@@ -67,4 +107,50 @@ cambio de rama:
 * **Protección de Ramas:** `main` y `develop` están protegidas; el push directo está prohibido.
 * **Cuando realizar commit** Los commits deberan hacerce por historia en el code review, especificamente cuando este en status done la historia.
 * **Generacion de ramas** Las ramas se deben generar por epicas o por features nunca por historia.
-* **Nota:** Esta automatización solo podrá crear las ramas como se indica y realizar push a las mismas en caso de ser necesario.
+* **Nota:** Esta automatización solo podrá crear las ramas como se indica y realizar push a las mismas en caso de ser necesario.
+
+---
+## 6. Derivación Determinista del Mensaje de Commit (Anti-Alucinación)
+
+> El agente **NO inventa** feature ni épica: los **parsea** del `story_key`, que sigue la convención `@_siesa-agents/resources/conventions/epic-story-naming-convention.md` (`{NNN}-{E}.{HH}`).
+
+**Regla de parseo del `story_key`** (ej: `16-1.01`):
+- `NNN` = texto antes del **primer** `-` → `16` (el feature)
+- `E` = texto entre el `-` y el `.` → `1` (la épica)
+- `HH` = texto después del `.` → `01` (la historia)
+
+### 6.1. Resolución de `<feature_scope>` (código Jira primero, doc como fallback)
+
+El agente **DEBE** verificar primero si el feature ya fue sincronizado con Jira. Orden de prioridad:
+
+1. **Buscar `FEATURE_CODE_JIRA`** con este orden de búsqueda (igual que el sync de épicas):
+   1. En el **shard de la épica** (`planning-artifacts/epics/epic-feat-<NNN>-*.md`): primera línea `<!-- FEATURE_CODE_JIRA=... -->` o frontmatter YAML `FEATURE_CODE_JIRA:` / `FEATURE_ID:`.
+   2. Si no está ahí → en el **shard del PRD** correspondiente (`prd/f<N>-*.md`).
+2. **Evaluar el valor encontrado:**
+   - Si existe y **NO** empieza con `PENDING:` (es un issue key real, ej: `PROY-123`) → **`<feature_scope>` = ese issue key.** (Feature YA sincronizado.)
+   - Si vale `PENDING:...`, o no se encontró ningún `FEATURE_CODE_JIRA` → **`<feature_scope>` = `feat-<NNN3>`** (fallback documental).
+
+> ⚠️ NUNCA usar el literal `PENDING:...` como scope. `PENDING` ⇒ fallback `feat-<NNN3>`.
+
+**Tabla de fuentes** — cada campo tiene UNA fuente; si la fuente no existe, aplica la regla de "si falta":
+
+| Campo | Fuente única | Si falta |
+| :--- | :--- | :--- |
+| `<tipo>` | `## Change Log` / naturaleza de la historia | usar `feat` |
+| `<feature_scope>` | `FEATURE_CODE_JIRA` sincronizado (§6.1) → issue key real | fallback `feat-<NNN3>` |
+| `NNN` | `story_key`, segmento antes del 1er `-` | ABORTAR: `story_key` inválido |
+| `NNN3` | `NNN` con padding a 3 dígitos (`16`→`016`, `3`→`003`, `123`→`123`) | — |
+| `E` | `story_key`, entre `-` y `.` | ABORTAR: `story_key` inválido |
+| `HH` | `story_key`, después del `.` | ABORTAR: `story_key` inválido |
+| título épica | H2/H3 del epic file (`### Epic <NNN>-<E>: <título>`) | omitir `— título`, dejar solo `Epic: <NNN>-<E>` |
+| título historia | H1 del story file (`# Story <NNN>-<E>.<HH>: <título>`) | omitir `— título`, dejar solo `Story: <NNN>-<E>.<HH>` |
+| descripción | resumen de la historia | derivar del título de la historia, minúsculas, imperativo, ≤72 chars |
+
+**Checklist de validación antes de ejecutar `git commit`** (todos deben ser ✅):
+1. El asunto casa con `^(feat|fix)\(.+\): .{1,72}$` y el scope es **o** un issue key de Jira sincronizado **o** `feat-<NNN3>` — **nunca** `PENDING:...`.
+2. Si el feature estaba sincronizado, el scope es exactamente el `FEATURE_CODE_JIRA` (no el fallback).
+3. Existe una línea `Epic: <NNN>-<E>` y su `<NNN>-<E>` coincide con el prefijo del `story_key`.
+4. Existe una línea `Story: <NNN>-<E>.<HH>` idéntica al `story_key`.
+5. Ningún título fue inventado: si no había fuente, el `— título` se omitió.
+
+Si algún punto falla → NO commitear, reportar el campo faltante.

package/siesa-agents/bmm/workflows/4-implementation/code-review/steps/step-07-commit-push.md

@@ -98,18 +98,30 @@ To securely persist the verified and approved code changes to the repository fol
 
   2. **Construct Commit Message**:
      <action>
-     Per Section 3 of `{gitFlowGuide}`, use Conventional Commits format:
-     - For features: `feat: {description}`
-     - For fixes: `fix: {description}`
-
-     Derive type from story context and construct message.
+     Build the message STRICTLY from Section 3 (template) and Section 6 (deterministic
+     derivation) of `{gitFlowGuide}`. Do NOT redefine or invent the format here — the
+     guide is the single source of truth.
+
+     1. Parse `{{story_key}}` into `NNN`, `E`, `HH` per Section 6.
+     2. Resolve `<feature_scope>` per Section 6.1: FIRST look up `FEATURE_CODE_JIRA` in the
+        epic shard (then the PRD shard). If it is a real synced Jira issue key (NOT
+        `PENDING:...`) → use it as the scope. Otherwise fall back to `feat-<NNN3>`.
+     3. Fill the template:
+        `<tipo>(<feature_scope>): <descripción>` + `Epic:` and `Story:` trailers.
+     4. Take epic/story titles literally from the epic/story files; if absent, omit the
+        `— título` (never invent one).
+     5. Run the Section 6 validation checklist. If any item fails, STOP and report the
+        missing field instead of committing.
+
+     Store the result as `{{commit_message}}` (subject + trailers).
      </action>
 
   3. **User Confirmation**:
      <output>
      READY TO COMMIT:
      - Branch: {{current_branch}}
-     - Message: "feat: implementation for story {{story_key}}"
+     - Message:
+     {{commit_message}}
 
      Do you want to proceed with the commit and push?
      </output>
@@ -129,7 +141,7 @@ To securely persist the verified and approved code changes to the repository fol
      </logic>
 
   4. **Commit Changes**:
-     <action>Run command `git commit -m "feat: implementation for story {{story_key}}"`</action>
+     <action>Commit using `{{commit_message}}` (one `-m` for the subject and one `-m` per trailer line, per the example in Section 3.2 of `{gitFlowGuide}`).</action>
      <check if="Commit failed (no changes?)">
         <output>ℹ️ No changes to commit.</output>
      </check>