Axis 5: Approaches

Onboarding for SMEs

The entry point for SMEs into Git-native compliance follows a step-by-step path:

1. Initialize Git repository - Structure with .gitcover/ directory, V7GUID configuration
2. Select OSCAL catalog - GoBD baseline, BSI modules or individual profile
3. Activate OPA policies - Pre-receive hooks for validation before commit
4. Set up GPG signing - One GPG key pair per actor
5. Start the voucher chain - Assign first V7GUIDs, begin prev-hash chaining

For entrepreneurs from the part-time self-employment level

The entry can begin with a very simple story: GCDMS for voucher archiving, GCPN for evidence chains. Expand later: OSCAL policies, OPA validation, multi-tenant.

Interactive onboarding: The "Compliance City"

Instead of classic questionnaires, onboarding takes place as a modular build-up following the concept of a city on a Lego baseplate. Every architectural decision and every domain-specific requirement corresponds to a brick or an assembly (Lego set) that is stored and versioned as a structured module in the newly initialized default Git repository.

The analogy for the user:

• The baseplate: The empty Git repository, freshly created for the tenant in its infrastructure. It provides the standardized frame (the studs) onto which everything docks.
• The bricks: Modular configuration and service files. Only when a brick snaps into place (Git commit) does the corresponding function or compliance check become active.

Phase 1 - Lay out the baseplate (initialization & identity):

The system automatically creates the default repository for the tenant. The onboarding assistant determines the identity of the company. The data is stored in structured form in the 'TOP' (Tenant Organization Profile) repository - the first Git commit is already the first auditable compliance process. By the way: tenants can of course also be organized hierarchically, like the corporate structures to which they belong.

Phase 2 - Infrastructure wiring (utility grid):

The assistant records the IT landscape: laptop workstation, file server, cloud-first or hybrid infrastructure. Parameters such as internet connection, domain, storage paths etc. flow into the infrastructure information and prepare the paths for cross-connections (others.json).

Phase 3 - Erect buildings (domain-specific scope):

The user decides in a modular fashion which regulatory areas their city should cover:

At no point does the user see configuration files or code. Since every step immediately produces a clean Git commit, the system is documented from the very first minute in a fully audit-proof manner in accordance with GoBD and AO.

Tenant isolation and access control

OIDC claims and others.json

Linking OIDC claims with others.json is the royal road to multi-tenant, layperson-safe compliance environments. In others.json, the following are collected:

1. Canonical routes to the tenant's own Git repositories
2. Cross-connections to Git repositories of other tenants, if the tenant is a member of a group

Access is controlled via OIDC claims (roles and custom claims such as tenant_id, org_unit_id and group memberships). An inlet pipeline reads the others.json depending on the user claim and injects the permitted paths as a system prompt:

You are the GitCover agent for tenant X. You have access exclusively to the following repositories: [path 1], [path 2]. Do not execute any commands outside these directories.

Two-level claim model for PII access

