context-map-ai 2.0.0__tar.gz

context_map_ai-2.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: 🐛 Bug Report / Reporte de Error
+about: Create a report to help us improve ContextMap
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## 🐛 Description / Descripción
+A clear and concise description of what the bug is. / Una descripción clara y concisa de lo que es el error.
+
+## 🔄 Steps to Reproduce / Pasos para Reproducir
+1. Go to / Ir a '...'
+2. Run command / Ejecutar comando '...'
+3. See error / Ver el error
+
+## 🎯 Expected Behavior / Comportamiento Esperado
+A clear and concise description of what you expected to happen.
+
+## 💻 Environment / Entorno
+- **OS:** [e.g. Windows 11 / Ubuntu 24.04 / macOS Sequoia]
+- **Python Version:** [e.g. 3.11.5]
+- **ContextMap Version:** [e.g. 1.9.0]
+- **AI Agent / IDE:** [e.g. Antigravity / Cursor / Claude Code / Hermes]
+
+## 📋 Error Logs / Traza de Error
+```text
+// Paste logs here / Pega los logs aquí
+```

context_map_ai-2.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: 🚀 Feature Request / Solicitud de Funcionalidad
+about: Suggest an idea or improvement for ContextMap
+title: '[FEAT] '
+labels: enhancement
+assignees: ''
+---
+
+## 💡 Is your feature request related to a problem? / ¿Está relacionada con un problema?
+A clear description of what the problem is (e.g. "I'd like to export context to...").
+
+## 🎨 Proposed Solution / Solución Propuesta
+A clear description of what you want to happen or how you imagine the feature.
+
+## ⚖️ Alternatives Considered / Alternativas Consideradas
+Any alternative solutions or features you've considered.
+
+## 📝 Additional Context / Contexto Adicional
+Add any other context or screenshots about the feature request here.

context_map_ai-2.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+## 📌 Tipo de Cambio
+
+- [ ] 🐛 Corrección de error (Bug fix)
+- [ ] ✨ Nueva funcionalidad (Feature)
+- [ ] ♻️ Refactorización de código (Refactor / Clean Code)
+- [ ] 📝 Actualización de documentación (Docs)
+- [ ] 🧪 Adición o corrección de pruebas (Tests)
+
+---
+
+## 📝 Descripción de los Cambios
+Proporciona un resumen claro de los cambios introducidos y el problema que resuelven.
+
+---
+
+## 🎯 Lista de Verificación (Checklist)
+
+- [ ] Mi código sigue las normas de `AGENTS.md` (Español Técnico, Google Style Docstrings, Type Hinting).
+- [ ] He ejecutado la suite de pruebas unitarias (`python -m pytest`) y todas pasan al 100% en verde.
+- [ ] He verificado la topología de árbol de Obsidian (`test_topologia_arbol.py`) sin wikilinks rotos.
+- [ ] He ejecutado `python -m context_map.cli refresh .` para actualizar el brief y el vault.
+- [ ] No he incluido información sensible, credenciales o API keys.

context_map_ai-2.0.0/.github/copilot-instructions.md

@@ -0,0 +1,34 @@
+# GitHub Copilot — Instrucciones para ContextMap
+
+> Generado automáticamente por **ContextMap** (2026-08-12).
+
+## Antes de sugerir código
+
+- Revisa `.context-map/CONTEXT.md` para entender el proyecto (stack, riesgos, tareas).
+- Respeta la arquitectura modular existente.
+- Usa convenciones del proyecto: docstrings en español, type hints estrictos.
+
+## Verificación
+
+- Tests: `python -m pytest`
+- ContextMap: `python -m context_map.cli build --clean --brief`
+
+
+<!-- CONTEXTMAP:BEGIN -->
+
+# GitHub Copilot — Instrucciones para ContextMap
+
+> Generado automáticamente por **ContextMap** (2026-08-18).
+
+## Antes de sugerir código
+
+- Revisa `.context-map/CONTEXT.md` para entender el proyecto (stack, riesgos, tareas).
+- Respeta la arquitectura modular existente.
+- Usa convenciones del proyecto: docstrings en español, type hints strictly.
+
+## Verificación
+
+- Tests: `python -m pytest`
+- ContextMap: `python -m context_map.cli build --clean --brief`
+
+<!-- CONTEXTMAP:END -->

