Autorschafts-Header — SPDX-Lizenzzeile pro Datei

Kanonische normative Referenz für nachgelagerte Mitwirkende. Dieses Dokument spiegelt die Abschnitte zu Autorschaft und Datei-Header der Projektspezifikation wider (Spezifikation §0.5 + §4.6); es ist die eigenständige Referenz, die mit dem veröffentlichten Repository ausgeliefert wird. Die architektonische Begründung ist in ADR-0002 festgehalten.

1. Die kanonische Header-Zeile

Jede zutreffende Datei im Ökosystem MUSS mit einer einzigen kanonischen SPDX-Lizenzbezeichner-Zeile beginnen, in der Kommentarsyntax ihrer Dateityp-Familie. Die Zeile ist der maschinenlesbare Lizenzmarker der Datei; ihre Anwesenheit ist für nicht ausgenommene Dateien nicht verhandelbar, und ihr Inhalt wird von einer einzigen Quelle der Wahrheit geregelt, nicht von Datei zu Datei improvisiert. Das vollständige Copyright-Instrument lebt einmalig in der Datei LICENSE im Repository-Stamm — es wird nicht in jede Quelldatei dupliziert.

1.1 Informationsgehalt (Invariante)

Der kanonische Inhalt ist genau eine Zeile:

1. SPDX-License-Identifier: MIT — der maschinenlesbare Lizenzmarker gemäß der von der FSFE gepflegten REUSE-Spezifikation; eindeutig geparst von der SPDX-Toolchain (reuse lint, scancode), dem Linux-Kernel-Tooling und nachgelagerten Lizenz-Scannern. Er trägt keinen visuellen Rahmen und keine Zeilen für Copyright, Website, E-Mail oder GitHub pro Datei — die Herkunft pro Datei ist konstruktionsbedingt die einzige SPDX-Zeile (siehe §4).

