siesa-agents 2.1.78 → 2.1.80

package/siesa-agents/bmm/workflows/4-implementation/dev-story/steps/step-02-check-branch.md

@@ -0,0 +1,108 @@
+---
+name: 'step-02-check-branch'
+description: 'Validate and enforce Git branch naming convention per centralized GitFlow guidelines'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/dev-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-02-check-branch.md'
+nextStepFile: '{workflow_path}/steps/step-03-load-context.md'
+
+# Centralized GitFlow Guidelines
+gitFlowGuide: '{project-root}/_siesa-agents/bmm/data/git-flow-siesa.md'
+---
+
+# Step 2: Git Branch Validation
+
+## STEP GOAL:
+
+Ensure development occurs on the correct feature branch following the **centralized GitFlow guidelines** defined in `{gitFlowGuide}`.
+
+## MANDATORY EXECUTION RULES:
+
+- 📖 **LOAD AND READ** `{gitFlowGuide}` before any Git operation
+- 🛑 NEVER start development on `main` or `develop` directly
+- 🔄 Follow the branch naming convention from the centralized guide
+
+## EXECUTION PROTOCOLS:
+
+### 1. Load GitFlow Guidelines
+
+<action>
+1. Load and read the entire file at `{gitFlowGuide}`.
+2. Extract and store the following rules:
+   - **Parent Branch**: The required source branch for features (Section 1)
+   - **Branch Naming Format**: The naming convention pattern (Section 2)
+   - **Commit Standards**: The message format requirements (Section 3)
+   - **Governance Rules**: Protection and naming constraints (Section 4)
+</action>
+
+### 2. Validate Parent Branch
+
+<action>
+1. Run `git branch --show-current` to get `current_branch`.
+2. Per the GitFlow guide, validate that you are on or can branch from `develop`.
+3. If not on `develop`:
+   - Run `git checkout develop && git pull origin develop`
+   - Confirm no pending changes before branching
+</action>
+
+### 3. Gather Branch Parameters
+
+<action>
+Per the naming format in `{gitFlowGuide}` (`rama-padre-team-owner-rq-descripcion`), gather:
+
+1. **Parent Branch**: `develop` (fixed per guidelines)
+2. **Team**: Ask user or derive from project context
+3. **Owner**: Ask user or derive from git config (`git config user.email`)
+4. **RQ**: Extract from story metadata or ask user for requirement number
+5. **Description**: Derive from story name, sanitized (lowercase, hyphens)
+</action>
+
+<output>
+To create the branch, I need the following information per GitFlow guidelines:
+- **Team prefix**: (e.g., `legacy-erp-nomina`, `platform`, etc.)
+- **RQ number**: (requirement/ticket number)
+
+The owner will be derived from your git config, and the description from the story.
+</output>
+
+### 4. Construct Branch Name
+
+<action>
+1. Build branch name following the pattern from `{gitFlowGuide}`:
+   `{parent}-{team}-{owner}-{rq}-{description}`
+
+2. Apply governance rules from Section 4:
+   - All lowercase
+   - No special characters
+   - Hyphens as separators
+
+Example: `develop-legacy-erp-nomina-gaduranb-rq1234-nueva-interfaz`
+</action>
+
+### 5. Check and Create/Switch Branch
+
+**IF Current Branch == Target Branch:**
+- Output: `✅ Already on correct branch: {{target_branch}}`
+- Proceed to Next Step.
+
+**IF Current Branch != Target Branch:**
+1. Check if `target_branch` exists: `git branch --list {{target_branch}}`.
+2. **IF Exists:**
+   - Run `git checkout {{target_branch}}`.
+   - Output: `🔄 Switched to existing branch: {{target_branch}}`.
+3. **IF Not Exists:**
+   - Run `git checkout -b {{target_branch}}`.
+   - Output: `✨ Created and switched to new branch: {{target_branch}}`.
+
+### 6. Store Branch Context
+
+<action>
+Store `target_branch` in workflow context for use in subsequent steps (commit, push).
+</action>
+
+### 7. Next Step
+
+Load, read entire file, then execute `{nextStepFile}` (`step-03-load-context.md`).

