Encabezado de autoría — Línea de licencia SPDX por archivo

Referencia normativa canónica para colaboradores de aguas abajo. Este documento refleja las secciones de Autoría y encabezado de archivo de la especificación del proyecto (Especificación §0.5 + §4.6); es la referencia independiente que se distribuye con el repositorio publicado. La justificación arquitectónica se registra en ADR-0002.

1. La línea de encabezado canónicaCopy Anchor Link

Todo archivo aplicable del ecosistema DEBE comenzar con una única línea canónica de identificador de licencia SPDX, en la sintaxis de comentario de su familia de tipo de archivo; solo un shebang o, en los archivos Markdown, el frontmatter YAML puede precederla (§5). La línea es el marcador de licencia legible por máquina del archivo; su presencia es innegociable para los archivos no exentos, y su contenido se rige por una única fuente de verdad, no se improvisa archivo por archivo. El instrumento de copyright completo vive una sola vez en el archivo LICENSE de la raíz del repositorio — no se duplica en cada archivo fuente.

1.1 Contenido de información (invariante)Copy Anchor Link

El contenido canónico es exactamente una línea:

1. SPDX-License-Identifier: MIT — el marcador de licencia legible por máquina según la especificación REUSE que mantiene la FSFE; lo analizan sin ambigüedad la cadena de herramientas de SPDX (reuse lint, scancode), las herramientas del kernel de Linux y los escáneres de licencias de aguas abajo. No lleva borde visual ni líneas de copyright, sitio web, correo electrónico o GitHub por archivo — por diseño, la procedencia por archivo es la única línea SPDX (ver §4).

