ED03 - Format du journal : artefacts JSON, signature temporelle, V7GUID, sidecars

Problème

Un entrepreneur souhaite tenir son journal dans Git - mais à quoi ressemble techniquement une entrée ? La pratique actuelle ne connaît aucune réponse contraignante :

• Notes en texte libre dans Markdown, Word ou papier - non lisibles par machine, non validées par schéma, non traçables
• Lignes Excel avec date, activité, heures - non versionnées, non ancrées cryptographiquement, non auditables
• Exports de logiciels de paie au format PDF - non exploitables par machine (§ 147 Abs. 6 AO), non traçables de manière rétrograde/progressive
• Aucune identité univoque - chaque entrée a un nom de fichier, mais le nom de fichier peut changer ; l'identité de l'entrée n'est pas stable
• Aucun ancrage temporel - la date figure sous forme de chaîne dans le document, mais qui a réellement saisi, et quand ? Le moment de la saisie n'est pas lié cryptographiquement à l'identité

Message essentiel

Une entrée de journal GitCover est un artefact JSON avec :

1. JSON-Schema-First - le schéma existe avant l'entrée ; l'entrée est validée par rapport au schéma (hook pre-commit)
2. V7GUID (Class Identifier) - classe le document/l'action selon le registre .gitcover (quoi/quel type) ; sert à l'organisation du classement et aux requêtes DB (par ex. EF Core dans Vertical App)
3. uuidV7 (Object ID) - constitue déjà à elle seule l'identité univoque (DocID) de l'entrée, RFC 9562 §5.7, générée à partir d'un horodatage prédéfini (ou now()) via le helper GitCover (gc-v7guid), le reste étant complété par du hasard
4. Clé composite V7GUID:uuidV7 - la clé composite du sidecar GCPN, sert à l'organisation du classement et aux requêtes ; le moment de la saisie est contenu dans l'uuidV7 (horodatage 48 bits), pas de champ datetime/date séparé
5. Sidecar obligatoire - chaque pièce justificative reçoit un sidecar .gc.md avec son propre uuidV7 (acte de classification) et l'uuidV7 du document
6. Traçabilité rétrograde/progressive - de l'écriture comptable → pièce justificative → entrée de journal → uuidV7 et inversement résoluble

Compliance by Design : le format n'est pas ajouté après coup - il est structurel. Schéma, V7GUID (Class), uuidV7 (Object) et sidecar sont des champs obligatoires, sans lesquels une entrée n'est pas admise dans le dépôt.

Pas de datetime/date redondant : le moment de la saisie est ancré dans l'uuidV7 elle-même (horodatage 48 bits, RFC 9562 §5.7). Une représentation sous forme de chaîne séparée dans les schémas JSON ou les données JSON est redondante et n'est pas consignée au niveau des faits. La représentation sous forme de chaîne pour le transfert DTO/HTMX relève de la responsabilité du harness, pas du niveau des faits.

L'entrée de journal comme nœud de conformité

L'entrée technique n'est pas une fin en soi. Elle est le nœud temporel où convergent plusieurs chaînes de preuve :

Le SSoT du journal indique selon quel agenda le travail a été effectué. Les documents originaux, les sidecars, GCPN et les artefacts du grand livre/de la facturation fournissent les pièces justificatives correspondantes. Cette séparation évite deux erreurs : une entrée de journal n'est pas confondue avec un substitut de pièce justificative externe, et une pièce justificative rassemblée plus tard n'est pas présentée à tort comme une preuve de travail effectuée en temps utile.

Le schéma JSON (Schema-First)

Le schéma existe avant l'entrée - il est déposé dans .gitcover/schemas/diary-entry-1.0.schema.json et versionné. Une entrée sans référence de schéma ($schema) est rejetée par le hook pre-commit.