package/siesa-agents/bmm/workflows/4-implementation/dev-story/steps/step-03-load-context.md

@@ -0,0 +1,46 @@
+---
+name: 'step-03-load-context'
+description: 'Load project context and story information'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/dev-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-03-load-context.md'
+nextStepFile: '{workflow_path}/steps/step-04-env-readiness.md'
+projectContext: '{project-root}/_bmad-output/project-context.md'
+---
+
+# Step 3: Load Context
+
+## STEP GOAL:
+
+Load all available context to inform implementation, including coding standards, project-wide patterns, and specific story requirements.
+
+## EXECUTION PROTOCOLS:
+
+### 1. Load Project Context
+
+1.  Load `{projectContext}` (if exists) for coding standards and project-wide patterns.
+2.  Review architectural guidelines, tech stack details, and implementation patterns.
+
+### 2. Deep Dive Story Context
+
+1.  Re-read the **Dev Notes** section of the Story file.
+2.  Extract developer guidance:
+    *   Architecture requirements.
+    *   Previous learnings.
+    *   Technical specifications.
+3.  Use this enhanced context to inform implementation decisions.
+
+### 3. Output Status
+
+Display:
+```
+✅ Context Loaded
+Story and project context available for implementation.
+```
+
+### 4. Next Step
+
+Load, read entire file, then execute `{nextStepFile}` (`step-04-env-readiness.md`).

package/siesa-agents/bmm/workflows/4-implementation/dev-story/steps/step-04-env-readiness.md

@@ -0,0 +1,45 @@
+---
+name: 'step-04-env-readiness'
+description: 'Analyze dependencies and ensure environment readiness'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/dev-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-04-env-readiness.md'
+nextStepFile: '{workflow_path}/steps/step-05-review-check.md'
+---
+
+# Step 4: Environment Readiness & UI Kit Check
+
+## STEP GOAL:
+
+Analyze tasks for UI requirements and ensure `siesa-ui-kit` is properly installed and configured if needed.
+
+## EXECUTION PROTOCOLS:
+
+### 1. Analyze for UI Requirements
+
+Scan the Story's Tasks and Acceptance Criteria for UI-related keywords:
+*   `table`, `form`, `view`, `css`, `style`, `component`
+*   `dark mode`, `modal`, `button`, `input`, `grid`, `layout`
+*   `theme`, `icon`, `frontend`, `interface`, `screen`
+*   `dialog`, `popup`, `widget`, `dashboard`, `chart`, `visualization`
+
+### 2. UI Kit Enforcement
+
+**IF NO UI keywords found:**
+1.  Output: `ℹ️ No specific UI tasks detected. Skipping siesa-ui-kit check.`
+
+**IF UI keywords found:**
+1.  **Install/Update**: Run `npm install siesa-ui-kit@latest`.
+    *   Output: `✅ siesa-ui-kit ensured at latest version.`
+2.  **Verify Import**:
+    *   Locate project main entry file (`src/app/layout.tsx`, `src/main.jsx`, etc.).
+    *   Read content to check for `siesa-ui-kit/styles.css`.
+    *   **If missing**: Add `import 'siesa-ui-kit/styles.css'` (or equivalent).
+    *   Output: `✅ Verified/Added 'siesa-ui-kit/styles.css' import.`
+
+### 3. Next Step
+
+Load, read entire file, then execute `{nextStepFile}` (`step-05-review-check.md`).

package/siesa-agents/bmm/workflows/4-implementation/dev-story/steps/step-05-review-check.md