1.2 Die Referenzform (Familie der #-Kommentare)

Der kanonische Text — hier in seiner #-Kommentarsyntax-Form geschrieben — ist die Quelle der Wahrheit unter src/apothem/schemas/authorship-header.txt:

# SPDX-License-Identifier: MIT

Dieser Text ist die einzige autoritative Quelle. Der Validator file-header (§7) läuft gegen diese byte-genaue Vorlage. Jede Drift zwischen der Header-Zeile einer Datei und dieser Vorlage (unter der Syntaxsubstitution gemäß §2) ist ein CI-Fehlschlag.

2. Varianten je Dateityp (byte-genau)

Der Informationsgehalt der Zeile ist invariant; nur ihre Kommentarsyntax variiert je Dateityp. Die vollständige Tabelle der Varianten je Dateityp:

Markdown-Variante (kanonische Darstellung):

<!-- SPDX-License-Identifier: MIT -->

Der HTML-Kommentar-Wrapper (oder MDX {/* */}) wird unsichtbar gerendert, sodass die gerenderte Oberfläche sauber bleibt, während der Lizenzmarker im Quelltext über alle Dateitypen hinweg maschinenlesbar bleibt.

3. Ausnahmeliste (kategorisch ausgenommen)

Die folgenden Klassen sind von der SPDX-Header-Zeile ausgenommen. Die Anwendbarkeitsprüfung des Validators file-header gibt für diese not-applicable zurück:

• LICENSE — selbst das rechtliche Instrument; trägt die autoritative Copyright-Zeile, deren Vorhandensein der Validator license-author-consistency bestätigt.
• *.svg-Assets — XML-Kommentare sind für Zeilenkommentar-Marker fragil, daher wird die SVG-Herkunft vom Asset-README und den generierten Raster-Ausgaben getragen.
• CHANGELOG.md — formatgebundenes Release-Notes-Dokument; die SPDX-Zeile erscheint als einzelner HTML-Kommentar über der Changelog-Überschrift, nicht in das Format eingeflochten.
• JSON-Dateien (.json) — JSON hat keine Kommentarsyntax. Wo für eine JSON-Konfiguration eine Zuschreibung erforderlich ist, lege eine geschwisterliche <file>.NOTICE.md an.
• Lockfiles — package-lock.json, yarn.lock, pnpm-lock.yaml, Cargo.lock, Pipfile.lock, poetry.lock, go.sum usw. (maschinenverwaltet).
• Generierte Dateien — alles mit einem # Generated by ...- oder // Generated by ...-Marker oder alles, was linguist-generated=true in .gitattributes entspricht.
• Vendorierte Drittanbieter-Inhalte — Dateien unter vendor/, third_party/, node_modules/. Sie tragen die eigene Lizenz/Notiz des Upstreams; unseren Marker über die Upstream-Zuschreibung zu injizieren, ist eine Lizenzverletzung.
• .audit/-Dateien — von git ignorierte Ephemera; außerhalb des Geltungsbereichs des veröffentlichten Baums.
• Plan-Dateien (<project-root>/.apothem/plans/** und das veraltete <project-root>/.plans/**) — von git ignorierte Ephemera; die Herkunft ist das Frontmatter des Plans (siehe plans-discipline.md §3).
• Leere Marker — .keep, .gitkeep usw. (semantisch null Bytes).
• Binärdateien jeder Art.

Die Ausnahmeliste ist selbst als Regex/Glob-Liste in src/apothem/schemas/header-exceptions.txt kodiert und ist die Eingabe für die Anwendbarkeitsprüfung des Validators. Änderungen erfordern eine strukturierte Rückfrage und einen neuen ADR.

4. Lizenz-Interaktion

Die SPDX-Zeile deklariert die Lizenz des Projekts maschinenlesbar; die LICENSE-Datei deklariert sie autoritativ:

• SPDX-License-Identifier: MIT — der maschinenlesbare Lizenzmarker gemäß der REUSE-Spezifikation und dem SPDX-Standard. Automatisierte Lizenz-Scanner parsen diese Zeile direkt; die SPDX-Ausdruckssyntax ist mit reuse lint, scancode-toolkit, FOSSology und dem Lizenz-Tooling des Linux-Kernels kreuzkompatibel.

• LICENSE im Repository-Stamm — das autoritative rechtliche Instrument, das die vollständigen MIT-Bedingungen und den Copyright-Inhaber trägt. Es ist die einzige Heimat der Copyright-Erklärung; die Header pro Datei referenzieren es implizit über den gemeinsamen SPDX-Bezeichner, statt das Copyright in jeder Datei erneut zu nennen.

Einzeilige Form. Die Herkunft pro Datei ist die einzige SPDX-Zeile; das Copyright-Instrument lebt einmalig im Stamm-LICENSE. Umrahmte mehrzeilige Banner-Boxen (Copyright, Website, E-Mail, Kontaktzeilen in einem Linienrahmen) werden vom Validator abgelehnt: Sie duplizieren Kontakt- und Copyright-Metadaten in jeder Datei, ohne etwas hinzuzufügen, das der maschinenlesbare Lizenzmarker dem REUSE/SPDX/SBOM-Tooling nicht bereits liefert. Die byte-genaue Vorlage unter src/apothem/schemas/authorship-header.txt trägt die einzeilige Form; der Validator läuft gegen diese Vorlage.

Querverweise. LICENSE-Datei (MIT) — das rechtliche Instrument ist im Konfliktfall maßgeblich. ADR-0006 dokumentiert die Begründung der Banner-Verschmälerungs-Ratifizierung.

5. Einfügeposition

• Die SPDX-Zeile ist der erste Inhalt der Datei, mit einer und nur einer Ausnahme: eine Shebang-Zeile (#!/usr/bin/env bash, #!/usr/bin/env python3 usw.), die stets in Zeile 1 bleibt; die SPDX-Zeile beginnt in Zeile 2.
• Bei Markdown- / MDX-Dateien mit YAML-Frontmatter steht der SPDX-Kommentar ganz oben, das YAML-Frontmatter folgt, dann das H1 und der Rumpf. Die gerenderte Ausgabe beginnt mit einem unsichtbaren Kommentar, dann wird das Frontmatter vom Tooling geparst, danach fließt der sichtbare Inhalt.
• Eine einzelne Leerzeile trennt die SPDX-Zeile vom nächsten Inhalt (Frontmatter----, Nachfolger des Shebangs, H1 usw.).

6. Header-Sichtbarkeitsrichtlinie

Speziell für Markdown-Dateien ist die SPDX-Zeile standardmäßig unsichtbar — eingewickelt in <!-- ... --> (oder {/* */} für MDX), nur im Quelltext sichtbar. Dies ist die richtige Richtlinie für README, CONTRIBUTING, CLAUDE.md, die Anweisungsdateien der unterstützten Harnesses, SKILL.md von Skills, Kommando-Rümpfe, Output-Styles und Doku-Seiten. Eine sichtbare Darstellung (die SPDX-Zeile als Klartext oder eingefasster Block am Anfang der Ausgabe) ist für eigenständige Referenzdokumente erlaubt, die von einer sofort lesbaren Herkunft profitieren; die Richtlinie wird pro Dateiklasse in src/apothem/schemas/header-visibility.yaml festgelegt (Standard unsichtbar), mit einem dateibezogenen Override-Marker <!-- header-visibility: visible -->, der unmittelbar nach der Zeile erlaubt ist.