Schéma diary-entry-1.0.schema.json (simplifié)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gitcover.org/schemas/diary-entry-1.0.schema.json",
  "title": "GitCover Diary Entry v1.0",
  "type": "object",
  "required": [
    "$schema", "V7GUID", "docUid",
    "author", "role", "tenant", "sphere", "source"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri",
      "const": "https://gitcover.org/schemas/diary-entry-1.0.schema.json"
    },
    "V7GUID": {
      "type": "string",
      "description": "Class Identifier - classe le document/l'action à partir du registre .gitcover (quoi/quel type)"
    },
    "docUid": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
      "description": "Object ID - RFC 9562 §5.7 UUIDv7, généré à partir d'un horodatage prédéfini (pas now()), horodatage 48 bits ancré dans le GUID"
    },
    "author": { "type": "string", "description": "Placeholder d'acteur, p. ex. E1" },
    "role": {
      "type": "string",
      "enum": ["GF", "Buchhalter", "Lohnverantwortlicher", "F&E-Leiter", "Administrator"]
    },
    "tenant": { "type": "string", "description": "Placeholder de tenant, p. ex. ORG-1" },
    "sphere": {
      "type": "string",
      "enum": ["ideell", "vermögensverwaltend", "zweckbetrieblich", "wirtschaftlich", "n/a"]
    },
    "source": {
      "type": "string",
      "enum": ["E1", "StB", "Notar", "Bank", "DRV", "FA", "BA", "VBG", "KK", "auto"]
    },
    "source_sha256": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "SHA-256 de la pièce justificative référencée (ID de pièce univoque)"
    },
    "tags": { "type": "array", "items": { "type": "string" } }
  }
}

Important - pas de champ datetime/date : le moment de la saisie est contenu dans l'uuidV7 (horodatage 48 bits, RFC 9562 §5.7). Une représentation sous forme de chaîne séparée est redondante et n'est pas consignée au niveau des faits. L'uuidV7 seule constitue la DocID univoque ; la clé composite V7GUID:uuidV7 sert à l'organisation du classement et aux requêtes DB.

V7GUID - structure et horodatage 48 bits

Principe fondamental : la composante horodatage 48 bits (bits 0–47) est autoritative pour le moment de la saisie. Elle est ancrée dans l'uuidV7 elle-même et ne peut être modifiée a posteriori sans rendre le GUID invalide. Un champ datetime séparé n'existe pas - le temps est contenu dans l'uuidV7. La représentation sous forme de chaîne pour DTO/HTMX relève de la responsabilité du harness.

Extension GitCover : hiérarchie et ID de processus dans les bits 66–127

La spécification GitCover V7GUID (work/OSS/TOP/.gitcover/specs/v7guid/) étend la composante aléatoire de 62 bits (bits 66–127) par une hiérarchie à 6 niveaux et des ID de processus - il s'agit de l'extension protégée par brevet (DPMA Az. 10 2025 003 091.6) :

Remarque : cette extension n'est pas impérativement nécessaire pour la série sur le journal - elle devient pertinente dans ED02 (tenant/sphère/rôle) et les articles ultérieurs (harness). Ici, la base RFC 9562 avec horodatage 48 bits suffit.

Routines helper : créer un V7GUID à partir de clés étrangères

L'outil OSS GitCover gc-v7guid (work/OSS/gc-v7guid) fournit les opérations :

gen — générer des Object ID UUIDv7

# n Object ID avec horodatage prédéfini (pas now()) et queue aléatoire (RFC 9562)
gc-v7guid gen 1 --ts 2026-08-15T09:00:00Z
# Sortie : 01a17e18-c662-7874-9e1c-85d47895304f

gen-doc — de manière déterministe à partir des métadonnées du document

# ID liée au document à partir de l'horodatage + SHA-256 du document original
gc-v7guid gen-doc --ts 2026-08-15T09:00:00Z --doc-sha256 <64-hex>

decode — extraire l'horodatage et la structure de l'uuidV7

gc-v7guid decode 019f2c6f-0900-7000-8000-000000000000
# Sortie : unix_ms, utc (ISO-8601), version=7, variant=2, rfc9562

Clé étrangère → uuidV7

Les routines helper permettent de créer, à partir d'une clé étrangère (par ex. un horodatage dans le nom de fichier comme 260815_0900_Lohnabrechnung.pdf), une clé uuidV7 valide - avec un horodatage prédéfini, et non now() :

1. Parser la clé étrangère - 260815_0900 → 2026-08-15T09:00:00Z
2. Calculer l'horodatage 48 bits - millisecondes Unix depuis l'epoch
3. Générer l'uuidV7 - Guid.CreateVersion7() avec horodatage explicite, le reste avec du hasard
4. Clé composite - V7GUID (Class issue du registre) : uuidV7 (Object avec horodatage)
5. Documentation GoBD - saisie en temps utile ancrée de manière traçable (pas de champ datetime séparé)