@@ -0,0 +1,57 @@
+---
+name: 'step-05-review-check'
+description: 'Detect review continuation and extract review context'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/dev-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-05-review-check.md'
+nextStepFile: '{workflow_path}/steps/step-06-mark-in-progress.md'
+---
+
+# Step 5: Review Context Check
+
+## STEP GOAL:
+
+Determine if this execution is a continuation after a code review or a fresh start.
+
+## EXECUTION PROTOCOLS:
+
+### 1. Check for Review Section
+
+Inspect the story file for:
+1.  Section: `Senior Developer Review (AI)`
+2.  Subsection in Tasks: `Review Follow-ups (AI)`
+
+### 2. Extract Review Context
+
+**IF Review Section EXISTS:**
+1.  Set `review_continuation = true`.
+2.  Extract:
+    *   Review Outcome (Approve/Changes Requested/Blocked).
+    *   Review Date.
+    *   Action Items (Count checked vs unchecked).
+    *   Severity Breakdown.
+3.  Count unchecked `[ ]` tasks in `Review Follow-ups (AI)`.
+4.  Store `pending_review_items` list.
+5.  Output:
+    ```
+    ⏯️ Resuming Story After Code Review
+    Outcome: {{review_outcome}}
+    Action Items: {{unchecked_review_count}} remaining
+    Strategy: Prioritize review follow-ups [AI-Review] first.
+    ```
+
+**IF Review Section DOES NOT EXIST:**
+1.  Set `review_continuation = false`.
+2.  Set `pending_review_items = empty`.
+3.  Output:
+    ```
+    🚀 Starting Fresh Implementation
+    Story: {{story_key}}
+    ```
+
+### 3. Next Step
+
+Load, read entire file, then execute `{nextStepFile}` (`step-06-mark-in-progress.md`).

package/siesa-agents/bmm/workflows/4-implementation/dev-story/steps/step-06-mark-in-progress.md

@@ -0,0 +1,52 @@
+---
+name: 'step-06-mark-in-progress'
+description: 'Mark story in-progress in sprint status'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/dev-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-06-mark-in-progress.md'
+nextStepFile: '{workflow_path}/steps/step-07-implement.md'
+sprintStatusFile: '{implementation_artifacts}/sprint-status.yaml'
+---
+
+# Step 6: Update Sprint Status
+
+## STEP GOAL:
+
+Update the project's sprint status tracking to reflect that work has started on this story.
+
+## EXECUTION PROTOCOLS:
+
+### 1. Check Sprint Status File
+
+**IF `{sprintStatusFile}` EXISTS:**
+1.  Load the FULL file.
+2.  Find entry for `{{story_key}}` in `development_status`.
+3.  Check current status.
+
+### 2. Update Status
+
+**IF Current Status == 'ready-for-dev' OR `review_continuation == true`:**
+1.  Update status to `in-progress`.
+2.  Save file.
+3.  Output:
+    ```
+    🚀 Status updated: ready-for-dev → in-progress
+    ```
+
+**IF Current Status == 'in-progress':**
+1.  Output: `⏯️ Story already in-progress.`
+
+**IF Status Unknown/Other:**
+1.  Output: `⚠️ Unexpected status: {{current_status}}. Continuing...`
+
+### 3. Non-Sprint Tracking
+
+**IF `{sprintStatusFile}` DOES NOT EXIST:**
+1.  Output: `ℹ️ No sprint status file. Progress tracked in story file only.`
+
+### 4. Next Step
+
+Load, read entire file, then execute `{nextStepFile}` (`step-07-implement.md`).

package/siesa-agents/bmm/workflows/4-implementation/dev-story/steps/step-07-implement.md

