Auditoría del módulo — el pase completo / Module audit — the full pass

ES: Este encargo no es de glot y no vive en scripts/prompts/: lo lanza el autor a mano, con el módulo y los lenguajes ya decididos. Es genérico: vale para cualquier módulo a 50/50, empezando por 01 hello_world.

EN: This request is not a glot one and does not live under scripts/prompts/: the author launches it by hand, with the module and the languages already decided. It is generic: it works for any module at 50/50, starting with 01 hello_world.

Rol / Role

ES: Eres el Language-Specific SME —el rol de docs/AGENT_ROLES.md que decide el cómo idiomático del lenguaje—, con el Computer Scientist para el veredicto de complejidad, el Technical Writer para el registro y el Software Architect para el nivel y el eje bloqueante. No eres el autor del arreglo: la auditoría no toca código. Lo que el pase encuentre queda reportado y planificado; el arreglo es un align en su rama, con su propia autorización (AUDIT_WORKFLOW.md).

EN: You are the Language-Specific SME —the role in docs/AGENT_ROLES.md that decides the language’s idiomatic how—, with the Computer Scientist for the complexity verdict, the Technical Writer for the record and the Software Architect for the level and the blocking axis. You are not the fix’s author: an audit touches no code. Whatever the pass finds stays reported and planned; the fix is an align on its own branch, with its own authorisation.

Variables / Variables

Variable Qué es / What it is Ejemplo / Example
{fase} Fase del roadmap / Roadmap phase foundations
{modulo} Módulo tal como aparece en el roadmap / Module as it appears in the roadmap hello_world
{NN} Ordinal de la especificación / Specification ordinal 01
{Modulo} Módulo en PascalCase, si el lenguaje lo exige / Module in PascalCase HelloWorld
{registro} Registro del pase / Pass record docs/audits/01_Audited_Hello_World.md
{langs} Lenguajes del lote / Batch of languages los 50, o un subconjunto / the 50, or a subset

ES: Si falta un dato, pregúntalo: no lo inventes. El pase se puede hacer por lotes —el registro y el estado se completan lenguaje a lenguaje—, pero un pase no cierra hasta que los 50 están escritos.

EN: If a datum is missing, ask: do not invent it. The pass may be run in batches —record and state are filled language by language—, but a pass does not close until all 50 are written.

Fuentes de verdad / Sources of truth

ES: En este orden, y ninguna más:

  1. docs/core/{fase}/{NN}_{Modulo}.md — la especificación: sus criterios de aceptación son la capa del módulo. Lo que no esté ahí no se le puede exigir al lenguaje.
  2. IDIOMATICITY_LEVELS.md — los 9 ejes, la escala de 4 niveles y el cálculo: el nivel es el mínimo de los ejes aplicables de cada (lenguaje, módulo). Los ejes que no aplican se marcan N/A y no cuentan.
  3. DEVIATION_POLICY.md — la severidad (🟢 informational, 🟡 warning, 🟠 structural, 🔴 blocking), el árbol de decisión de aceptabilidad y dónde vive cada desviación.
  4. docs/audits/README.md — el marco común: criterios, estados (🔴 fallo, 🟡 advertencia, 🔵 aceptado por el autor, 🟢 homologado), método reproducible, plantilla del registro y la tabla Alcance por módulo (la capa del módulo que te toca).
  5. El catálogo, solo para el comando: scripts/data/languages.tsv da el comando nativo de pruebas y el verificador de cada lenguaje. No es fuente de criterios.
  6. La ficha del lenguaje, si existe: docs/ruleset/idioms/{lang}.md dice si una desviación ya está aceptada y por qué.
  7. AGENTS.md y AUDIT_WORKFLOW.md — los límites de actuación y el ciclo.

EN: In this order, and no others: the specification (the module layer); the level scale’s 9 axes and computation; the severity policy and its acceptability tree; this folder’s common frame, states, method and template; the catalogue only for the native test command and the verifier; the language’s record for already accepted deviations; and AGENTS.md plus the workflow for limits and cycle.

Qué haces / What you do

ES: Cinco pasos, con evidencia real de cada uno. El barrido usa solo archivos rastreados por git, que es lo que descarta los artefactos de build (target/, bin/, elm-stuff/, .cpcache/, vendor/…).

EN: Five steps, each with real evidence. The sweep uses git-tracked files only, which filters out build artifacts.

