Eje 5: Procedimientos

Onboarding de pymes

El acceso de las pymes a la compliance nativa de Git sigue un camino paso a paso:

1. Inicializar el repositorio Git — estructura con el directorio .gitcover/, configuración V7GUID
2. Seleccionar el catálogo OSCAL — línea base GoBD, módulos BSI o perfil individual
3. Activar las políticas OPA — Pre-receive-Hooks para la validación previa al commit
4. Configurar la firma GPG — un par de claves GPG por actor
5. Iniciar la cadena de comprobantes — asignar los primeros V7GUIDs, comenzar el encadenamiento prev-hash

Para emprendedores desde el nivel de actividad secundaria

El inicio puede darse con una historia muy sencilla: GCDMS para el archivado de comprobantes, GCPN para las cadenas de evidencia. Ampliación posterior: políticas OSCAL, validación OPA, multi-tenant.

Onboarding interactivo: la «Compliance City»

En lugar de cuestionarios clásicos, el onboarding se realiza como una construcción modular según el concepto de una ciudad sobre una placa base de Lego. Cada decisión arquitectónica y cada requisito funcional corresponde a un bloque o a un conjunto de bloques (set de Lego) que se deposita y versiona como módulo estructurado en el repositorio Git por defecto recién inicializado.

La analogía para el usuario:

• La placa base: el repositorio Git vacío, recién creado para el tenant en su infraestructura. Ofrece el marco normalizado (los tetones) sobre el que todo se acopla.
• Los bloques: configuración modular y archivos de servicio. Solo cuando un bloque encaja en su posición (commit de Git), se activa la función correspondiente o la verificación de compliance.

Fase 1 — Colocar la placa base (inicialización e identidad):

El sistema crea automáticamente el repositorio por defecto para el tenant. El asistente de onboarding determina la identidad de la empresa. Los datos se depositan de forma estructurada en el repositorio 'TOP' (Tenant Organization Profile); el primer commit de Git ya es el primer proceso de compliance auditable. Por cierto: los tenants también pueden organizarse jerárquicamente, al igual que las estructuras empresariales a las que pertenecen.

Fase 2 — Cableado de la infraestructura (red de suministro):

El asistente registra el panorama de TI: puesto de trabajo con portátil, servidor de archivos, infraestructura cloud-first o híbrida. Parámetros como la conexión a Internet, el dominio, las rutas de almacenamiento, etc. se incorporan a la información de infraestructura y preparan las rutas para las conexiones transversales (others.json).

Fase 3 — Construir los edificios (alcance funcional):

El usuario decide de forma modular qué ámbitos regulatorios debe cubrir su ciudad:

El usuario no ve en ningún momento archivos de configuración ni código. Dado que cada paso genera de inmediato un commit de Git limpio, el sistema está documentado desde el primer minuto de forma completamente a prueba de auditoría conforme a GoBD y AO.

Aislamiento de mandantes y control de acceso

Claims de OIDC y others.json

La vinculación de los claims de OIDC con el archivo others.json es el camino real para entornos de compliance multi-mandante y seguros para usuarios no expertos. En others.json se recopilan:

1. Rutas canónicas hacia los repositorios Git propios del tenant
2. Conexiones transversales hacia repositorios Git de otros tenants, cuando el tenant es miembro de un grupo

El acceso se controla mediante claims de OIDC (roles y custom claims como tenant_id, org_unit_id y pertenencias a grupos). Una Inlet-Pipeline lee el archivo others.json según el claim del usuario e inyecta las rutas permitidas como system prompt:

Eres el agente de GitCover para el mandante X. Tienes acceso exclusivamente a los siguientes repositorios: [Ruta 1], [Ruta 2]. No ejecutes ningún comando fuera de estos directorios.

Modelo de claims de dos niveles para el acceso a PII