@@ -0,0 +1,62 @@
+---
+name: 'step-07-implement'
+description: 'Implement task following red-green-refactor cycle'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/dev-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-07-implement.md'
+nextStepFile: '{workflow_path}/steps/step-08-test-authoring.md'
+completionStep: '{workflow_path}/steps/step-11-mark-review.md'
+---
+
+# Step 7: Implementation Loop (Red-Green-Refactor)
+
+## STEP GOAL:
+
+Implement a SINGLE task or subtask using TDD and the Red-Green-Refactor cycle.
+
+## MANDATORY RULES:
+
+- 🛑 FOLLOW STORY TASKS EXACTLY
+- 🎨 Enforce `siesa-ui-kit` usage
+- 🧪 Red-Green-Refactor is MANDATORY
+
+## EXECUTION PROTOCOLS:
+
+### 1. Identify Next Task
+
+1.  Read Story File.
+2.  Find **FIRST** incomplete task (unchecked `[ ]`).
+    *   **IF NO incomplete tasks:** Load and execute `{completionStep}` (`step-11-mark-review.md`).
+    *   **IF Task Found:** Proceed below.
+
+### 2. UI Kit Validation
+
+For the current task:
+1.  **Strictly Forbidden:** Creating custom UI components if `siesa-ui-kit` has an equivalent.
+2.  **Missing Component Protocol:**
+    *   If component missing, ASK user: [1] Shadcn/ui (MCP) or [2] Custom (MR to Platform).
+    *   Log decision in Dev Notes.
+
+### 3. Red Phase (Failing Test)
+
+1.  Write a **FAILING** test for the task functionality.
+2.  Run test to CONFIRM failure.
+
+### 4. Green Phase (Make it Pass)
+
+1.  Implement **MINIMAL** code to pass the test.
+2.  Run test to CONFIRM success.
+3.  Handle edge cases specified in task.
+
+### 5. Refactor Phase
+
+1.  Improve structure while keeping tests green.
+2.  Align with architecture patterns (from Context).
+3.  Document approach in **Dev Agent Record**.
+
+### 6. Next Step
+
+Load, read entire file, then execute `{nextStepFile}` (`step-08-test-authoring.md`).

package/siesa-agents/bmm/workflows/4-implementation/dev-story/steps/step-08-test-authoring.md

@@ -0,0 +1,39 @@
+---
+name: 'step-08-test-authoring'
+description: 'Author comprehensive tests'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/dev-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-08-test-authoring.md'
+nextStepFile: '{workflow_path}/steps/step-09-run-tests.md'
+---
+
+# Step 8: Comprehensive Test Authoring
+
+## STEP GOAL:
+
+Ensure the implemented task is covered by robust tests beyond the initial TDD cycle (Integration, E2E, Edge Cases).
+
+## EXECUTION PROTOCOLS:
+
+### 1. Unit Tests
+
+Ensure business logic and core functionality are covered.
+
+### 2. Integration Tests
+
+Add tests for component interactions if specified in story requirements.
+
+### 3. End-to-End (E2E) Tests
+
+Include E2E tests for critical UI flows if story demands them.
+
+### 4. Edge Cases
+
+Cover error handling and edge cases identified in Dev Notes.
+
+### 5. Next Step
+
+Load, read entire file, then execute `{nextStepFile}` (`step-09-run-tests.md`).

package/siesa-agents/bmm/workflows/4-implementation/dev-story/steps/step-09-run-tests.md

@@ -0,0 +1,43 @@
+---
+name: 'step-09-run-tests'
+description: 'Run validations and tests'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/dev-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-09-run-tests.md'
+nextStepFile: '{workflow_path}/steps/step-10-validate-task.md'
+---
+
+# Step 9: Run Tests & Validations
+
+## STEP GOAL:
+
+Verify implementation correctness, ensure no regressions, and validate coding standards.
+
+## EXECUTION PROTOCOLS:
+
+### 1. Run Tests
+
+1.  Infer test framework (Vitest/Jest).
+2.  **Run All Tests**: Ensure no regressions.
+3.  **Run New Tests**: Verify implementation.
+
+### 2. Run Quality Checks
+
+1.  Run Linting/Static Analysis (if configured).
+
+### 3. Validate Standards
+
+1.  **UI Library Check**: Verify NO custom styles/components were created where `siesa-ui-kit` exists (unless logged).
+
+### 4. Handling Failures
+
+*   **Regression Failures**: STOP and Fix.
+*   **New Test Failures**: STOP and Fix.
+*   **UI Violation**: STOP and Refactor.
+
+### 5. Next Step
+
+Load, read entire file, then execute `{nextStepFile}` (`step-10-validate-task.md`).

package/siesa-agents/bmm/workflows/4-implementation/dev-story/steps/step-10-validate-task.md

