Axis 5: Procedures

SME Onboarding

The entry 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 evidence chain - assign the first V7GUIDs, begin prev-hash chaining

For Entrepreneurs from Side-Business Level

The entry can begin with a very simple story: GCDMS for evidence archiving, GCPN for proof 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 following the concept of a city on a Lego baseplate. Every architectural decision and every functional requirement corresponds to a building block 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) on which everything docks.
• The building blocks: Modular configuration and service files. Only when a block 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 a structured manner in the 'TOP' (Tenant Organization Profile) repository - the first Git commit is already the first auditable compliance process. Incidentally: tenants can of course also be organized hierarchically, like the corporate structures to which they belong.

Phase 2 - Infrastructure wiring (Utility Network):

The assistant captures 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 (Functional Scope):

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

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

Tenant Isolation and Access Control

OIDC Claims and others.json

The linking of OIDC claims with others.json is the ideal approach for multi-tenant-capable, layperson-safe compliance environments. In others.json the following come together:

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 exclusive access 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 is granted 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 act.

AI-Assisted Data Capture via Form Bridging

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

1. AI recognizes the need: The user says "I want to add a new business location."
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 saving.
4. Direct write 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", and the AI confirms in the chat.

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

The .gitcover/ Directory Structure

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

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}_{Description}.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 via Git Hooks and Webhooks

GitCover repos are automatically configured with hooks/webhooks during 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 an export as .v7g.md
• Compliance claim: Immediate activation of OSCAL/OPA mechanisms

These hooks/webhooks are also versioned 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/ and are updated as needed and documented in a GoBD- or NIS2-compliant manner.

V7GUID Sidecars

A V7GUID sidecar is a *.v7g.md metadata file 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 evidence chain and in the GCDMS.

Minimum Information

Every sidecar necessarily contains:

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

Additionally, it usually carries 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 is thus to be distinguished from the categorized v7guid, which encodes the functional 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. Functional source (if available): If the file name or the content provides a functionally significant date (e.g. invoice, email or notice date), this is used instead of the mtime - the DocID thus binds to the document's date of origin.

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

Relation to V7GUID and Registry

• V7GUID: The v7g_taxonomy block classifies the document via its categorized v7guid into 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 kept 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); Git does not interpret this reference.

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 in .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 Compliance

Audit Readiness

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

Thesis: Forensics is the Git repo, HTML is just 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 evidence chains, .gitcover/ registries/dictionaries in JSON/JSONL format. For an audit 10 years later, a git clone (or unpacking a git bundle) suffices — 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 Git branch FY2026 (tag)
2. Validate the evidence chain - check V7GUID chaining (script)
3. Generate OSCAL assessment results - automated from OPA validations
4. GPG seal issuance - closing commit with management signature
5. Archiving - .v7g.zip container, v7g-export

NIS2 Risk Analysis

The NIS2 risk analysis on a Git basis:

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. Report - 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-supported 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 to 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 added to authorized_keys on the host. 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 path specifications at all times.

Multi-Device Capability

By centralizing 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 blocking - the script host opens separate, short-lived shell processes

Share Frontends: Nextcloud as a 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 merely implements them
4. Audit logging - Nextcloud logs are forwarded to GCAL (Syslog/Loki)
5. Open-source compliance - 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.