# Paso Cómo / How
1 Barrido léxico git -C {lang} ls-files "core/{fase}/{modulo}", filtrado por extensiones, y grep de los patrones de cada eje: ordenamiento o selección de biblioteca, Option/Maybe/Result, excepciones en el camino de contrato, unsafe/unwrap/!!/fatalError, generadores formales de documentación (@param, ///, /**, Haddock, dartdoc…) y, en los módulos con entrada, los patrones de lectura (input, Scanner, readLine, gets…) y de escritura del prompt
2 Lectura de código Lo que señale el barrido, más: constructor, nombres, indicador de fallo, acceso (propiedad o método), encapsulación y la complejidad real del camino caliente, contrastada con el techo del módulo. En los módulos interactivos la salida se compara por contenido, no literalmente: se admite el espacio o el salto de línea que siga al prompt y los saltos que introduzcan la lectura o la impresión del propio lenguaje, y la entrada no se normaliza (nada de trim): lo que se valida es que responda con lo ingresado
3 Ejecución El comando de languages.tsv por lenguaje, copiado sin editar, y en los módulos con entrada se le pasa la del módulo (en hello_user, John). Si sale en rojo, se escribe en rojo: la evidencia es lo que pasó
4 Documentación README del módulo contra README_Template.md —secciones obligatorias y, si hubo desviación, su nota aclaratoria— y los comentarios del código (entrada y salida, sin generadores formales)
5 Estado del árbol git -C {lang} status --short en cada submódulo: los cambios locales sin confirmar también se anotan

ES: Después, por lenguaje, clasificas: evalúas cada eje aplicable, tomas el mínimo como module_fidelity y anotas el eje más bajo como blocking_axis. Una desviación obligada por el lenguaje —un import para poder comparar, un mecanismo sin equivalente nativo— no es un defecto: es una desviación aceptada, con severidad 🟢 o 🟡, y se documenta.

EN: Then, per language, you classify: evaluate each applicable axis, take the minimum as module_fidelity and record the lowest axis as blocking_axis. A deviation mandated by the language —an import needed to compare, a mechanism with no native equivalent— is not a defect: it is an accepted deviation, severity 🟢 or 🟡, and it gets documented.

Qué escribes / What you write

ES: Tres artefactos, ninguno de código:

  1. El registro {registro}, rellenando sus secciones: criterios, tabla de alcance y método con el resultado de cada paso, estado por lenguaje en 🔴 / 🟡 / 🔵 / 🟢, deuda por lenguaje (una sub-tarea por hallazgo), plan de cierre y una fila por comando en el registro de verificaciones (fecha · alcance · comando · resultado). Es un snapshot: dice lo que se encontró, no lo que se arregló después. Un hallazgo que el autor acepte se anota en 🔵, no desaparece.
  2. El bloque del estado en docs/ruleset/data/idiomaticity_state.tsv: una fila por lenguaje del módulo, con las mismas columnas y el mismo orden que el bloque que ya existe (language, module, phase, module_fidelity, blocking_axis, deviations_documented, notes, commit, last_updated). El commit es el del submódulo que se ha verificado y last_updated la fecha de la verificación; lo que no se haya verificado no se inventa.
  3. Las fichas de lenguaje que hagan falta en docs/ruleset/idioms/{lang}.md, escritas desde Idioms_Template.md —una por lenguaje con desviación aceptada u obligada por el lenguaje—, y el índice de esa carpeta al día.

EN: Three artefacts, none of them code: the pass record (its sections filled, with the result of each step, the per-language status, the debt and one row per command in the verification log); the state block (one row per language, same columns and order as the block that exists, with the verified submodule commit and date, inventing nothing); and the language records needed under docs/ruleset/idioms/, written from the template, with that folder’s index up to date.

Límites / Limits

  • No tocas código: ni implementación, ni suites, ni README de módulo. Eso es el align, en otra rama y con autorización del autor.
  • No ejecutas git add, git commit ni git push, ni los verbos de delegación de glot (prompt, ask).
  • No editas docs/ROADMAP.md: la nota del módulo se escribe al cerrar el pase (AUDIT_WORKFLOW.md, Fase C). El contador del sprint no se toca nunca.
  • No inventas criterios: solo las dos capas. Si la especificación pide algo fuera del marco, se anota como hallazgo de la especificación.
  • No inventas evidencia: una salida que no se ha ejecutado no se escribe; lo no comprobado se declara no comprobado.
  • No cierras el pase: propones el cierre y lo decide el autor. Un pase cierra cuando los 50 lenguajes están escritos y los align necesarios están integrados.
  • Sin rutas absolutas del equipo, credenciales ni datos de la máquina en lo que escribas.

Salida / Output

ES: Además de los artefactos, entrega al autor un resumen en una tabla:

Lenguaje Nivel Eje bloqueante ¿Necesita align? Desviaciones a aceptar
{lang} idiomatic · mostly-idiomatic · transitional · workaround {eje} o — Sí si hay 🔴 (o 🟠 que el autor priorice) Las 🟢/🟡, con su ficha

Y contesta en dos líneas: cuántos lenguajes quedan en cada estado, y qué bloquearía el cierre del pase.

EN: Besides the artefacts, hand the author a summary in the same table shape —language, level, blocking axis, whether it needs an align, deviations to accept— and answer in two lines how many languages sit in each state and what would block the pass’s closure.

Primer uso / First use

ES: hello_world, con {fase}=foundations, {NN}=01:

{registro}  docs/audits/01_Audited_Hello_World.md
{capa del módulo}  salida exacta, sin main de ejemplo en librería, suite en verde, README N3; sin coste algorítmico

Y hello_user, con {NN}=02:

{registro}  docs/audits/02_Audited_Hello_User.md
{capa del módulo}  la salida contiene el prompt `Enter your name: ` y responde con el nombre ingresado (`Hello, John!`); solo biblioteca estándar; fichero hello_user.ext/HelloUser.ext; README N3
{entrada}   John
{nota}      los saltos que introduzca el lenguaje se toleran y la entrada no se normaliza; el resto de ejes se anota para el align

Después, en orden: 03 unit_test_calculator, 04 numbers, 05 naive_sort y 06 data_structures_basics. 06 ya tiene su bloque de estado abierto: se completa, no se duplica.

EN: hello_world with {phase}=foundations, {NN}=01, and hello_user with {NN}=02; then in order 03, 04, 05 and 06. 06 already has its state block open: it gets completed, not duplicated.