Convenciones de entorno multi-superficie

Referencia normativa canónica para colaboradores de aguas abajo. Este documento refleja las secciones de Convenciones de entorno multi-superficie de la especificación del proyecto (Especificación §0.6 + §2.8 + §4.7); es la referencia independiente que se distribuye con el repositorio publicado. La justificación arquitectónica se registra en ADR-0003.

1. Por qué en pluralCopy Anchor Link

Una superficie de ingeniería moderna la tocan varios entornos: consolas de chat, motores de autocompletado dentro del IDE, compañeros de programación en pareja y revisores de pull requests. Cada uno lee su propio archivo de configuración canónico. Si el proyecto distribuye solo uno de esos archivos, los tiempos de ejecución restantes improvisan en silencio frente a convenciones no declaradas; la memoria dentro del repositorio que falta se filtra de inmediato.

El costo de una superficie ausente es la deriva silenciosa en el código generado por máquina, la peor clase de defecto porque se acumula de forma invisible. Cada artefacto generado por máquina agrava la divergencia; para cuando un revisor humano detecta la contradicción, la base de código ya arrastra semanas de convenciones incoherentes.

La configuración del tiempo de ejecución de los entornos es plural por la realidad del despliegue. El ecosistema publicado DEBE distribuir las tres superficies obligatorias de §3: AGENTS.md, un archivo de memoria de comportamiento para el tiempo de ejecución de la consola de chat (CLAUDE.md) y un archivo de instrucciones con alcance de repositorio para el tiempo de ejecución de autocompletado dentro del IDE. Las superficies DEBEN ser mutuamente coherentes —sin contradicción, sin deriva— y DEBEN codificar conjuntamente las mismas disciplinas.

2. El contrato de coherenciaCopy Anchor Link

Cada superficie de convenciones dentro del alcance (§3) es un canal que expresa la especificación única de convenciones del proyecto. La especificación se descompone en:

• Secciones compartidas: Disciplina de planes, indagación estructurada (o su equivalente en la superficie), Encabezado de autoría, Nomenclatura, Antipatrones, Jerarquía modal. Estas DEBEN aparecer en cada superficie obligatoria y DEBEN ser semánticamente equivalentes entre superficies.
• Secciones específicas de cada superficie: encuadres de capacidades, patrones de llamada a herramientas, diferencias entre la generación de código y el chat. Estas PUEDEN diferir entre superficies, pero NO DEBEN contradecir las secciones compartidas.

El validador multi-surface-coherence (§7) se ejecuta en cada ejecución de CI y en el pre-commit, y comprueba el contrato.

Las superficies son canales distintos que expresan una sola especificación. Las secciones compartidas DEBEN coincidir —semánticamente y, donde sea posible, léxicamente— entre superficies. Las secciones específicas de cada superficie NO DEBEN contradecir las secciones compartidas.

3. Superficies dentro del alcanceCopy Anchor Link

Para este repositorio, las superficies de activación opcional son las que el fixture de la lista de afirmaciones (tests/fixtures/multi-surface-claims.yaml) enumera bajo optional-in. Las configuraciones raíz específicas de proveedor que no se usan están ausentes de forma intencional; un archivo de configuración específico de una herramienta se agrega solo cuando esa herramienta es una superficie de edición activa para este repositorio.

4. Lista de secciones del archivo de instrucciones dentro del IDECopy Anchor Link

El archivo de instrucciones con alcance de repositorio bajo .github/ DEBE contener, en este orden, las siguientes secciones (cada una con el texto de encabezado exacto que figura abajo; los cuerpos de las secciones se redactan, no se estampan desde una plantilla, pero cada uno DEBE cubrir las afirmaciones listadas):

1. Project Context — un párrafo: qué es este repositorio, quién lo usa, su forma de nivel superior. Concreto; sin marketing.
2. Coding Conventions — nomenclatura, jerarquía modal, frontmatter, estilo de markdown, puntos de estilo específicos del lenguaje donde divergen de los valores predeterminados.

3. File Headers — todo archivo que genere el tiempo de ejecución DEBE comenzar con la única línea canónica SPDX-License-Identifier: MIT según site/content/docs/reference/authorship-header.mdx, en la variante de comentario que corresponda al tipo de archivo. Referencia a scripts/inject-header.* y a site/content/docs/reference/authorship-header.mdx.