@@ -0,0 +1,63 @@
+---
+name: 'step-10-validate-task'
+description: 'Validate and mark task complete'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/dev-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-10-validate-task.md'
+nextTaskStep: '{workflow_path}/steps/step-07-implement.md'
+completionStep: '{workflow_path}/steps/step-11-mark-review.md'
+---
+
+# Step 10: Task Completion & Loop
+
+## STEP GOAL:
+
+Formally mark the task as complete after verifying all gates, update records, and determine if the workflow should loop for the next task or finish.
+
+## MANDATORY EXECUTION RULES:
+
+- 🛑 NEVER mark complete unless ALL validation gates pass.
+- 🔄 Loop back to Step 07 if tasks remain.
+
+## EXECUTION PROTOCOLS:
+
+### 1. Validation Gates
+
+Confirm:
+1.  Tests EXIST and PASS.
+2.  Implementation matches Task specs exactly.
+3.  ACs satisfied.
+4.  `siesa-ui-kit` compliance.
+5.  No regressions.
+
+### 2. Review Follow-up Handling
+
+**IF Task is `[AI-Review]` follow-up:**
+1.  Add to `resolved_review_items`.
+2.  Mark task `[x]`.
+3.  Mark corresponding Action Item `[x]` in Review Section.
+4.  Log resolution in Completion Notes.
+
+### 3. Mark Complete
+
+**IF All Gates Pass:**
+1.  Mark task/subtask `[x]`.
+2.  Update **File List** (new/modified/deleted files).
+3.  Add **Completion Notes**.
+
+**IF Validation Fails:**
+1.  **HALT**. Do not proceed. Fix issues.
+
+### 4. Loop Decision
+
+1.  Save Story File.
+2.  Check for **Incomplete Tasks**.
+
+**IF Tasks Remain:**
+1.  Load, read entire file, then execute `{nextTaskStep}` (`step-07-implement.md`).
+
+**IF NO Tasks Remain:**
+1.  Load, read entire file, then execute `{completionStep}` (`step-11-mark-review.md`).

package/siesa-agents/bmm/workflows/4-implementation/dev-story/steps/step-11-mark-review.md

@@ -0,0 +1,50 @@
+---
+name: 'step-11-mark-review'
+description: 'Story completion and mark for review'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/dev-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-11-mark-review.md'
+nextStepFile: '{workflow_path}/steps/step-12-communication.md'
+sprintStatusFile: '{implementation_artifacts}/sprint-status.yaml'
+---
+
+# Step 11: Final Validation & Status Update
+
+## STEP GOAL:
+
+Perform final Definition of Done (DoD) validation and update story status to "review".
+
+## EXECUTION PROTOCOLS:
+
+### 1. Final Validation Gates
+
+1.  **Re-scan Story**: Verify ALL tasks `[x]`.
+2.  **Full Regression**: Run suite.
+3.  **File List**: Ensure complete.
+4.  **UI Compliance**: Verify `siesa-ui-kit`.
+5.  **DoD Checklist**:
+    *   ACs met.
+    *   Tests (Unit/Int/E2E) pass.
+    *   Quality checks pass.
+    *   Dev Notes updated.
+
+**IF Validation Fails:** HALT and Fix.
+
+### 2. Update Story Status
+
+1.  Update Story Status section to: `review`.
+
+### 3. Update Sprint Status
+
+**IF `{sprintStatusFile}` EXISTS:**
+1.  Load FULL file.
+2.  Update `development_status[{{story_key}}] = "review"`.
+3.  Save file (preserving comments).
+4.  Output: `✅ Story status updated to "review" in sprint-status.yaml`.
+
+### 4. Next Step
+
+Load, read entire file, then execute `{nextStepFile}` (`step-12-communication.md`).

package/siesa-agents/bmm/workflows/4-implementation/dev-story/steps/step-12-communication.md

@@ -0,0 +1,45 @@
+---
+name: 'step-12-communication'
+description: 'Completion communication and user support'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/dev-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-12-communication.md'
+---
+
+# Step 12: Communication & Handover
+
+## STEP GOAL:
+
+Inform the user of completion, provide a summary, and suggest next steps.
+
+## EXECUTION PROTOCOLS:
+
+### 1. Prepare Summary
+
+1.  Compile key accomplishments: Story ID/Title, Files Modified, Tests Added.
+2.  Summarize from **Completion Notes**.
+
+### 2. User Communication
+
+1.  Output:
+    ```
+    🎉 **Story Implementation Complete**
+    Story: {{story_key}}
+    Status: review
+    Files: {{files_modified_count}}
+    Tests: {{tests_added_summary}}
+    ```
+2.  Provide Story File Path.
+
+### 3. Explanation & Handover
+
+1.  Ask if user needs explanations (Technical decisions, How to test, etc.).
+2.  **IF User Asks**: Provide clear context tailored to skill level.
+3.  **Next Steps**: Suggest running `code-review` workflow.
+
+### 4. Completion
+
+**TERMINATE WORKFLOW.**