1.2 La forma de referencia (familia de comentario #)Copy Anchor Link

El texto canónico — escrito aquí en su forma de sintaxis de comentario # — es la fuente de verdad en src/apothem/schemas/authorship-header.txt:

# SPDX-License-Identifier: MIT

Este texto es la única fuente autoritativa. El validador file-header (§8) comprueba los archivos contra este fixture exacto, byte a byte. Cualquier desviación entre la línea de encabezado de un archivo y este fixture (aplicando la sustitución de sintaxis según §2) se informa como hallazgo. El validador es bloqueante: con --strict, tal como lo ejecutan CI y el hook de pre-commit, un hallazgo hace fallar la ejecución (§8).

2. Variantes por tipo de archivo (exactas byte a byte)Copy Anchor Link

El contenido de información de la línea es invariante; solo varía su sintaxis de comentario según el tipo de archivo. La tabla completa de variantes por tipo de archivo:

Variante Markdown (renderizado canónico):

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

El envoltorio de comentario HTML (o MDX {/* */}) se renderiza de forma invisible, así que la superficie renderizada permanece limpia mientras el marcador de licencia en el código fuente sigue siendo legible por máquina en todos los tipos de archivo.

3. Lista de excepciones (exentas por categoría)Copy Anchor Link

Las siguientes clases están exentas de la línea de encabezado SPDX. El validador file-header da por válidos estos archivos sin comprobarlos. Las clases siguientes coinciden con la lista de patrones glob de header-exceptions.txt:

• Archivos legales y de versión — LICENSE, LICENSE.md, LICENSE.txt, NOTICE y VERSION. LICENSE lleva la línea de copyright autoritativa, cuya presencia confirma el validador license-author-consistency.
• El fixture canónico — schemas/authorship-header.txt. Inyectar el encabezado en el fixture produciría un encabezado del encabezado.
• Recursos *.svg — los comentarios XML son frágiles como marcadores de comentario de línea, así que la procedencia de los SVG la llevan el README de los recursos y las salidas ráster generadas.
• Archivos JSON (.json) — JSON no tiene sintaxis de comentarios. Cuando se requiera atribución para una configuración JSON, coloca un archivo <file>.NOTICE.md hermano.
• Lockfiles — todo archivo *.lock, package-lock.json, yarn.lock, pnpm-lock.yaml y go.sum. Estos archivos los gestiona la máquina.
• Archivos generados y minificados — cualquier archivo bajo un directorio generated/, y los paquetes minificados (*.min.js, *.min.css).
• Contenido de terceros incluido (vendored) — archivos bajo _vendor/, vendor/, third_party/ y node_modules/. Llevan la licencia o el aviso propios del upstream. Inyectar nuestro marcador sobre la atribución del upstream constituye una violación de licencia.
• Estado de auditoría, planificación y del entorno — todo lo que hay bajo .audit/ y .apothem/, que contiene planes, memoria, datos de aprendizaje y contextos. También projects/ y memory/ en la raíz del árbol de trabajo, que son propiedad del entorno. Estos árboles están ignorados por git o son propiedad del operador, y quedan fuera del alcance del árbol publicado. Los archivos de plan registran su procedencia en su frontmatter (consulta plans-discipline.md §3).
• Fixtures de datos de prueba — archivos .yaml, .yml, .txt y .json bajo tests/fixtures/. Los archivos fuente de prueba de ese árbol siguen llevando el encabezado.
• Entradas de humo del inyector — los archivos bajo tests/conformity-scenarios/fixtures/F-13-injector-smoke/. Permanecen sin encabezado porque la prueba del inyector comprueba que el inyector lo añade a ellos.
• Marcadores de empaquetado y vacíos — .SRCINFO, que un analizador de empaquetado lee de forma estricta, y los marcadores de tamaño cero .keep, .gitkeep y py.typed.
• Archivos binarios — los sufijos de imagen, fuente, archivo comprimido, multimedia y objeto compilado listados en el fixture. Un sufijo que la tabla de variantes del validador no asigna queda exento por defecto.

La propia lista de excepciones está codificada como una lista de regex/glob en src/apothem/schemas/header-exceptions.txt y es la entrada de la comprobación de aplicabilidad del validador. Las enmiendas requieren una indagación estructurada y un nuevo ADR.

4. Interacción con la licenciaCopy Anchor Link

La línea SPDX declara la licencia del proyecto de forma legible por máquina; el archivo LICENSE la declara de forma autoritativa:

• SPDX-License-Identifier: MIT — el marcador de licencia legible por máquina según la especificación REUSE y el estándar SPDX. Los escáneres de licencias automatizados analizan esta línea directamente; la sintaxis de expresiones SPDX es compatible con reuse lint, scancode-toolkit, FOSSology y las herramientas de licencias del kernel de Linux.

• LICENSE en la raíz del repositorio — el instrumento legal autoritativo, que lleva los términos completos de MIT y el titular del copyright. Es el único lugar de la declaración de copyright; los encabezados por archivo lo referencian de forma implícita mediante el identificador SPDX compartido, en lugar de reafirmar el copyright en cada archivo.

Forma de una sola línea. La procedencia por archivo es la única línea SPDX; el instrumento de copyright vive una sola vez en el LICENSE de la raíz. El validador rechaza las cajas de banner multilínea con borde (líneas de copyright, sitio web, correo electrónico y contacto envueltas en un marco rayado): duplican los metadatos de contacto y de copyright en cada archivo sin añadir nada que el marcador de licencia legible por máquina no proporcione ya a las herramientas REUSE/SPDX/SBOM. El fixture exacto byte a byte en src/apothem/schemas/authorship-header.txt lleva la forma de una sola línea; el validador se ejecuta contra este fixture.

Referencias cruzadas. Archivo LICENSE (MIT) — el instrumento legal prevalece en caso de conflicto. ADR-0006 documenta la justificación de la ratificación de la reducción del banner.

5. Posición de inserciónCopy Anchor Link

• La línea SPDX es el primer contenido del archivo, con dos excepciones. Una línea shebang (#!/usr/bin/env bash, #!/usr/bin/env python3, etc.) siempre permanece en la línea 1, y la línea SPDX comienza en la línea 2. En los archivos Markdown / MDX con frontmatter YAML, el frontmatter va primero (siguiente punto).
• Para los archivos Markdown / MDX con frontmatter YAML, el frontmatter permanece en el byte 0 para que las herramientas puedan analizarlo, y el comentario SPDX sigue al --- de cierre, después el cuerpo, que en los archivos que llevan un H1 comienza con él. scripts/inject-header.py coloca el comentario de esta manera.
• Una única línea en blanco separa la línea SPDX del siguiente contenido (el H1, el cuerpo, etc.).

6. Política de visibilidad del encabezadoCopy Anchor Link

En los archivos Markdown y MDX, la línea SPDX siempre se escribe dentro de su envoltorio de comentario (<!-- ... --> o {/* */}). Solo es visible en el código fuente y no aparece en la página renderizada. El inyector no tiene ningún renderizado visible ni anulación por archivo. Ninguna herramienta del repositorio lee el fixture src/apothem/schemas/header-visibility.yaml.

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

Una CLI determinista que:

• Toma una o más rutas de archivo (o globs).
• Determina la aplicabilidad mediante la lista de excepciones (§3).
• Detecta el estado del encabezado existente (canónico / malformado / ausente) y elimina cualquier bloque de banner no canónico que encuentre, de modo que las reejecuciones sean idempotentes.
• Renderiza la variante SPDX correcta por tipo de archivo (§2).
• Inserta en la posición correcta (§5), respetando los shebangs y el frontmatter.
• Añade la línea en blanco que falte a una línea SPDX que esté en el punto de inserción sin ella, en lugar de insertar una segunda copia por encima.
• Opera en tres modos: fix-in-place (escribe), emit-patch (imprime un diff unificado) y check (termina con código distinto de cero ante cualquier divergencia; ningún trabajo de CI lo ejecuta sobre el árbol rastreado).
• Es idempotente: ejecutarlo dos veces no tiene ningún efecto.

El inyector se invoca mediante el objetivo make headers-fix, que ejecuta scripts/inject-header.py --mode fix-in-place.

8. El validador — file-headerCopy Anchor Link

Reside en src/apothem/conformity/file_header_grep.py. Para cada archivo del árbol de trabajo, el validador consulta su aplicabilidad (según §3) y, si es aplicable, comprueba que la línea SPDX canónica esté presente en el punto de inserción. En la mayoría de las familias ese punto es el inicio del archivo, tras un shebang opcional. En los archivos Markdown y MDX se omite primero el bloque de frontmatter YAML, de modo que la línea canónica puede seguir a la valla de cierre, como exige §5. Los archivos MDX se resuelven a la forma {/* */} (§2) y se comprueban contra ella. El validador y el inyector colocan el bloque canónico en el mismo índice.

Se apoya en el fixture exacto, byte a byte, en src/apothem/schemas/authorship-header.txt. La ejecución sobre el corpus informa un número de hallazgos y una muestra de los archivos marcados para este comprobador. No imprime el diff por archivo ni el porcentaje de cobertura. El comprobador es bloqueante: con --strict, que usan CI y el hook de pre-commit, un hallazgo hace fallar la ejecución. Sin --strict, la puerta de conformidad informa el hallazgo y termina con 0.

9. Mecanismos de autoaplicaciónCopy Anchor Link

La disciplina debe sobrevivir a toda sesión futura y a todo colaborador futuro. Superficies de aplicación obligatorias:

1. src/apothem/schemas/authorship-header.txt — el fixture canónico exacto, byte a byte; una única fuente de verdad.
2. scripts/inject-header.{sh,py} — el inyector mecánico (§7).
3. Validador file-header (§8) — informa de la divergencia como hallazgo bloqueante, que hace fallar una ejecución con --strict.
4. Hook de pre-commit — el hook conformity-corpus-perwrite ejecuta cada comprobador por escritura, incluido el validador file-header (§8), sobre el árbol rastreado con --strict. El comprobador file-header es bloqueante, así que un hallazgo bloquea la confirmación. El hook solo comprueba. No tiene modo de corrección y nunca ejecuta el inyector (§7), que se ejecuta mediante make headers-fix.
5. Bloque de comportamiento obligatorio de CLAUDE.md — instruye al asistente para que inyecte la línea SPDX canónica siempre que cree un archivo aplicable.
6. El archivo de instrucciones de GitHub Copilot en .github/copilot-instructions.md — instruye a Copilot para que haga lo mismo al generar archivos.
7. Hooks PreToolUse en src/apothem/hooks/messages/pretooluse-{write,edit}-header-guard.md — interceptan las llamadas a las herramientas Write y Edit en las rutas aplicables, de modo que la línea SPDX se inyecte al crear el archivo, en lugar de descubrirse después como un hallazgo del validador. El comprobador del guard, src/apothem/hooks/lib/header_check.py, usa solo la biblioteca estándar y lee el fixture y la lista de exenciones del directorio schemas/ junto a hooks/, de modo que también funciona con el plugin de Claude Code, donde el paquete apothem no se puede importar. Aplica las tablas de variantes y las reglas de punto de inserción del inyector a los archivos dentro del proyecto, y solo en un proyecto git que contenga el fixture del encabezado (src/apothem/schemas/authorship-header.txt), ya que la línea SPDX es la convención de este repositorio y no un valor predeterminado para todos los proyectos que abre el plugin.
8. Casilla de la plantilla de pull request — afirmación, dirigida al colaborador, de que cada archivo nuevo lleva la línea SPDX canónica.
9. Este documento (site/content/docs/reference/authorship-header.mdx) — explicación canónica y normativa.

Véase tambiénCopy Anchor Link

• ADR-0002 — justificación arquitectónica y alternativas consideradas.
• ADR-0006 — ratificación de la reducción del banner.
• src/apothem/schemas/authorship-header.txt — el fixture canónico exacto byte a byte.
• src/apothem/schemas/header-exceptions.txt — la lista de excepciones (forma regex/glob).
• scripts/inject-header.py y scripts/inject-header.sh — el inyector.
• src/apothem/conformity/file_header_grep.py — el validador.
• Especificación del proyecto §0.5 + §4.6 — el texto canónico que se refleja aquí.