4. Plans Discipline — el tiempo de ejecución NO DEBE generar código ni scripts que escriban en un directorio de configuración de un entorno (por ejemplo ~/.claude/plans/ o ~/.codex/.plans/) ni en ninguna otra ubicación global de planes. Los artefactos de planificación van a <project-root>/.apothem/plans/ (un árbol heredado <project-root>/.plans/ se actualiza mediante apothem migrate-workspace) según site/content/docs/reference/plans-discipline.mdx.
5. Structured Inquiry Behavior — cuando el tiempo de ejecución tiene dudas, NO DEBE fabricar en silencio. En su lugar, inserta un bloque de aclaración claramente marcado (p. ej., un comentario # TODO(clarify): <question>) y plantea la pregunta en el chat cuando la superficie lo permite. Sin API inventadas, sin nombres de modelo inventados, sin rutas de archivo inventadas.
6. Forbidden Patterns — prohibiciones explícitas: sin adjetivos de marketing, sin relleno evasivo, sin restos de depuración con console.log, sin rutas absolutas codificadas de forma fija al directorio personal del usuario, sin hacer commit de secretos, sin hacer commit de archivos bajo .apothem/plans/ (o el heredado .plans/), sin contradecir el archivo canónico de instrucciones del proyecto.
7. Output Format — el código y la prosa generados se ajustan a las convenciones unificadas de salida conversacional: carácter definitivo, seccionado uniforme, densidad, disciplina de resumen, citas. Para el código: superficie pública documentada, con tipos donde el lenguaje admite tipos, con pruebas donde existe una estructura de pruebas.
8. Review Checklist — lo que un revisor (humano o tiempo de ejecución en modo de revisión de pull requests) DEBE verificar antes de aprobar: encabezado presente, nomenclatura conforme, ninguna escritura en .apothem/plans/, ninguna contradicción con el archivo canónico de instrucciones del proyecto, validadores en verde localmente.
9. Pointers — enlaces a AGENTS.md, CLAUDE.md, site/content/docs/reference/plans-discipline.mdx, site/content/docs/reference/authorship-header.mdx, este documento de convenciones, src/apothem/schemas/ y CONTRIBUTING.md.

El archivo comienza con la línea SPDX canónica del encabezado de autoría (variante Markdown) según site/content/docs/reference/authorship-header.mdx §2, visible o invisible según la política de visibilidad del encabezado que haya elegido el proyecto.

El archivo de instrucciones dentro del IDE no es una copia literal de AGENTS.md ni de CLAUDE.md. AGENTS.md es la superficie canónica de instrucciones del proyecto, CLAUDE.md la refleja para Claude Code, y el archivo de instrucciones dentro del IDE está redactado para un tiempo de ejecución de autocompletado de código en el editor que emite sugerencias que un desarrollador acepta o rechaza. La información (disciplinas, convenciones, antipatrones) es idéntica; el encuadre difiere.

5. Referencia de la lista de afirmacionesCopy Anchor Link

El fixture en tests/fixtures/multi-surface-claims.yaml enumera cada afirmación compartida. Entradas de ejemplo:

- id: plans.location
  claim: "Planning artifacts live at <project-root>/.apothem/plans/, never inside a harness configuration directory."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
  optional-in: [site/content/docs/architecture/agents.mdx, .cursorrules]
- id: header.canonical
  claim: "Every applicable new file begins with the canonical SPDX-License-Identifier: MIT header line, in the comment family matching the filetype."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
- id: ambiguity.resolution
  claim: "Ambiguity is surfaced via the structured-inquiry channel or a clearly-marked TODO(clarify); never silently invented."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
# ... (one entry per shared claim)

El validador analiza cada superficie, intenta encontrar la presencia de cada afirmación en la superficie (mediante la jerarquía de encabezados + la extracción de palabras clave del cuerpo) y falla ante cualquier ausencia o contradicción.

6. Regla de reconciliaciónCopy Anchor Link

Cuando se detecta que dos superficies se contradicen en una afirmación compartida, la reconciliación predeterminada es:

AGENTS.md es la voz canónica del proyecto. Toda superficie en contradicción se reescribe para reflejar la semántica de AGENTS.md con el encuadre propio de esa superficie.

Una anulación específica de una superficie solo se permite con un marcador explícito dentro del archivo, <!-- coherence-override: <claim-id> -->, que apunte a un ADR que explique la divergencia deliberada. El propio marcador de anulación figura en la lista de permitidos del validador y aparece en el informe de CI.

Para este repositorio, la estrategia de reconciliación ratificada es agents-md-wins: AGENTS.md es canónico y cada espejo de entorno activo se mantiene semánticamente equivalente.

7. ValidadoresCopy Anchor Link

Tres validadores implementan conjuntamente el contrato de coherencia:

- in-IDE-instructions-presence    (src/apothem/conformity/copilot_instructions_presence_grep.py)
- multi-surface-coherence         (src/apothem/conformity/multi_surface_coherence_grep.py)
- license-author-consistency      (src/apothem/conformity/license_author_consistency_grep.py)

• El primero verifica que el archivo de instrucciones dentro del IDE existe, se puede analizar, contiene cada sección canónica enumerada en §4 y comienza con la línea canónica SPDX-License-Identifier: MIT (variante Markdown).
• El segundo analiza las secciones canónicas de cada superficie y verifica que las secciones compartidas son mutuamente coherentes según un comparador normalizado (insensible a mayúsculas y minúsculas, tolerante a los espacios en blanco, que admite la paráfrasis léxica pero exige equivalencia semántica en la lista de afirmaciones definida por el fixture).
• El tercero verifica únicamente que el LICENSE de la raíz lleva una línea Copyright (c) <name> que se puede analizar. No lee los encabezados por archivo, que no llevan nombre de autor.

8. Ciclo de vida de las superficiesCopy Anchor Link

• Agregar una superficie. El operador la activa mediante el canal de indagación estructurada. El generador redacta la superficie según la lista de afirmaciones, ejecuta el validador y registra un ADR si hace falta una anulación específica de la superficie.
• Eliminar una superficie. La indagación estructurada confirma la eliminación, un ADR registra la justificación y se modifica la lista required-in del validador.
• Detección de deriva. El pre-commit / CI rechaza cualquier commit que se desvíe de la lista de afirmaciones; el autor del commit reescribe la superficie para restaurar la coherencia.

Véase tambiénCopy Anchor Link

• ADR-0003 — justificación arquitectónica y alternativas consideradas.
• tests/fixtures/multi-surface-claims.yaml — el fixture canónico de la lista de afirmaciones.
• AGENTS.md — la voz canónica del proyecto.
• CLAUDE.md — el espejo para Claude Code.
• site/content/docs/reference/plans-discipline.mdx — la referencia canónica de la afirmación compartida Disciplina de planes.
• site/content/docs/reference/authorship-header.mdx — la referencia canónica de la afirmación compartida Encabezado de autoría.
• Especificación del proyecto §0.6 + §2.8 + §4.7 — el texto canónico completo que se refleja aquí.