fix: formalize tags and related conventions in framework docs

dist/.devtrail/00-governance/AGENT-RULES.md

@@ -125,6 +125,21 @@ Before creating a document, load the corresponding template:
 | INC | `.devtrail/05-operations/incidents/` |
 | TDE | `.devtrail/06-evolution/technical-debt/` |
 
+### Tags and Related
+
+When populating the `tags` and `related` fields in frontmatter:
+
+**Tags:**
+- Use kebab-case keywords: `sqlite`, `api-design`, `gnome-integration`
+- 3 to 8 tags per document describing topic, technology, or component
+- Tags enable search and categorization in `devtrail explore`
+
+**Related:**
+- Reference other **DevTrail documents only** — use the document filename with `.md` extension
+- If the document is in a subdirectory within `.devtrail/`, include the relative path: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-file.md`
+- If the document is in the same directory, the filename alone is sufficient
+- **Do not** put task IDs (T001, US3), issue numbers, or external URLs in `related` — put those in the document body instead
+
 ---
 
 ## 6. Communication with Humans

dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md

@@ -70,11 +70,53 @@ related:
 | Field | Description |
 |-------|-------------|
 | `updated` | Last update date |
-| `tags` | Tags for categorization |
-| `related` | References to related documents |
+| `tags` | Tags for categorization (see conventions below) |
+| `related` | References to related documents (see conventions below) |
 | `supersedes` | ID of the document this one replaces |
 | `superseded_by` | ID of the document that replaces this one |
 
+### Tags Convention
+
+Tags are **free-form keywords** used for categorization and search. They help discover related documents across the project.
+
+**Format rules:**
+- Use **kebab-case** (lowercase, hyphens): `gnome-integration`, `sqlite`, `api-design`
+- One concept per tag — avoid compound tags like `auth-and-security`
+- Recommended range: **3 to 8 tags** per document
+- Tags should describe the **topic**, **technology**, **component**, or **concern** of the document
+
+**Example:**
+```yaml
+tags: [sqlite, persistence, hexagonal-architecture, repository-pattern]
+```
+
+### Related Convention
+
+Related references link documents to other **DevTrail documents** within the same project. They enable cross-navigation in tools like `devtrail explore`.
+
+**Format rules:**
+- Use the **document filename** (with `.md` extension): `AILOG-2026-02-03-001-implement-sync-item.md`
+- For governance or non-typed documents, use the filename as-is: `AGENT-RULES.md`, `DOCUMENTATION-POLICY.md`
+- Paths are resolved relative to `.devtrail/` — if the document is in a subdirectory, include the path from `.devtrail/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implement-sync-item.md`
+- When the file is in the same directory as the referencing document, the filename alone is sufficient
+- **Do not use** external task IDs (`T001`, `US3`), issue numbers, or URLs — those belong in the document body, not in frontmatter
+- **Do not use** partial IDs without description (prefer `AILOG-2026-02-03-001-implement-sync-item.md` over `AILOG-2026-02-03-001`)
+
+**Examples:**
+```yaml
+# Same directory or well-known location — filename is enough
+related:
+  - AIDEC-2026-02-02-001-sqlite-bundled-vs-system.md
+  - AGENT-RULES.md
+
+# Documents in specific subdirectories — include path from .devtrail/
+related:
+  - 07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implement-sync-item.md
+  - 02-design/decisions/ADR-2026-01-15-001-use-hexagonal-architecture.md
+```
+
+**Resolution:** The CLI resolves references by searching: (1) exact ID match, (2) filename match anywhere in `.devtrail/`, (3) path suffix match. Using the full filename provides the most reliable resolution.
+
 ---
 
 ## 3. Document Statuses

dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md

@@ -127,6 +127,21 @@ Antes de crear un documento, cargar la plantilla correspondiente:
 | INC | `.devtrail/05-operations/incidents/` |
 | TDE | `.devtrail/06-evolution/technical-debt/` |
 
+### Tags y Related
+
+Al poblar los campos `tags` y `related` en el frontmatter:
+
+**Tags:**
+- Usar palabras clave en kebab-case: `sqlite`, `api-design`, `gnome-integration`
+- 3 a 8 tags por documento describiendo tema, tecnología o componente
+- Los tags habilitan búsqueda y categorización en `devtrail explore`
+
+**Related:**
+- Referenciar únicamente otros **documentos DevTrail** — usar el nombre de archivo con extensión `.md`
+- Si el documento está en un subdirectorio dentro de `.devtrail/`, incluir la ruta relativa: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-archivo.md`
+- Si el documento está en el mismo directorio, el nombre de archivo es suficiente
+- **No** colocar IDs de tareas (T001, US3), números de issues ni URLs externas en `related` — esos van en el cuerpo del documento
+
 ---
 
 ## 6. Comunicación con Humanos

dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md

@@ -72,11 +72,53 @@ related:
 | Campo | Descripción |
 |-------|-------------|
 | `updated` | Fecha de última actualización |
-| `tags` | Etiquetas para categorización |
-| `related` | Referencias a documentos relacionados |
+| `tags` | Etiquetas para categorización (ver convenciones abajo) |
+| `related` | Referencias a documentos relacionados (ver convenciones abajo) |
 | `supersedes` | ID del documento que este reemplaza |
 | `superseded_by` | ID del documento que reemplaza a este |
 
+### Convención de Tags
+
+Los tags son **palabras clave de formato libre** usadas para categorización y búsqueda. Ayudan a descubrir documentos relacionados en todo el proyecto.
+
+**Reglas de formato:**
+- Usar **kebab-case** (minúsculas con guiones): `gnome-integration`, `sqlite`, `api-design`
+- Un concepto por tag — evitar tags compuestos como `auth-y-seguridad`
+- Rango recomendado: **3 a 8 tags** por documento
+- Los tags deben describir el **tema**, **tecnología**, **componente** o **preocupación** del documento
+
+**Ejemplo:**
+```yaml
+tags: [sqlite, persistencia, hexagonal-architecture, repository-pattern]
+```
+
+### Convención de Related
+
+Las referencias relacionadas vinculan documentos con otros **documentos DevTrail** dentro del mismo proyecto. Permiten navegación cruzada en herramientas como `devtrail explore`.
+
+**Reglas de formato:**
+- Usar el **nombre del archivo** del documento (con extensión `.md`): `AILOG-2026-02-03-001-implementar-sincronizacion.md`
+- Para documentos de gobernanza u otros sin tipo, usar el nombre tal cual: `AGENT-RULES.md`, `DOCUMENTATION-POLICY.md`
+- Las rutas se resuelven relativas a `.devtrail/` — si el documento está en un subdirectorio, incluir la ruta desde `.devtrail/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implementar-sincronizacion.md`
+- Cuando el archivo está en el mismo directorio que el documento que lo referencia, el nombre de archivo es suficiente
+- **No usar** IDs de tareas externas (`T001`, `US3`), números de issues ni URLs — esos pertenecen al cuerpo del documento, no al frontmatter
+- **No usar** IDs parciales sin descripción (preferir `AILOG-2026-02-03-001-implementar-sincronizacion.md` sobre `AILOG-2026-02-03-001`)
+
+**Ejemplos:**
+```yaml
+# Mismo directorio o ubicación conocida — el nombre de archivo es suficiente
+related:
+  - AIDEC-2026-02-02-001-sqlite-bundled-vs-system.md
+  - AGENT-RULES.md
+
+# Documentos en subdirectorios específicos — incluir ruta desde .devtrail/
+related:
+  - 07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implementar-sincronizacion.md
+  - 02-design/decisions/ADR-2026-01-15-001-usar-arquitectura-hexagonal.md
+```
+
+**Resolución:** El CLI resuelve referencias buscando: (1) coincidencia exacta de ID, (2) coincidencia de nombre de archivo en cualquier parte de `.devtrail/`, (3) coincidencia de sufijo de ruta. Usar el nombre de archivo completo proporciona la resolución más confiable.
+
 ---
 
 ## 3. Estados de Documentos

dist/DEVTRAIL.md

@@ -147,9 +147,25 @@ agent: your-agent-id-v1.0
 confidence: high | medium | low
 review_required: true | false
 risk_level: low | medium | high | critical
+tags: [oauth, authentication, api]
+related:
+  - ADR-2025-01-20-001-use-jwt-tokens.md
 ---
 ```
 
+### Tags
+
+- Use **kebab-case** keywords: `sqlite`, `api-design`, `gnome-integration`
+- 3 to 8 tags per document — describe topic, technology, or component
+- Tags enable search and categorization in `devtrail explore`
+
+### Related
+
+- Reference other **DevTrail documents** by filename (with `.md`): `AILOG-2025-01-27-001-implement-oauth.md`
+- For documents in subdirectories, include path from `.devtrail/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-file.md`
+- For documents in the same directory, filename alone is sufficient
+- **Do not** use task IDs, issue numbers, or URLs — those go in the document body
+
 ---
 
 ## 9. Autonomy Limits