vault-scope-boundaries

name	vault-scope-boundaries
description	Patrón de delimitación por ficheros entre módulos hermanos para evitar solapamiento de alcance en el vault
metadata	{"tipo":"decision","proyecto":"AbadIA-MCP","areas":["vault-architecture","scope-design"]}

Vault Scope Boundaries: Delimitación por Ficheros

El Patrón

Cuando dos módulos comparten un directorio fuente (como server-core y server-map comparten server/), el alcance no se delimita por directorios, sino por ficheros específicos. Esta estrategia evita solapamiento de responsabilidades y permite que futures tareas de documentación (task/02 a task/07) trabajen sin ambigüedad sobre qué contenido corresponde a cada módulo.

En el caso de server-core vs server-map, la frontera es tajante:

• server-map abarca: map_definitions.py, map_utils.py, y todo el árbol de api/ (incluyendo api/v1/).
• server-core abarca: el resto de la lógica de runtime, inicialización, y módulos base que no aparecen en la lista anterior.

Esta decisión se materializa en plan.md (línea 28) como "el alcance de cada uno está acotado por ficheros (core = lógica/runtime; map = map_*.py + api/)" y se detalla en task/01.md (líneas 15-17 y línea 28) con el inventario exacto.

Cómo Aplica: Extensión a Agent, Scripts, Tests y Docs

La regla es universal: cuando un módulo documenta una región lógica dentro de un árbol compartido, lista explícitamente los ficheros (o patrones de fichero) que entran en su alcance. Ejemplos de aplicación futura:

1. Agent (task/02): Si el módulo agent contiene un submodule tools-internal/ (herramientas internas del agente) y otro tools-external/ (que invoca servicios externos), la frontera se declara por ruta de fichero. La documentación del vault debe registrar: "agent documenta tools-internal/ y tools-shared.py; no documenta herramientas específicas de otros módulos que viven en external-services/."

2. Scripts (task/03): Si existen scripts de utilidad en scripts/helpers.py que también podrían pertenecer a scripts/exec/ y scripts/tools/, el vault aclara: "documentamos scripts/exec/*.py y scripts/tools/config.py; los scripts de desarrollo en scripts/dev/ siguen otro patrón" (o similar).

3. Tests (task/04): La cobertura no se define por "tests que prueban server/" sino por "tests en tests/unit/server/ y tests/integration/server_api/; tests de smoke en tests/smoke/ se documentan bajo otro módulo o no se incluyen."

4. Docs (task/05): Si hay documentación técnica en docs/ y también en subdirectorios de módulos (p. ej., agent/docs/), la declaración es: "vault-docs documenta docs/*.md y docs/guides/; cada módulo documenta su propio <module>/docs/ en su sección."

Evidencia y Referencia

• plan.md, línea 28: "el alcance de cada uno está acotado por ficheros (core = lógica/runtime; map = map_*.py + api/)."
• task/01.md, líneas 15-17: Restricción de alcance; detalla que "Alcance acotado: solo map_definitions.py, map_utils.py y api/ (incl. api/v1/); NO documentar la lógica/runtime core (eso es server-core)."
• task/01.md, línea 28: Subtarea de "Confirmar el inventario de ficheros en alcance (map_definitions.py, map_utils.py, api/ y api/v1/) y delimitar la frontera con server-core."

Beneficio

Esta regla explícita previene que en tasks futuras haya conflictos sobre si un fichero pertenece a un módulo u otro, reduce la necesidad de revisar o reescribir documentación por ambigüedad de límites, y facilita auditoría: si alguien pregunta "¿por qué este fichero está documentado en agent y no en scripts?", la respuesta apunta a la lista de ficheros acotados en el plan o la config del vault.