context_map_ai-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    name: Tests (pytest)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Instalar dependencias
+        run: uv sync --dev --all-extras
+      - name: Ejecutar tests
+        run: uv run pytest -q
+
+  lint:
+    name: Lint (ruff · bloqueante)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Instalar dependencias
+        run: uv sync --dev --all-extras
+      - name: Ruff check
+        run: uv run ruff check context_map/

context_map_ai-2.0.0/.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: 🌐 Deploy MkDocs Documentation
+
+on:
+  push:
+    branches:
+      - master
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocs-material pymdown-extensions
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

context_map_ai-2.0.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: 📦 Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  pypi-publish:
+    name: Build and publish Python distribution to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Requerido para PyPI Trusted Publisher (OIDC)
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine hatchling
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package artifacts
+        run: twine check dist/*
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

context_map_ai-2.0.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+.pytype/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Context Map (generated)
+.context-map/
+
+# Logs
+*.log

context_map_ai-2.0.0/.hermes/config.yaml

@@ -0,0 +1,58 @@
+# Configuración del agente Hermes para ContextMap
+# Generado automáticamente por ContextMap — adaptado al stack detectado
+
+project:
+  name: "ContextMap"
+  description: "Proyecto gestionado con ContextMap"
+  language: "Python"
+  architecture: "Modular (gobernanza por ContextMap)"
+
+agent:
+  instructions: ".context-map/CONTEXT.md"
+  language_style:
+    code: "es"
+    messages: "es"
+    commit_messages: "es"
+
+workflows:
+  dev_loop: ".hermes/workflows/dev-loop.md"
+  test_loop: ".hermes/workflows/test-loop.md"
+
+shields:
+  pre_commit: ".hermes/shields/pre-commit.md"
+  quality: ".hermes/shields/quality-gate.md"
+
+triggers:
+  post_commit: ".hermes/triggers/post-commit.md"
+
+
+<!-- CONTEXTMAP:BEGIN -->
+
+# Configuración del agente Hermes para ContextMap
+# Generado automáticamente por ContextMap — adaptado al stack detectado
+
+project:
+  name: "ContextMap"
+  description: "Proyecto gestionado con ContextMap"
+  language: "Python"
+  architecture: "Modular (gobernanza por ContextMap)"
+
+agent:
+  instructions: ".context-map/CONTEXT.md"
+  language_style:
+    code: "es"
+    messages: "es"
+    commit_messages: "es"
+
+workflows:
+  dev_loop: ".hermes/workflows/dev-loop.md"
+  test_loop: ".hermes/workflows/test-loop.md"
+
+shields:
+  pre_commit: ".hermes/shields/pre-commit.md"
+  quality: ".hermes/shields/quality-gate.md"
+
+triggers:
+  post_commit: ".hermes/triggers/post-commit.md"
+
+<!-- CONTEXTMAP:END -->

context_map_ai-2.0.0/.hermes/shields/pre-commit.md

@@ -0,0 +1,24 @@
+# Escudo Pre-Commit — ContextMap
+
+## Verificaciones obligatorias
+
+- [ ] Tests pasan: `python -m pytest`
+- [ ] Sin secretos en el diff (api_key, password, .env)
+- [ ] Sin archivos huérfanos en la raíz (PLAN.md, NOTAS.txt)
+- [ ] ContextMap actualizado: `python -m context_map.cli build --clean --brief`
+- [ ] Conventional Commits en español
+
+
+<!-- CONTEXTMAP:BEGIN -->
+
+# Escudo Pre-Commit — ContextMap
+
+## Verificaciones obligatorias
+
+- [ ] Tests pasan: `python -m pytest`
+- [ ] Sin secretos en el diff (api_key, password, .env)
+- [ ] Sin archivos huérfanos en la raíz (PLAN.md, NOTAS.txt)
+- [ ] ContextMap actualizado: `python -m context_map.cli build --clean --brief`
+- [ ] Conventional Commits en español
+
+<!-- CONTEXTMAP:END -->

context_map_ai-2.0.0/.hermes/triggers/post-commit.md

@@ -0,0 +1,20 @@
+# Post-Commit — ContextMap
+
+Después de cada commit:
+
+1. Verifica que `python -m context_map.cli build --clean --brief` se ejecutó (hook pre-commit).
+2. Si el commit tocó dependencias: actualiza el lockfile del gestor de paquetes.
+3. Si el commit tocó arquitectura: revisa que el vault 4.0-RIESGOS no marcó nueva deuda.
+
+
+<!-- CONTEXTMAP:BEGIN -->
+
+# Post-Commit — ContextMap
+
+Después de cada commit:
+
+1. Verifica que `python -m context_map.cli build --clean --brief` se ejecutó (hook pre-commit).
+2. Si el commit tocó dependencias: actualiza el lockfile del gestor de paquetes.
+3. Si el commit tocó arquitectura: revisa que el vault 4.0-RIESGOS no marcó nueva deuda.
+
+<!-- CONTEXTMAP:END -->

context_map_ai-2.0.0/.hermes/workflows/dev-loop.md

@@ -0,0 +1,26 @@
+# Dev Loop — ContextMap
+
+Ciclo de trabajo estándar (generado por ContextMap):
+
+1. **Entender**: lee `.context-map/CONTEXT.md` y el vault del proyecto.
+2. **Planificar**: define el cambio antes de escribir código.
+3. **Implementar**: respeta la arquitectura modular existente.
+4. **Verificar**: ejecuta `python -m pytest` (100% en verde).
+5. **ContextMap**: `python -m context_map.cli scan . && python -m context_map.cli build --clean --brief`.
+6. **Commit**: Conventional Commits en español.
+
+
+<!-- CONTEXTMAP:BEGIN -->
+
+# Dev Loop — ContextMap
+
+Ciclo de trabajo estándar (generado por ContextMap):
+
+1. **Entender**: lee `.context-map/CONTEXT.md` y el vault del proyecto.
+2. **Planificar**: define el cambio antes de escribir código.
+3. **Implementar**: respeta la arquitectura modular existente.
+4. **Verificar**: ejecuta `python -m pytest` (100% en verde).
+5. **ContextMap**: `python -m context_map.cli scan . && python -m context_map.cli build --clean --brief`.
+6. **Commit**: Conventional Commits en español.
+
+<!-- CONTEXTMAP:END -->

context_map_ai-2.0.0/.pre-commit-hooks.yaml

@@ -0,0 +1,7 @@
+- id: context-map
+  name: ContextMap Auto Sync
+  description: Escanea y actualiza automáticamente la bóveda de Obsidian y briefs de ContextMap antes de cada commit.
+  entry: ctxmap build --clean --brief --quiet
+  language: python
+  stages: [pre-commit]
+  types: [python, markdown, yaml, json]

context_map_ai-2.0.0/AGENTS.md

@@ -0,0 +1,213 @@
+# Instrucciones para Agentes de IA — Context Map
+
+Este documento establece las normas obligatorias, arquitectura y flujo de trabajo que **todos los Agentes de Inteligencia Artificial** (Antigravity, Cursor, Hermes, Claude, Windsurf, Copilot, etc.) deben seguir sin excepción al interactuar con este repositorio.
+
+---
+
+## 1. Reglas Globales de Comunicación y Código
+
+* **Idioma**: Todas las respuestas, explicaciones y docstrings deben redactarse exclusivamente en **Español Técnico Profesional**.
+* **Documentación**: Todo código generado debe incluir comentarios descriptivos y **Docstrings** formales (Google Style / PEP 257) en funciones, clases y módulos.
+* **Tipado Fuerte**: Uso estricto de **Type Hinting** en Python (`List[Node]`, `Tuple[str, int]`, `Optional[Dict]`, etc.).
+* **Limpieza de Raíz**: No crear archivos sueltos en la raíz (`PLAN.md`, `ROADMAP.txt`). Mantener únicamente los archivos de configuración e identidad (`README.md`, `LICENSE`, `pyproject.toml`, `AGENTS.md`, `.gitignore`).
+
+---
+
+## 2. Arquitectura de Código (Clean Architecture Jerárquica)
+
+El código de `context_map` está organizado bajo el principio de responsabilidad única en la convención `modulo/submodulo/archivo.py`:
+
+```
+context_map/
+├── core/                        # Fundamentos del dominio
+│   ├── models/                  # Dataclasses (Node, Edge, Event)
+│   ├── parsing/                 # Parser de eventos y deserialización JSONL
+│   ├── storage/                 # Persistencia JSONL y snapshots
+│   ├── normalization/           # Estandarización y clasificación semántica
+│   └── generators/              # Generadores de resúmenes y Contexto Narrativo
+├── domain/                      # Lógica de negocio
+│   ├── scanning/                # Escáner estático del proyecto
+│   ├── synchronization/         # Sincronización incremental del grafo
+│   ├── ingestion/               # Ingesta de documentos externos (MD/TXT/PDF → DOCUMENTO)
+│   ├── ecosystem/               # Detección de stack/IDE y adaptación de reglas agénticas
+│   ├── analysis/                # Análisis de readiness del sistema
+│   ├── health/                  # Diagnóstico y mantenimiento (doctor)
+│   └── reporting/               # Reportes semanales de avance
+├── application/                 # CLI y orquestación
+│   ├── cli/                     # Parser principal de argumentos CLI
+│   └── commands/                # Comandos unificados (build, scan, sync, etc.)
+├── infrastructure/              # Integraciones externas
+│   ├── integrations/            # Git, Hermes, Antigravity, Chat exports
+│   └── analyzers/               # Analizadores AST de estructura y contenido
+└── presentation/                # Generación de salidas visuales
+    ├── vault/                   # Generador de Vault Obsidian (atomic, consolidated, templates)
+    └── briefs/                  # Generador de CONTEXT.md para Agentes
+```
+
+---
+
+## 3. Protocolo de Inicio para Agentes (Ponerse en Contexto)
+
+Cualquier agente que tome una tarea en este proyecto **DEBE** seguir estos pasos obligatorios antes de escribir o modificar código:
+
+1. **Verificar el PROYECTO correcto**: el vault de ESTE proyecto es
+   `.context-map/vault-ContextMap/`. Si el usuario pregunta por OTRO proyecto (p. ej.
+   mi-app-utm) o por un vault que no es este, dilo ANTES de responder — nunca
+   respondas con el contexto de otro proyecto.
+2. **Leer el Brief Ejecutivo**:
+   Consultar [.context-map/CONTEXT.md](file:///c:/Users/jose.cespedes/Desktop/PruebaContext/.context-map/CONTEXT.md) para conocer las métricas, riesgos críticos y tareas pendientes.
+3. **Comprobar la FRESCURA del contexto**: si el brief avisa que el diario manual
+   es más nuevo que el build (sección "Estado del Contexto"), ejecuta
+   `ctxmap refresh .` ANTES de responder sobre el estado del proyecto.
+4. **Leer los PENDIENTES REALES**: además del backlog generado (5.0-BACKLOG),
+   revisa SIEMPRE `.context-map/vault-ContextMap/7.0-MANUAL/BACKLOG.md` (si existe)
+   y el diario más reciente (`7.0-MANUAL/Diario/`). Los pendientes conversados con
+   el usuario viven ahí.
+5. **Revisar el Backlog y Vault**:
+   Inspeccionar `.context-map/vault-ContextMap/2.0-IDEAS/2.1-Ideas-Pendientes/` y `5.0-BACKLOG/5.1-Tareas.md`.
+6. **No Suponer Rutas o Lógica**:
+   Inspeccionar el código fuente antes de formular hipótesis de cambio.
+
+> ⚠️ **NUNCA respondas "¿qué quedó pendiente?" basándote solo en un documento
+> suelto (auditoría, CHANGELOG, docs/)** — cruza SIEMPRE el brief + backlog manual
+> + diario más reciente. Esa es la fuente de verdad del proyecto.
+
+---
+
+## 4. Topología Estricta en Árbol para Obsidian (Graph View) — REGLA INAMOVIBLE
+
+> **Esta es la regla MÁS IMPORTANTE del renderizador. Ningún agente, refactor
+> o "mejora" puede violarla. El Graph View de Obsidian DEBE verse como un
+> árbol puro: cada nota cuelga de EXACTAMENTE UN padre, las ramas de ideas
+> pendientes (2.1), futuras (2.2) y completadas (2.3) son INDEPENDIENTES y
+> NUNCA se cruzan entre sí ni con otras secciones.**
+
+### 4.1 Estructura del Árbol (obligatoria)
+
+```
+00-INDICE.md                      ← raíz (padre de todos)
+├── 1.0-PROPOSITO/                ← sección raíz
+│   └── 1.1, 1.2, 1.3             ← hojas → SOLO a su sección padre
+├── 2.0-IDEAS/                    ← sección raíz
+│   ├── 2.1-Ideas-Pendientes/     ← RAMA INDEPENDIENTE
+│   │   └── DEVOPS/DEVOPS-Pendientes.md      ← índice de concepto (nombre ÚNICO)
+│   │       └── idea_*.md                     ← nota → SOLO a su índice
+│   ├── 2.2-Ideas-Futuras/        ← RAMA INDEPENDIENTE (solo si hay activas)
+│   │   └── CONCEPTO/CONCEPTO-Futuras.md
+│   ├── 2.3-Ideas-Completas-e-Implementadas/  ← RAMA INDEPENDIENTE
+│   │   └── DEVOPS/DEVOPS-Completas.md
+│   │       └── 01-DEVOPS-01-10.md            ← batch → SOLO a su índice
+│   └── 2.4-Ideas-Relevantes.md
+├── 3.0-ESTRUCTURA/ → 3.1
+├── 4.0-RIESGOS/ → notas de riesgo
+├── 5.0-BACKLOG/ → 5.1
+└── 6.0-HISTORIAL/ → 6.1, 6.2, 6.3
+```
+
+### 4.2 Reglas Obligatorias (violarlas = bug)
+
+1. **CADA NOTA TIENE EXACTAMENTE UN PADRE** (árbol puro). El padre se
+   materializa como el ÚNICO wikilink con `⬅` (pie "Volver a..."). Ningún
+   nodo enlaza a más de un nivel superior, ni a nodos hermanos, ni entre
+   secciones de estado, ni a `00-INDICE.md` (salvo las 6 secciones raíz).
+2. **Nivel 0 (`00-INDICE.md`)**: Enlaza **únicamente** a los 6 Nodos de
+   Sección Raíz (`1.0`, `2.0`, `3.0`, `4.0`, `5.0`, `6.0`).
+3. **Nivel 1 (Secciones Raíz `X.0`)**: Enlazan a `00-INDICE.md` (su padre)
+   y a sus sub-nodos `X.Y` (sus hijos). Nada más.
+4. **Nivel 2 y Nodos Hoja**: Enlazan **exclusivamente a su Sección Padre**
+   vía el pie `⬅ Volver a ...`. NUNCA de regreso a `00-INDICE.md`.
+5. **Índices de concepto con nombre ÚNICO por estado**:
+   `{CONCEPTO}-Pendientes.md`, `{CONCEPTO}-Futuras.md`, `{CONCEPTO}-Completas.md`.
+   NUNCA `{CONCEPTO}.md` a secas: Obsidian fusiona archivos con el mismo
+   nombre base y mezclaría ideas pendientes con completas.
+6. **PROHIBIDO enlazar por nombre corto ambiguo**: todo wikilink a un índice
+   de concepto usa su nombre único completo (con sufijo de estado). Las notas
+   de idea muestran el concepto como texto plano (`` ``Concepto`` ``), SIN
+   wikilink adicional al índice (el pie ya enlaza al padre).
+7. **Los batches de ideas completadas se nombran `NN-CONCEPTO-INICIO-FIN.md`
+   y su índice DEBE enlazar a los batches reales** (nunca a `idea_*.md`
+   inexistentes → nodos fantasma).
+8. **Enlaces a sub-secciones condicionales**: `2.0-IDEAS.md` solo enlaza a
+   `2.1` / `2.2` / `2.3` si existen nodos de ese estado. Enlaces rotos =
+   nodos fantasma = bug.
+9. **`00-CONEXIONES.md` en modo jerárquico se renderiza SIN wikilinks**
+   (`con_wikilinks=False`): los nombres de archivo del modo jerárquico no
+   derivan del slug del título, así que los wikilinks crearían nodos fantasma.
+
+### 4.3 Verificación Automática (inamovible)
+
+- El test `context_map/__tests__/test_topologia_arbol.py` DEBE pasar antes
+  de cualquier commit (verificado por `python -m pytest`). Comprueba:
+  - 0 nodos sin padre (excepto `00-INDICE.md` y `00-CONEXIONES.md`)
+  - 0 colisiones de nombre base entre archivos del vault
+  - 0 wikilinks rotos (target que no existe como archivo)
+  - Cada índice de concepto termina en `-Pendientes/-Futuras/-Completas.md`
+- El **pre-commit hook** regenera el vault con el código LOCAL
+  (`python -m context_map.cli build`) — NUNCA con el binario global `ctxmap`
+  desactualizado. Si el vault generado no pasa 4.3, el commit está roto.
+
+### 4.4 Vault ÚNICO por proyecto
+
+- El vault activo es `.context-map/vault-<NombreProyecto>` (ej:
+  `vault-ContextMap`, sin guión extra). El nombre lo resuelve el repo GitHub.
+- PROHIBIDO acumular vaults paralelos obsoletos (`vault-Context-Map`,
+  `vault-TestAuto`, etc.): cualquier vault que no se regenera por `build`
+  debe moverse a `.context-map/_legacy/` o eliminarse. Solo debe existir UN
+  vault por proyecto para que Obsidian no mezcle grafos.
+- **Sincronización Multi-Vault**: Todo cambio en `build` debe renderizarse
+  en `.context-map/vault/` y en `.context-map/vault-<project>/`
+  simultáneamente para que la vista de Obsidian se actualice en tiempo real.
+
+---
+
+## 5. Metodología de Contexto Narrativo con Alma
+
+Toda nota generada para una entidad en el Vault debe invocar `generar_contexto_narrativo(node)` en `context_map/core/generators/generadores.py` para inyectar su estructura polimórfica según el tipo de nodo:
+
+* **`IDEA`**: ¿Por qué?, ¿De dónde surgió?, ¿Para qué?, ¿Cómo?, y tabla de **Pros y Contras**.
+* **`RIESGO`**: ¿Qué riesgo es?, Ubicación, Impacto, Mitigación y **Matriz de Gravedad**.
+* **`CAMBIO` / `CORRECCION`**: Modificación realizada, Razón del cambio, Archivos y **Verificación de No-Regresión**.
+* **`BASE`**: Componente estructural, **Rol en la Arquitectura** e integraciones.
+* **`PRUEBA`**: Funcionalidad validada, Criterios de Aceptación y comando `pytest`.
+* **`FUTURO`**: Tarea pendiente (TODO), Ubicación en código y Prioridad.
+
+### 5.1 HUMANIZAR TODOS LOS ARCHIVOS (regla obligatoria)
+
+Al actualizar el contexto, el agente debe revisar y **redactar TODOS los
+archivos del vault** (no solo `7.0-MANUAL/`): índices con propósito (no
+conteos), narrativas sin plantillas vacías, títulos legibles, riesgos
+deduplicados, historia con los mensajes reales, ideas con alma. **Guardar
+siempre el contexto**: nunca borrar información con historia ni notas
+manuales — lo tosco se redacta, no se elimina.
+
+### 5.2 MEMORIA VIVA DEL PROYECTO (regla fundamental)
+
+ContextMap es la **memoria del proyecto**, mantenida constantemente por el
+agente: si durante el trabajo surge una idea, decisión o lección, se
+**documenta automáticamente** (sin esperar a que lo pidan) en la nota del
+día (`7.0-MANUAL/Diario/`) y, si es reutilizable, como conocimiento
+accionable en `8.0-KNOWLEDGE/` (formato: Lección · Cómo se resolvió ·
+Prompt específico · Instrucción específica · Conexiones). Lo conversado
+siempre queda.
+
+---
+
+## 6. Verificación Obligatoria y Commits
+
+Antes de dar por completada cualquier tarea o comitear en Git:
+
+```bash
+# 1. Ejecutar tests unitarios (deben pasar 100%)
+python -m pytest
+
+# 2. Escanear y actualizar el mapa de contexto
+python -m context_map.cli scan .
+
+# 3. Reconstruir la bóveda de Obsidian y el brief de contexto
+python -m context_map.cli build --clean --brief
+
+# 4. Verificar readiness
+python -m context_map.cli check .
+```
+
+* **Mensajes de Commit**: Usar la convención *Conventional Commits* en español (ej. `feat: ...`, `fix: ...`, `refactor: ...`, `docs: ...`).