For access to personal data (PII), the GCBoK defines a claim hierarchy with two levels (see Techniques: Git as IdP:

The others.json maps these claims to repository paths:

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

A user with org_unit_id = ORG-1-Portfolio receives access to PII/ORG-1-Portfolio, but not to PII/ORG-2-IT — even with the same tenant_id. This implements the principle of least privilege (NIS2 Art. 21) at the repository level.

For the end user, this security apparatus remains invisible. They log in, see their familiar working environment, and the AI automatically knows where it is allowed to operate.

AI-supported data capture via form bridging

Chat interfaces are suitable for contexts and analyses, not for strict data type capture (IBANs, postal codes, OSCAL schemas). The GCBoK therefore recommends form bridging:

1. AI detects the need: The user says, "I would like to add a new place of business."
2. Dynamic form URL: The AI outputs a link to a validated web input form (Blazor WASM/PWA), coupled to session and user management.
3. Encapsulated input: The user fills out the form - hard-validated before storage.
4. Direct writing to Git: The form writes the result as a structured file directly into the working directory of the tenant repository and triggers the commit.
5. AI takes over again: The MCP server reports "file updated", the AI confirms in the chat.

Advantage: Validation before storage protects the single source of truth. LLMs do not manipulate the writing process. The Git hook/OPA validation is triggered immediately.

The .gitcover/ directory structure

The .gitcover/ directory at the root of a GitCover repository is the central archive for all non-code artifacts. It serves audit-proofing, compliance (GoBD/AO) and audit trail maintenance.

Directory layout

.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

File naming convention

General format: {uuidV7}_{human-readable-key}_{Beschreibung}.v7g.md

Metadata schema (.v7g.md frontmatter)

---
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"
---

Automation through Git hooks and webhooks

GitCover repos are automatically configured with hooks/webhooks at init or tenant onboarding:

• post-commit: Updates .gitcover/ on new commits
• pre-push: Validates .gitcover/ before the push
• Webhooks: Issue creation, project changes, time tracking - each triggers export as .v7g.md
• Compliance claim: Immediate activation of OSCAL/OPA mechanisms

Versioning of these hooks/webhooks also takes place via Git, so that changes are traceable and auditable (self-referential, versioned, audit-proof). The hooks themselves can be versioned code artifacts that reside in .gitcover/hooks/, are updated as needed, and are documented in a GoBD- or NIS2-compliant manner.

V7GUID sidecars

A V7GUID sidecar is a *.v7g.md metadata file that is stored alongside a digital original document - e.g. Rechnung_2026.pdf receives Rechnung_2026.pdf.v7g.md in the same directory. The sidecar carries the metadata that Git cannot store within a binary file (PDF, DOCX, EML, image), thereby anchoring the original in the voucher chain and in the GCDMS.

Minimum information

Every sidecar must contain:

• sha256 - SHA-256 hash of the digital original document (proof of integrity).

In addition, it usually records identity, taxonomy and location (for a template see Axis 6: Templates).

DocID assignment

If the document is not yet managed in the DMS, a new DocID is generated. The DocID is the pure uuidv7 - the concrete instance identifier (Object ID) of the dual identifier that materializes the individual document (cf. Axis 2: Concepts). It must therefore be distinguished from the categorized v7guid, which encodes the domain-specific context (class, tenant, sphere).

The DocID is generated from a timestamp, so that it is time-bound and sortable:

1. Tool: A sidecar tool generates a UUIDv7 from a TimeStamp argument as the DocID.
2. Default source: the file timestamp (mtime) of the original document.
3. Domain-specific source (if available): If the file name or the content provides a domain-relevant date (e.g. invoice, e-mail or notice date), this is used instead of the mtime - the DocID thus binds to the creation date of the document.

Both identifiers - DocID (uuidv7) and the categorized v7guid - are maintained in the sidecar and linked via the composite_key ({v7guid}:{uuidv7}).

Relation to V7GUID and Registry

• V7GUID: The v7g_taxonomy block assigns the document via its categorized v7guid to the six-level business hierarchy and the tenant sphere (see Axis 2: Concepts).
• Registry: The locations block documents the physical storage location (UNC path, validity period). Registered tenant identifiers are maintained in the central tenant register (Central Tenant Register, Axis 2).

Structure (example)

# 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 }
}
```

Issue archiving: Gitea DB to Git fact base

Problem statement

Gitea issues are database entries - not native Git objects. They are not versioned and cannot be reconstructed if the Gitea database is lost. Commits reference issues only textually (Fixes #123); this reference is not interpreted by Git.

Solution: Automated export as .v7g.md

The workflow from the Gitea database to the audit-proof fact base:

1. Gitea issue created → Webhook triggers export
2. Export as .v7g.md → Save to .gitcover/issues/
3. Extract metadata → UUID, hashes, signatures
4. Git commit with signature → git commit -S
5. OSCAL/OPA validation → Compliance check
6. Timestamp → ELSTER/Bundesanzeiger integration (if required)

OPA example rule for issue validation

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])
}

GoBD/AO conformity

Audit readiness

Audit readiness means: an audit can take place at any time - without any follow-up preparation.

Thesis: Forensics is the Git repo, HTML is only presentation The HTML auditor package (audit website, generated reports) is a derivative for human readability. The forensic evidentiary value lies exclusively in the Git repository itself: immutable commit history, GPG-signed commits, V7GUID voucher chains, .gitcover/ registries/dictionaries in JSON/JSONL format. In an audit 10 years later, a git clone suffices (or unpacking a git bundle) — no web infrastructure, no database, no running services needed. This corresponds to the schema tiering (see Templates: V7GUID schema) and the derivative gcbok-audit-evidence-docs/docs/02-audit-website-als-pruefungsartefakt.

GoBD year-end closing

The GoBD year-end closing with Git-native compliance:

1. Close the period - Freeze the Git branch FY2026 (tag)
2. Validate the voucher chain - Check the V7GUID chaining (script)
3. Generate OSCAL assessment results - Automated from OPA validations
4. GPG seal issuance - Closing commit with GF signature
5. Archiving - .v7g.zip container, v7g-export

NIS2 risk analysis

The NIS2 risk analysis based on Git:

1. Asset inventory - Git repositories as asset register
2. Risk identification - OPA policies for threat scenarios
3. Assessment - V7GUID classification for risk categories
4. Mitigation - Pre-receive hooks for policy enforcement
5. Reporting - OSCAL assessment results as NIS2 evidence

AI server integration in the LAN

Architecture principle

The GCBoK describes a reference model for the integration of a headless AI server in the LAN that centrally provides LLM inference and RAG-based compliance agents. The AI environment runs in an isolated container environment (rootless Podman), but couples to services installed natively on the host for inference and web search.

SSH Script Host (OSSH)

For demanding tasks (code compilation, Git operations, compliance checks) that go beyond the container sandbox, the agent uses an SSH Script Host - a controlled, key-based breakout onto the host system:

1. Agent decides: "Run dotnet-build"
2. SSH channel: encrypted connection via id_rsa.pub to the host user
3. Native process: The command is executed in the real operating system context
4. Stream return: stdout/stderr are returned as a text stream
5. Agent analyzes: Compiler output in the LLM context

Security prerequisite: The SSH key generated in the container must be entered on the host in authorized_keys. Communication takes place purely via standard data streams (stdin, stdout, stderr) - without file transfer.

Consistent path addressing (FQN)

To avoid path inconsistencies between workstation, container and script host, file server shares are mounted at identical mount points on all systems. AI agents and human developers reference identical, absolute paths at all times.

Multi-device capability

Through centralization on the AI server, multiple end devices can access the same environment in parallel:

• The developer starts a code analysis on the desktop
• They track the agent's progress in real time on the smartphone via VPN
• No mutual blockages - the script host opens separate, short-lived shell processes

Share frontends: Nextcloud as read-only frontend

Role distribution

Conditions for use

Nextcloud can be used selectively for shares in a GCBoK-based environment if:

1. Read-only shares only - No changes via Nextcloud; all mutations run through Git
2. Git integration - Nextcloud mounts Git repos as external storage (WebDAV, S3 gateway or GCSYNC)
3. Policy validation - GCPN defines access rules (OPA/Rego); Nextcloud only enforces them
4. Audit logging - Nextcloud logs are forwarded to GCAL (syslog/Loki)
5. Open source conformity - Community edition only, no proprietary plugins

Exclusion criteria

• Write access via Nextcloud (violates Git-native storage)
• Proprietary Nextcloud extensions (violates OSS principles)
• Missing Git integration (Nextcloud must be able to access Git repos)

See also: Templates for OSCAL catalogs and OPA policies in Axis 6: Templates.