Référence GoBD : la saisie en temps utile (GoBD Rz. 146) est documentée cryptographiquement par l'horodatage 48 bits dans l'uuidV7 - et non simplement affirmée. L'horodatage fait partie de l'identité et ne peut être modifié a posteriori.

Structure du sidecar (.gc.md)

Chaque pièce justificative reçoit un sidecar avec deux références uuidV7 :

Exemple de sidecar

{
  "$schema": "https://gitcover.org/schemas/v7g-sidecar-2.0.schema.json",
  "V7GUID": "<V7GUID-Class-aus-Registry>",
  "docUid": "019f2c6f-0900-7001-8000-000000000001",
  "sha256": "ab94670c0dd8499c27ef2feddd1d9c5925977d55a52150a6fca0f6567d2e5e79",
  "title": "260815_Lohnabrechnung.pdf",
  "original_filename": "260815_Lohnabrechnung.pdf",
  "locations": [
    {
      "unc_path": "./ORG-1/sources/lohn/260815_Lohnabrechnung.pdf",
      "from": "260815",
      "to": null,
      "note": "Emplacement de stockage principal"
    }
  ],
  "v7g_taxonomy": [
    {
      "v7guid": "019f2c6f-0900-7000-8000-000000000000",
      "taxonomy": "ORG-1/Lohn",
      "valid_from": "260815",
      "valid_to": null,
      "note": "Tenant : ORG-1, Catégorie : Lohn, Sphère : ideell"
    }
  ],
  "gcpn": {
    "prima_nota_ref": null,
    "journal_entry_ref": null
  },
  "obsolescence": {
    "status": "active",
    "superseded_by": null,
    "superseded_at": null
  }
}

Clé composite V7GUID:uuidV7 :

• V7GUID (champ 1) - Class Identifier du sidecar (classification issue du registre .gitcover : quoi/quel type)
• uuidV7 (champ 2) - Object ID du sidecar lui-même, généré avec un horodatage prédéfini (quand la classification a-t-elle eu lieu ?), horodatage 48 bits ancré dans le GUID
• v7g_taxonomy[].v7guid - Object ID du document classifié (quel document est classifié ?)
• sha256 - identité du document original classifié — la preuve de l'originalité, toujours et partout (même lorsque le document se déplace : indépendamment du chemin/du nom, calculée à partir du contenu)

Ainsi, non seulement le document est identifié de manière univoque (via son SHA-256), mais aussi l'acte de classification lui-même - y compris le moment (dans uuidV7), qui a classifié et dans quel rôle. Pas de champ datetime séparé - le temps est contenu dans les valeurs uuidV7.

Traçabilité rétrograde et progressive

Référence GoBD : la traçabilité rétrograde correspond à GoBD Rz. 146 (traçabilité). La traçabilité progressive correspond à GoBD Rz. 147 (vérifiabilité). Les deux sont garanties by design par uuidV7 + SHA-256 - et non par des renvois manuels.

Saisie du temps dans le journal

Chaque entrée de journal contient un tableau de saisie du temps :

Règle de colonne : la colonne Objet ne porte exclusivement que le projet R&D (FZul1, FZul2, …). Le travail hors R&D figure comme administration (sphère/catégorie) avec l'objet —. Chaque heure FZul appartient à exactement un projet (§ 7 FZulG).

Référence FZul : la saisie du temps est la base des justificatifs d'heures FZul (ED29). La séparation R&D vs administration s'effectue via la colonne Objet par ligne de temps - et non uniquement via le champ role de l'entrée. Le role décrit la fonction de la personne agissante (voir ci-dessous), et non l'attribution de l'aide.

La saisie est complète - le plafonnement n'intervient qu'à la facturation

Le journal enregistre intégralement le temps de travail réellement effectué et sans plafond - y compris lorsqu'il dépasse une limite hebdomadaire prévue par le droit des aides (par ex. 40 heures par semaine et par personne). Une telle limite est un facteur de calcul dans le total hebdomadaire et dans la détermination de l'aide, et non une limite de la ligne de temps individuelle : aucune ligne n'est tronquée, raccourcie ou reventilée simplement parce qu'une limite serait atteinte. La saisie complète est la condition de la plausibilité du journal et de la solidité de la chaîne de preuve. Les regroupements entre projets et administration sont des questions de facturation/projection, et non des corrections apportées à la pièce justificative.

