Autorschafts-Header — SPDX-Lizenzzeile pro Datei

Kanonische normative Referenz für nachgelagerte Mitwirkende. Dieses Dokument spiegelt die Abschnitte der Projektspezifikation zu Autorschaft und Datei-Header (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-ZeileCopy Anchor Link

Jede zutreffende Datei im Ökosystem MUSS mit einer einzigen kanonischen SPDX-Lizenzbezeichner-Zeile beginnen, in der Kommentarsyntax ihrer Dateityp-Familie; ihr darf nur ein Shebang oder, bei Markdown-Dateien, YAML-Frontmatter vorausgehen (§5). Die Zeile ist der maschinenlesbare Lizenzmarker der Datei; ihr Vorhandensein ist für nicht ausgenommene Dateien nicht verhandelbar, und ihr Inhalt wird von einer einzigen Quelle der Wahrheit geregelt und nicht von Datei zu Datei improvisiert. Das vollständige Copyright-Instrument liegt einmalig in der Datei LICENSE in der Repository-Wurzel — es wird nicht in jede Quelldatei dupliziert.

1.1 Informationsgehalt (Invariante)Copy Anchor Link

Der kanonische Inhalt ist genau eine Zeile:

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

1.2 Die Referenzform (Familie der #-Kommentare)Copy Anchor Link

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 maßgebliche Quelle. Der Validator file-header (§8) prüft Dateien gegen diese byte-genaue Vorlage. Jede Abweichung zwischen der Header-Zeile einer Datei und dieser Vorlage (unter der Syntaxsubstitution gemäß §2) wird als Befund gemeldet. Der Validator ist blockierend: Unter --strict, so wie CI und der Pre-Commit-Hook ihn ausführen, lässt ein Befund den Lauf fehlschlagen (§8).

2. Varianten je Dateityp (byte-genau)Copy Anchor Link

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 Wrapper aus HTML-Kommentar (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)Copy Anchor Link

Die folgenden Klassen sind von der SPDX-Header-Zeile ausgenommen. Der Validator file-header übergeht diese Dateien, ohne sie zu prüfen. Die unten genannten Klassen entsprechen der Glob-Liste in header-exceptions.txt:

• Rechts- und Versionsdateien — LICENSE, LICENSE.md, LICENSE.txt, NOTICE und VERSION. LICENSE trägt die maßgebliche Copyright-Zeile, deren Vorhandensein der Validator license-author-consistency bestätigt.
• Die kanonische Fixture — schemas/authorship-header.txt. Den Header in die Fixture einzufügen würde einen Header des Headers erzeugen.
• *.svg-Assets — XML-Kommentare sind für Zeilenkommentar-Marker fragil; daher wird die SVG-Herkunft vom Asset-README und von den generierten Rasterausgaben getragen.
• JSON-Dateien (.json) — JSON hat keine Kommentarsyntax. Wo für eine JSON-Konfiguration eine Zuschreibung erforderlich ist, legen Sie eine danebenliegende <file>.NOTICE.md an.
• Lockfiles — jede Datei *.lock, package-lock.json, yarn.lock, pnpm-lock.yaml und go.sum. Diese Dateien werden maschinell verwaltet.
• Generierte und minifizierte Dateien — jede Datei unter einem Verzeichnis generated/ sowie minifizierte Bundles (*.min.js, *.min.css).
• Vendorierte Inhalte Dritter — Dateien unter _vendor/, vendor/, third_party/ und node_modules/. Sie tragen die eigene Lizenz bzw. den eigenen Hinweis des Upstreams. Unseren Marker über die Zuschreibung des Upstreams zu setzen, ist eine Lizenzverletzung.
• Audit-, Planungs- und Harness-Zustand — alles unter .audit/ und .apothem/, das Pläne, Speicher, Lerndaten und Kontexte enthält. Ebenso projects/ und memory/ im Wurzelverzeichnis des Arbeitsbaums, die der Harness verwaltet. Diese Verzeichnisse sind von git ignoriert oder liegen in der Hoheit des Operators und stehen außerhalb des veröffentlichten Baums. Plan-Dateien werden über ihr Frontmatter herkunftsverfolgt (siehe plans-discipline.md §3).
• Testdaten-Fixtures — .yaml-, .yml-, .txt- und .json-Dateien unter tests/fixtures/. Testquelldateien in diesem Baum tragen weiterhin den Header.
• Injektor-Smoke-Test-Eingaben — die Dateien unter tests/conformity-scenarios/fixtures/F-13-injector-smoke/. Sie bleiben ohne Header, weil der Injektor-Test prüft, dass der Injektor den Header in sie einfügt.
• Paketierung und leere Marker — .SRCINFO, das ein Paketierungs-Parser streng liest, sowie die Null-Byte-Marker .keep, .gitkeep und py.typed.
• Binärdateien — die Suffixe für Bilder, Schriften, Archive, Medien und kompilierte Objekte, die in der Fixture aufgeführt sind. Ein Suffix, das die Varianten-Tabelle des Validators nicht abbildet, ist standardmäßig ausgenommen.

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-InteraktionCopy Anchor Link

Die SPDX-Zeile deklariert die Lizenz des Projekts maschinenlesbar; die LICENSE-Datei deklariert sie maßgeblich:

• 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 in der Repository-Wurzel — das maßgebliche 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 verweisen implizit über den gemeinsamen SPDX-Bezeichner darauf, statt das Copyright in jeder Datei erneut zu nennen.

Einzeilige Form. Die Herkunft pro Datei ist die einzige SPDX-Zeile; das Copyright-Instrument liegt einmalig in der LICENSE der Wurzel. Umrahmte mehrzeilige Banner-Boxen (Copyright-, Website-, E-Mail- und 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) — im Konfliktfall ist das rechtliche Instrument maßgeblich. ADR-0006 dokumentiert die Begründung der Ratifizierung der Banner-Verschmälerung.

5. EinfügepositionCopy Anchor Link

• Die SPDX-Zeile ist der erste Inhalt der Datei, mit zwei Ausnahmen. Eine Shebang-Zeile (#!/usr/bin/env bash, #!/usr/bin/env python3 usw.) bleibt stets Zeile 1, und die SPDX-Zeile beginnt in Zeile 2. Bei Markdown- / MDX-Dateien mit YAML-Frontmatter steht das Frontmatter zuerst (nächster Aufzählungspunkt).
• Bei Markdown- / MDX-Dateien mit YAML-Frontmatter bleibt das Frontmatter bei Byte 0, damit Tooling es parsen kann, und der SPDX-Kommentar folgt auf das schließende ---, danach der Rumpf, der bei Dateien mit einem H1 mit diesem beginnt. scripts/inject-header.py platziert den Kommentar auf diese Weise.
• Eine einzelne Leerzeile trennt die SPDX-Zeile vom nächsten Inhalt (dem H1, dem Rumpf usw.).

6. Header-SichtbarkeitsrichtlinieCopy Anchor Link

Bei Markdown- und MDX-Dateien wird die SPDX-Zeile immer innerhalb ihrer Kommentarumschließung geschrieben (<!-- ... --> oder {/* */}). Sie ist nur im Quelltext sichtbar und erscheint nicht in der gerenderten Seite. Der Injektor bietet keine sichtbare Darstellung und keine Überschreibung pro Datei. Kein Werkzeug im Repository liest die Datei src/apothem/schemas/header-visibility.yaml.

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

Eine deterministische CLI, die:

• Einen oder mehrere Dateipfade (oder Globs) entgegennimmt.
• Die Anwendbarkeit über die Ausnahmeliste (§3) bestimmt.
• Den vorhandenen Header-Zustand (kanonisch / fehlerhaft / fehlend) erkennt und dabei jeden nicht kanonischen Banner-Block, den sie findet, entfernt, damit erneute Läufe idempotent sind.
• Die korrekte SPDX-Variante je Dateityp (§2) rendert.
• An der korrekten Position (§5) einfügt und dabei Shebangs und Frontmatter berücksichtigt.
• Eine fehlende Leerzeile bei einer SPDX-Zeile ergänzt, die an der Einfügestelle ohne Leerzeile steht, statt oberhalb davon eine zweite Kopie einzufügen.
• In drei Modi arbeitet: fix-in-place (schreibt), emit-patch (gibt ein Unified-Diff aus), check (beendet sich bei jeder Abweichung mit einem Wert ungleich null; kein CI-Job führt ihn über den versionierten Baum aus).
• Idempotent ist: Zweimaliges Ausführen ist ein No-Op.

Der Injektor wird vom Make-Ziel make headers-fix aufgerufen, das scripts/inject-header.py --mode fix-in-place ausführt.

8. Der Validator — file-headerCopy Anchor Link

Liegt unter src/apothem/conformity/file_header_grep.py. Für jede Datei im Arbeitsbaum ermittelt der Validator deren Anwendbarkeit (gemäß §3) und prüft, sofern sie zutrifft, ob die kanonische SPDX-Zeile an der Einfügestelle vorhanden ist. Bei den meisten Familien ist diese Stelle der Kopf der Datei, nach einem optionalen Shebang. Bei Markdown- und MDX-Dateien wird zuerst ein YAML-Frontmatter-Block übersprungen, sodass die kanonische Zeile, wie §5 verlangt, nach der schließenden Frontmatter-Begrenzung stehen kann. MDX-Dateien werden auf die Form {/* */} (§2) aufgelöst und gegen sie geprüft. Validator und Injector setzen den kanonischen Block an denselben Index.

Gestützt auf die byte-genaue Vorlage unter src/apothem/schemas/authorship-header.txt. Der Korpus-Lauf meldet für diesen Matcher eine Anzahl an Befunden und eine Stichprobe markierter Dateien. Er gibt weder ein Diff pro Datei noch eine Abdeckung in Prozent aus. Der Matcher ist blockierend: Unter --strict, das CI und der Pre-Commit-Hook verwenden, lässt ein Befund den Lauf fehlschlagen. Ohne --strict meldet das Gate den Befund und beendet sich mit 0.

9. Selbstdurchsetzungs-MechanismenCopy Anchor Link

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. Validator file-header (§8) — meldet Abweichungen als blockierenden Befund, der einen --strict-Lauf fehlschlagen lässt.
4. Pre-Commit-Hook — der Hook conformity-corpus-perwrite führt jeden Matcher pro Schreibvorgang über den versionierten Baum mit --strict aus, einschließlich des Validators file-header (§8). Der Matcher file-header ist blockierend, daher blockiert ein Befund den Commit. Der Hook prüft nur. Er hat keinen Korrekturmodus und startet den Injektor (§7) nie; dieser läuft über make headers-fix.
5. Block CLAUDE.md für verbindliches Verhalten — weist den Assistenten an, die kanonische SPDX-Zeile zu injizieren, sobald er eine zutreffende Datei anlegt.
6. Die Anweisungsdatei von GitHub Copilot unter .github/copilot-instructions.md — weist Copilot an, bei der Dateierzeugung dasselbe zu tun.
7. PreToolUse-Hooks unter src/apothem/hooks/messages/pretooluse-{write,edit}-header-guard.md — fangen Write- und Edit-Tool-Aufrufe auf zutreffenden Pfaden ab, damit die SPDX-Zeile bei der Dateierstellung injiziert wird, statt später als Befund des Validators entdeckt zu werden. Der Prüfer des Guards, src/apothem/hooks/lib/header_check.py, verwendet ausschließlich die Standardbibliothek und liest die Fixture und die Ausnahmeliste aus dem Verzeichnis schemas/ neben hooks/, sodass er auch unter dem Claude Code-Plugin funktioniert, wo das Paket apothem nicht importierbar ist. Er wendet die Variantentabellen und die Regeln für die Einfügestelle des Injektors auf Dateien innerhalb des Projekts an, und zwar nur in einem git-Projekt, das die Header-Fixture (src/apothem/schemas/authorship-header.txt) trägt, da die SPDX-Zeile die Konvention dieses Repositorys ist und kein Standard für jedes Projekt, das das Plugin öffnet.
8. Checkbox in der PR-Vorlage — 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) — die kanonische, normative Erläuterung.

Siehe auchCopy Anchor Link

• 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 (Form mit Regex/Glob).
• 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.