7. Der Injektor — scripts/inject-header.{sh,py}

Eine deterministische CLI, die:

• Einen oder mehrere Dateipfade (oder Globs) entgegennimmt.
• Die Anwendbarkeit über die Ausnahmeliste (§3) bestimmt.
• Den Zustand des bestehenden Headers (kanonisch / fehlerhaft / fehlend) erkennt und jeden nicht kanonischen Banner-Block, den sie findet, entfernt, damit Wiederholungsläufe idempotent sind.
• Die korrekte SPDX-Variante je Dateityp (§2) rendert.
• An der korrekten Position (§5) einfügt und dabei Shebangs und Frontmatter respektiert.
• In drei Modi arbeitet: fix-in-place (schreibt), emit-patch (gibt ein einheitliches Diff aus), check (beendet mit Nicht-Null bei jeder Abweichung — von CI genutzt).
• Idempotent: zweimaliges Ausführen ist eine No-Op.

Der Injektor wird von den Make-Zielen aufgerufen, die neue Dateien mit voreingefügter SPDX-Zeile gerüsten (make headers-fix und die make new-*-Gerüste), sowie vom Pre-Commit-Hook im --fix-Modus.

8. Der Validator — file-header (CI)

Liegt unter src/apothem/conformity/file_header_grep.py. Für jede Datei im Arbeitsbaum schlägt der Validator ihre Anwendbarkeit nach (gemäß §3) und behauptet, falls anwendbar, dass die kanonische SPDX-Zeile am Kopf der Datei vorhanden ist — vor allem anderen Inhalt, wobei der einzige erlaubte vorangehende Inhalt ein Shebang ist (§5).

Gestützt auf die byte-genaue Vorlage unter src/apothem/schemas/authorship-header.txt. Meldet das Diff pro Datei und die aggregierte Abdeckung in % in der CI-Zusammenfassung. Lässt den Build bei jeder Abweichung fehlschlagen.

9. Selbstdurchsetzungs-Mechanismen

Die Disziplin muss jede künftige Sitzung und jeden künftigen Mitwirkenden überdauern. Verbindliche Durchsetzungsoberflächen:

1. src/apothem/schemas/authorship-header.txt — die byte-genaue kanonische Vorlage; eine einzige Quelle der Wahrheit.
2. scripts/inject-header.{sh,py} — der mechanische Injektor (§7).
3. file-header-CI-Validator (§8) — lässt den Build bei jeder Abweichung fehlschlagen.
4. Pre-Commit-Hook — führt den Validator mit --fix auf den gestageten Dateien aus, an den Injektor angebunden.
5. CLAUDE.md-Block für verbindliches Verhalten — weist den Assistenten an, die kanonische SPDX-Zeile immer dann zu injizieren, wenn er eine zutreffende Datei erstellt.
6. Die Anweisungsdatei des unterstützten Harnesses am kanonischen .github/-Pfad — weist die Laufzeitumgebung des Harnesses an, bei der Dateierzeugung dasselbe zu tun.
7. PreToolUse-Hooks unter src/apothem/hooks/messages/pretooluse-{write,edit}-header-guard.md — fangen Write/Edit-Tool-Aufrufe auf zutreffenden Pfaden ab, damit die SPDX-Zeile bei der Dateierstellung injiziert wird, statt später als CI-Fehlschlag entdeckt zu werden.
8. PR-Vorlagen-Checkbox — die an Mitwirkende gerichtete Zusicherung, dass jede neue Datei die kanonische SPDX-Zeile trägt.
9. Dieses Dokument (site/content/docs/reference/authorship-header.mdx) — der kanonische, normative Erklärtext.

Siehe auch

• ADR-0002 — architektonische Begründung, erwogene Alternativen.
• ADR-0006 — Ratifizierung der Banner-Verschmälerung.
• src/apothem/schemas/authorship-header.txt — die byte-genaue kanonische Vorlage.
• src/apothem/schemas/header-exceptions.txt — die Ausnahmeliste (Regex/Glob-Form).
• scripts/inject-header.py und scripts/inject-header.sh — der Injektor.
• src/apothem/conformity/file_header_grep.py — der Validator.
• Projektspezifikation §0.5 + §4.6 — der hier gespiegelte kanonische Text.