Le déroulement de la journée : d'abord la pièce, la comptabilisation plus tard

Une journée de journal suit un déroulement fixe. La saisie (pièce justificative) et la facturation/comptabilisation sont strictement séparées :

Délimitation : l'indication FZul/sphère dans le journal est un champ de la pièce justificative. Elle est indépendante de toute réserve liée à une attestation et ne génère aucune comptabilisation. Le journal est la preuve ; la comptabilisation se fait dans le ledger, la pondération dans les projections. Le même principe s'applique aux pièces justificatives : une pièce atteste, la comptabilisation intervient plus tard et séparément.

Les rôles dans le journal - personne, fonction, partie, exécution

Le champ role n'est pas la personne. Pour une compréhension robuste des rôles, GitCover distingue cinq niveaux, qui restent séparés même lorsque la même personne accomplit tout d'un seul trait (typique des PME) :

Une personne peut avoir plusieurs fonctions et plusieurs actes de signature sur le même document - par exemple en tant que gérant de deux sociétés. Il n'en résulte ni plusieurs personnes, ni nécessairement plusieurs comptes ou clés. Les rôles ne doivent toutefois pas se confondre du seul fait que la personne ou les identifiants sont identiques : chaque acte de signature lie version du document + personne + fonction + partie représentée + consentement expressément couvert. Une demande de confirmation commune adressée à la personne peut couvrir plusieurs signatures de fonctions, si les fonctions couvertes sont expressément nommées ; elle ne remplace pas une validation liée au document. Détails : DS03 - Processus de signature et DS13 - Stratification des parties prenantes.

Limite honnête : cette séparation est décrite comme exigence et modèle de données. Une liaison techniquement imposée de bout en bout entre personne, fonction, partie et consentement (notamment les claims de rôle depuis le fournisseur d'identité jusqu'aux événements de signature) fait l'objet d'un développement en cours et n'est pas encore mise en œuvre partout.

Le travail avec des agents dans le journal

Si l'entrepreneur recourt à des agents IA, la règle est la suivante : le pilotage, l'instruction, la surveillance et la validation des agents constituent un usage de moyens de travail par la personne agissante - le temps saisi est le temps de la personne. Le journal ne comporte aucune catégorie propre « temps d'agent » et n'exige aucune confirmation de « chevauchement » lorsque des activités se déroulent en parallèle. À la place :

• des lignes propres par activité/projet ;
• pour les activités hors du soutien R&D (notamment le développement d'outils et d'agents), en outre : quel acteur ou agent a agi avec quelle identité d'exécution effective - sans divulguer de secrets (tokens, clés).

Une éligibilité au soutien ne découle pas du recours à des agents, mais de la question de savoir si l'activité concerne une question de recherche technique ouverte (délimitation dans le projet concerné).

Ce qui aboutit dans le dépôt Git - et ce qui n'y aboutit pas

Important : seuls les artefacts structurés (JSON, sidecars, pièces justificatives, schémas, dictionnaires) sont admis dans le dépôt Git. Les documents privés ne sont jamais admis dans le dépôt, sauf s'ils ont été expressément introduits et classifiés comme artefact. Il s'agit d'une exigence de protection des données et de conformité (RGPD, GoBD).

Levier de risque

Exigence du harness (aperçu)

Déductible d'ED03 :

La liste complète des exigences figure dans Harness-Anforderungen.md.

Sources

• RFC 9562 §5.7 (UUIDv7) - horodatage Unix-ms 48 bits
• Spécification V7GUID - work/OSS/TOP/.gitcover/specs/v7guid/ (normatif)
• DPMA Az. 10 2025 003 091.6 - brevet V7GUID (revendication principale 2, revendications 5–8)
• Outil OSS GitCover gc-v7guid - work/OSS/gc-v7guid (helpers gen/decode)
• GoBD (circulaire BMF, Rz. 146 - traçabilité, Rz. 147 - vérifiabilité)
• AO (§ 147 Abs. 2 - « exploitable par machine », § 147 Abs. 6 - accès aux données)
• E1/agents/ (anonymisé) - concept SSoT avec artefacts JSON, sidecars

Topologie des sources et liens de référence CDN

Remarque : cette répartition des sources, du miroir et du community hub reflète l'état actuel et peut changer. Veuillez vérifier la source canonique correspondante sur gitcover.org pour l'état actuel.