Para el acceso a datos personales (PII), el GCBoK define una jerarquía de claims con dos niveles (véase Técnicas: Git como IdP:

El archivo others.json mapea estos claims a rutas de repositorio:

{
  "tenant_id": "0197a3b2-f3c0-7b00-8001-000000000042",
  "org_unit_id": "ORG-1-Portfolio",
  "allowed_repos": [
    "TOP",
    "PII/ORG-1-Portfolio"
  ]
}

Un usuario con org_unit_id = ORG-1-Portfolio obtiene acceso a PII/ORG-1-Portfolio, pero no a PII/ORG-2-IT — incluso con el mismo tenant_id. Esto implementa el principio de mínimo privilegio (NIS2 Art. 21) a nivel de repositorio.

Para el usuario final, este aparato de seguridad permanece invisible. Inicia sesión, ve su entorno de trabajo habitual y la IA sabe automáticamente dónde puede actuar.

Captura de datos asistida por IA mediante Formular-Bridging

Las interfaces de chat son adecuadas para contextos y análisis, no para la captura estricta de tipos de datos (IBAN, códigos postales, esquemas OSCAL). Por ello, el GCBoK recomienda un Formular-Bridging:

1. La IA detecta la necesidad: el usuario dice «Quiero añadir un nuevo centro de trabajo».
2. URL de formulario dinámica: la IA emite un enlace a un formulario de entrada web validado (Blazor WASM/PWA), acoplado a la gestión de sesiones y de usuarios.
3. Entrada encapsulada: el usuario rellena el formulario, con validación estricta antes del almacenamiento.
4. Escritura directa en Git: el formulario escribe el resultado como archivo estructurado directamente en el working directory del repositorio del mandante y dispara el commit.
5. La IA retoma el control: el servidor MCP informa «Archivo actualizado» y la IA lo confirma en el chat.

Ventaja: la validación antes del almacenamiento protege la Single Source of Truth. Los LLM no manipulan el proceso de escritura. La validación mediante Git-Hook/OPA se activa de inmediato.

La estructura de directorios .gitcover/

El directorio .gitcover/ en la raíz de un repositorio GitCover es el archivo central para todos los artefactos que no son código. Sirve para la seguridad de revisión, la compliance (GoBD/AO) y el mantenimiento del audit trail.

Disposición de directorios

.gitcover/
├── issues/              # Gitea-Issues als .v7g.md
├── projects/            # Projekt-Management-Daten
├── time_tracking/       # Zeiterfassung und Aufwandsnachweise
├── workflows/           # Workflow-Zustände und Genehmigungen
├── compliance/
│   ├── oscals/          # OSCAL-Dokumente (System Security Plans)
│   ├── opa/             # OPA-Regeln (Rego-Policies)
│   └── hooks/           # Git-Hooks für Automatisierung
├── audit/
│   ├── signatures/      # Kryptografische Signaturen
│   ├── timestamps/      # Zeitstempel (ELSTER/Bundesanzeiger)
│   └── logs/            # Protokolle
└── README.md            # Dokumentation der Struktur

Convención de nombres de archivo

Formato general: {uuidV7}_{human-readable-key}_{Beschreibung}.v7g.md

Esquema de metadatos (frontmatter del .v7g.md)

---
uuid: 018e312f-3e4f-7000-8000-000000000000
key: "#123"
type: "issue"
title: "Bugfix: Login-Modul"
original_source: "Gitea"
original_repo_hash: "a1b2c3d4e5f6..."
related_commits: ["abc123", "def456"]
related_elements:
  project: "Projekt-X"
  milestone: "v1.0"
forensic_attributes:
  created_at: "2026-06-29T12:00:00Z"
  updated_at: "2026-06-29T14:30:00Z"
  created_by: "Person A"
compliance:
  gobd_relevant: true
  audit_trail: true
  signature: "GPG-Signatur-Hash"
  timestamp: "ELSTER-2026-06-29-120000"
---

Automatización mediante Git-Hooks y webhooks

Los repos de GitCover se configuran automáticamente con hooks/webhooks durante el init o el onboarding del tenant:

• post-commit: actualiza .gitcover/ con los nuevos commits
• pre-push: valida .gitcover/ antes del push
• Webhooks: creación de issues, cambios de proyecto, registro de tiempo — cada uno dispara la exportación como .v7g.md
• Compliance-Claim: activación inmediata de los mecanismos OSCAL/OPA

La versionación de estos hooks/webhooks también se realiza mediante Git, de modo que los cambios son trazables y auditables (autorreferentes, versionados, a prueba de auditoría). Los hooks en sí pueden ser artefactos de código versionados que residen en .gitcover/hooks/, se actualizan según sea necesario y se documentan de conformidad con GoBD o NIS2.

Sidecars de V7GUID

Un sidecar V7GUID es un archivo de metadatos *.v7g.md que se deposita junto a un documento original digital; por ejemplo, Rechnung_2026.pdf recibe un Rechnung_2026.pdf.v7g.md en el mismo directorio. El sidecar contiene los metadatos que Git no puede almacenar dentro de un archivo binario (PDF, DOCX, EML, imagen) y ancla así el original en la cadena de comprobantes y en el GCDMS.

Información mínima

Cada sidecar contiene obligatoriamente:

• sha256 — hash SHA-256 del documento original digital (prueba de integridad).

De manera complementaria, registra por regla general identidad, taxonomía y ubicación (plantilla véase Eje 6: Plantillas).

Asignación de la DocID

Si el documento aún no está gestionado en el DMS, se genera una nueva DocID. La DocID es la uuidv7 pura: el identificador de instancia concreto (Object ID) del identificador dual que materializa el documento individual (véase Eje 2: Conceptos). Debe distinguirse, por tanto, de la v7guid categorizada, que codifica el contexto funcional (clase, tenant, esfera).

La DocID se genera a partir de una marca de tiempo, de modo que queda ligada al tiempo y es ordenable:

1. Herramienta: una herramienta de sidecar genera una UUIDv7 a partir de un argumento TimeStamp como DocID.
2. Fuente por defecto: la marca de tiempo del archivo (mtime) del documento original.
3. Fuente funcional (si está disponible): si el nombre del archivo o el contenido proporcionan una fecha funcionalmente relevante (p. ej., fecha de factura, de correo electrónico o de notificación oficial), se utiliza esta en lugar de la mtime; la DocID queda así vinculada a la fecha de origen del documento.

Ambos identificadores — la DocID (uuidv7) y la v7guid categorizada — se registran en el sidecar y se vinculan mediante el composite_key ({v7guid}:{uuidv7}).

Relación con V7GUID y Registry

• V7GUID: el bloque v7g_taxonomy clasifica el documento, mediante su v7guid categorizada, dentro de la jerarquía de negocio de seis niveles y de la esfera del tenant (véase Eje 2: Conceptos).
• Registry: el bloque locations documenta la ubicación física de almacenamiento (ruta UNC, período de validez). Los identificadores de tenant registrados se gestionan en el registro central de tenants (Zentrales Tenant-Register, Eje 2).

Estructura (ejemplo)

# V7G Sidecar - Rechnung_2026.pdf

**SHA-256:** `7d4e2f...`
**Tenant:** ORG-1
**Kategorie:** Finanzen und Buchführung
**Sphäre:** ideell

```json
{
  "$schema": "https://gitcover.org/schemas/v7g-sidecar-1.0.schema.json",
  "uuidV7": "0197a3b2-f3c0-7b00-8001-000000000042",
  "sha256": "7d4e2f...",
  "original_filename": "Rechnung_2026.pdf",
  "locations": [
    { "unc_path": "./ORG-1/FY2026/Rechnung_2026.pdf", "from": "260506", "to": null, "note": "Primärspeicherort" }
  ],
  "v7g_taxonomy": [
    { "v7guid": "0197a3b2-...-8001-...", "taxonomy": "ORG-1/Financial", "valid_from": "260506", "valid_to": null }
  ],
  "verification": { "verified_by": "auto", "method": "sha256_file", "intact": true }
}
```

Archivado de issues: de la base de datos de Gitea a la base de hechos en Git

Planteamiento del problema

Los issues de Gitea son entradas de base de datos, no objetos nativos de Git. No se versionan y, si se pierde la base de datos de Gitea, no son reconstruibles. Los commits referencian los issues solo de forma textual (Fixes #123); Git no interpreta esta referencia.

Solución: exportación automatizada como .v7g.md

El flujo de trabajo desde la base de datos de Gitea hasta la base de hechos a prueba de auditoría:

1. Issue de Gitea creado → el webhook dispara la exportación
2. Exportación como .v7g.md → guardar en .gitcover/issues/
3. Extracción de metadatos → UUID, hashes, firmas
4. Commit de Git con firma → git commit -S
5. Validación OSCAL/OPA → verificación de compliance
6. Marca de tiempo → integración con ELSTER/Bundesanzeiger (si es necesario)

Regla de ejemplo de OPA para la validación de issues

package gcbok.compliance

violation[msg] {
  input.path == "issues"
  file := input.files[_]
  not startswith(file.name, "018")  # UUIDv7-Prüfung
  msg := sprintf("Issue %s hat keine gueltige UUIDv7 im Dateinamen", [file.name])
}

Conformidad con GoBD/AO

Audit-Readiness

Audit-Readiness significa: cualquier auditoría puede tener lugar en cualquier momento, sin preparación adicional.

Tesis: lo forense es el repositorio Git, el HTML es solo presentación El paquete de examen HTML (sitio de auditoría, informes generados) es un derivado para la legibilidad humana. La fuerza probatoria forense reside exclusivamente en el propio repositorio Git: historial de commits inmutable, commits firmados con GPG, cadenas de comprobantes V7GUID, registries/dictionaries de .gitcover/ en formato JSON/JSONL. En una auditoría 10 años después basta un git clone (o desempaquetar un git bundle) — sin infraestructura web, sin base de datos, sin servicios en ejecución. Esto se corresponde con el Schema-Tiering (véase Plantillas: esquema V7GUID) y con el derivado gcbok-audit-evidence-docs/docs/02-audit-website-als-pruefungsartefakt.

Cierre de ejercicio GoBD

El cierre de ejercicio GoBD con compliance nativa de Git:

1. Cerrar el período — congelar la rama Git FY2026 (tag)
2. Validar la cadena de comprobantes — comprobar el encadenamiento V7GUID (script)
3. Generar los OSCAL-Assessment-Results — automatizado a partir de las validaciones OPA
4. Emisión del sello GPG — commit de cierre con firma de la GF
5. Archivado — contenedor .v7g.zip, v7g-export

Análisis de riesgos NIS2

El análisis de riesgos NIS2 basado en Git:

1. Inventario de activos — repositorios Git como registro de activos
2. Identificación de riesgos — políticas OPA para escenarios de amenazas
3. Evaluación — clasificación V7GUID para las categorías de riesgo
4. Mitigación — Pre-receive-Hooks para el Policy-Enforcement
5. Informe — OSCAL-Assessment-Results como evidencia NIS2

Integración del servidor de IA en la LAN

Principio de arquitectura

El GCBoK describe un modelo de referencia para la integración de un servidor de IA headless en la LAN que proporciona de forma centralizada inferencia LLM y agentes de compliance asistidos por RAG. El entorno de IA se ejecuta en un entorno de contenedores aislado (Rootless Podman), pero se acopla, para la inferencia y la búsqueda web, a servicios instalados de forma nativa en el host.

SSH Script Host (OSSH)

Para tareas exigentes (compilación de código, operaciones Git, verificaciones de compliance) que van más allá del sandbox del contenedor, el agente utiliza un SSH Script Host, una salida controlada y basada en claves hacia el sistema host:

1. El agente decide: «Ejecuta dotnet-build»
2. Canal SSH: conexión cifrada vía id_rsa.pub hacia el usuario del host
3. Proceso nativo: el comando se ejecuta en el contexto real del sistema operativo
4. Devolución por stream: stdout/stderr se devuelven como flujo de texto
5. El agente analiza: la salida del compilador en el contexto del LLM

Requisito de seguridad: la clave SSH generada en el contenedor debe darse de alta en el host dentro de authorized_keys. La comunicación se realiza exclusivamente mediante flujos de datos estándar (stdin, stdout, stderr), sin transferencia de archivos.

Direccionamiento consistente de rutas (FQN)

Para evitar inconsistencias de rutas entre la estación de trabajo, el contenedor y el script host, los recursos compartidos del servidor de archivos se montan en todos los sistemas en puntos de montaje idénticos. Los agentes de IA y los desarrolladores humanos referencian en todo momento rutas absolutas idénticas.

Capacidad multi-dispositivo

Gracias a la centralización en el servidor de IA, varios dispositivos finales pueden acceder en paralelo al mismo entorno:

• El desarrollador inicia un análisis de código en el escritorio
• Sigue el progreso del agente en tiempo real en el smartphone a través de VPN
• Sin bloqueos mutuos: el script host abre procesos de shell separados y de corta duración

Frontends de compartición: Nextcloud como frontend de solo lectura

Distribución de roles

Condiciones para el uso

Nextcloud puede utilizarse de forma puntual para shares en un entorno basado en GCBoK, si:

1. Solo shares de solo lectura — sin cambios a través de Nextcloud; todas las mutaciones se realizan vía Git
2. Integración con Git — Nextcloud monta los repos Git como almacenamiento externo (WebDAV, S3-Gateway o GCSYNC)
3. Validación de políticas — GCPN define las reglas de acceso (OPA/Rego); Nextcloud solo las aplica
4. Audit-Logging — los logs de Nextcloud se reenvían a GCAL (Syslog/Loki)
5. Conformidad de código abierto — solo Community Edition, sin plugins propietarios

Criterios de exclusión

• Acceso de escritura a través de Nextcloud (viola el almacenamiento nativo en Git)
• Extensiones propietarias de Nextcloud (violan los principios OSS)
• Falta de integración con Git (Nextcloud debe poder acceder a los repos Git)

Véase también: Plantillas para catálogos OSCAL y políticas OPA en Eje 6: Plantillas.