package/siesa-agents/bmm/workflows/4-implementation/dev-story/workflow_ext.md

@@ -140,4 +140,10 @@ node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event wor
 
 - If any `sa-emit` call fails, log the error and **continue the workflow normally**. Observability must never block the workflow.
 - Use the exact `{{story_key}}` value as resolved in step-01 (e.g., `1-1-user-authentication`).
-- Do NOT wait for user confirmation to execute these commands — they are silent background operations.
+- Do NOT wait for user confirmation to execute these commands — they are silent background operations.
+---
+
+## 7. Additional Completion Checklist
+
+Before marking a story as complete, verify the Siesa-specific checklist items at:
+`@_siesa-agents/bmm/workflows/4-implementation/dev-story/checklist_ext.md`

package/siesa-agents/bmm/workflows/4-implementation/sprint-planning/workflow_ext.md

@@ -117,3 +117,63 @@ Crear el archivo con la siguiente estructura:
 ## 4. PRIMERA EJECUCIÓN DEL SPRINT-STATUS
 
 Cuando `sprint-status.yaml` NO existe, continuar con el flujo estándar FULL_LOAD sin alteraciones, aplicando las reglas de trazabilidad de la sección 1 y generando el `feature-status.yaml` según la sección 3.
+
+---
+
+## 5. DATE IDEMPOTENCY — STEP 3.5 (Siesa Extension)
+
+**TRIGGER:** Before generating the `sprint-status.yaml` output file (between step 3 and step 4 of the base workflow).
+
+### Step 3.5: Preserve Existing Date Fields
+
+Before writing the output, load any existing date fields to prevent overwriting them:
+
+```
+existing_dates = {}           // map of preserved dates
+original_generated = {date}   // default: today
+
+IF FILE_EXISTS({status_file}):
+  existing_yaml = PARSE_YAML( READ_FILE({status_file}) )
+
+  // Preserve each epic-n-last-update already recorded
+  FOR each key IN existing_yaml.development_status:
+    IF key MATCHES "epic-{n}-last-update":
+      IF existing_yaml.development_status[key] IS NOT EMPTY:
+        existing_dates[key] = existing_yaml.development_status[key]
+
+  // Preserve the original generation date (never bump it on re-runs)
+  IF existing_yaml.generated IS NOT NULL:
+    original_generated = existing_yaml.generated
+```
+
+### Resolution Function (used in Step 4)
+
+```
+FUNCTION resolve_epic_date(epic_n):
+  date_key = "epic-{n}-last-update"
+  IF date_key IN existing_dates:
+    RETURN existing_dates[date_key]   // existing date — DO NOT overwrite
+  ELSE:
+    RETURN {date}                     // new epic — initialize with today
+```
+
+### Rules
+
+- `epic-n-last-update` is initialized ONLY if the key does not already exist in `{status_file}`.
+- Once set, the value is **NEVER** modified by `sprint-planning`.
+- Use `original_generated` (not today's date) for the `generated` field header.
+- Use `resolve_epic_date(n)` for every `epic-n-last-update` — never hardcode `{date}` directly.
+- Running `sprint-planning` multiple times must produce **identical** date fields.
+
+### sprint-status.yaml Date Field Format
+
+Each epic entry must include:
+```yaml
+epic-{n}: {status}
+epic-{n}-last-update: {resolve_epic_date(n)}   # preserved if exists, today if new
+```
+
+### Additional Checklist Item
+
+Before finalizing:
+- [ ] Every epic has a corresponding `epic-n-last-update` entry with a non-empty date value.