@imolko/ultra-agent 0.2.0-beta → 1.0.0-beta

package/scripts/adr-gate/rules/hardcoded.mjs

@@ -0,0 +1,63 @@
+/**
+ * Regla `hardcoded`: los ADRs activos no duplican anclas cuya fuente canónica
+ * vive en el paquete o en docs/agents/.
+ */
+
+import path from "node:path";
+
+import { tierAdrFiles } from "../registry.mjs";
+import { ESTADO_RE, pyStrip, readText } from "../text.mjs";
+
+/** Anchors caducados: la fuente canónica pasó al paquete y a docs/agents/ (A-052). */
+const STALE_ANCHORS = [".pi/skills/", ".pi/repo-config.md"];
+
+/**
+ * Ejecuta la regla sobre los ADRs activos de los tres tiers.
+ * @param {ReturnType<import("../registry.mjs").createRegistry>} registry
+ * @param {ReturnType<import("../report.mjs").createReport>} report
+ * @returns {void}
+ */
+export function ruleHardcoded(registry, report) {
+  for (const tier of registry.tiers) {
+    for (const adr of tierAdrFiles(tier)) {
+      checkHardcoded({ registry, adr, report });
+    }
+  }
+}
+
+/**
+ * Comprueba las anclas caducadas de un ADR activo.
+ * @param {{ registry: object, adr: string, report: object }} context
+ * @returns {void}
+ */
+function checkHardcoded(context) {
+  const text = readText(context.adr);
+  if (!isActiveAdr(text)) {
+    return;
+  }
+
+  for (const anchor of STALE_ANCHORS) {
+    if (text.includes(anchor)) {
+      const rel = path.relative(context.registry.root, context.adr);
+      context.report.add(
+        "hardcoded",
+        `${rel} duplica el ancla caducada \`${anchor}\` (fuente canónica: paquete/docs/agents)`,
+      );
+    }
+  }
+}
+
+/**
+ * Marca un ADR como activo salvo que su `**Estado**` sea `Reemplazado` o
+ * `Deprecado`; la ausencia del campo se trata como activo.
+ * @param {string} text
+ * @returns {boolean}
+ */
+function isActiveAdr(text) {
+  const match = ESTADO_RE.exec(text);
+  if (!match) {
+    return true;
+  }
+  const state = pyStrip(match[1]);
+  return state !== "Reemplazado" && state !== "Deprecado";
+}

package/scripts/adr-gate/rules/indices.mjs

@@ -0,0 +1,100 @@
+/**
+ * Regla `indices`: cada ADR aparece en el índice de su tier y el índice no lista
+ * ADRs inexistentes.
+ *
+ * Los destinos inexistentes se comprueban en orden canónico por code point. El
+ * gate histórico iteraba un `set` de Python, cuyo orden dependía de
+ * `PYTHONHASHSEED`; fijar el orden hace reproducible el golden (T-017).
+ */
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import { linkTargets } from "../links.mjs";
+import { tierAdrFiles } from "../registry.mjs";
+import {
+  joinUnnormalized,
+  readText,
+  resolvePath,
+  sortByCodePoint,
+} from "../text.mjs";
+
+const LOCAL_LINK_PREFIX = "./";
+
+/**
+ * Ejecuta la regla sobre los tres tiers.
+ * @param {ReturnType<import("../registry.mjs").createRegistry>} registry
+ * @param {ReturnType<import("../report.mjs").createReport>} report
+ * @returns {void}
+ */
+export function ruleIndices(registry, report) {
+  for (const tier of registry.tiers) {
+    checkTierIndex({ registry, tier, report });
+  }
+}
+
+/**
+ * Comprueba el índice de un tier en sus dos direcciones.
+ * @param {{ registry: object, tier: object, report: object }} context
+ * @returns {void}
+ */
+function checkTierIndex(context) {
+  const index = path.join(context.tier.directory, "index.md");
+  if (!existsSync(index)) {
+    const rel = path.relative(context.registry.root, index);
+    context.report.add(
+      "indices",
+      `falta el índice del tier ${context.tier.prefix}: ${rel}`,
+    );
+    return;
+  }
+
+  const indexTargets = new Set(
+    linkTargets(readText(index)).filter(
+      (target) =>
+        target.startsWith(LOCAL_LINK_PREFIX) && target.endsWith(".md"),
+    ),
+  );
+
+  checkListedAdrs({ ...context, indexTargets });
+  checkExistingTargets({ ...context, index, indexTargets });
+}
+
+/**
+ * Reporta los ADRs del tier que no aparecen en su índice.
+ * @param {{ registry: object, tier: object, report: object, indexTargets: Set<string> }} context
+ * @returns {void}
+ */
+function checkListedAdrs(context) {
+  for (const adr of tierAdrFiles(context.tier)) {
+    const target = `${LOCAL_LINK_PREFIX}${path.basename(adr)}`;
+    if (!context.indexTargets.has(target)) {
+      const rel = path.relative(context.registry.root, adr);
+      context.report.add(
+        "indices",
+        `${rel} no aparece en el índice de su tier`,
+      );
+    }
+  }
+}
+
+/**
+ * Reporta los destinos del índice que no existen, en orden canónico.
+ * @param {{ registry: object, tier: object, report: object, index: string, indexTargets: Set<string> }} context
+ * @returns {void}
+ */
+function checkExistingTargets(context) {
+  for (const target of sortByCodePoint([...context.indexTargets])) {
+    const relative = target.slice(LOCAL_LINK_PREFIX.length);
+    const resolved = resolvePath(
+      joinUnnormalized(context.tier.directory, relative),
+    );
+    if (!existsSync(resolved)) {
+      const rel = path.relative(context.registry.root, context.index);
+      context.report.add(
+        "indices",
+        `el índice ${rel} lista un ADR inexistente: ${target}`,
+      );
+    }
+  }
+}

package/scripts/adr-gate/rules/jerarquia.mjs

@@ -0,0 +1,102 @@
+/**
+ * Regla `jerarquia`: un ADR A/T/P no referencia tiers prohibidos, ni por enlace
+ * markdown ni por cita en texto plano. Los IDs citados por un enlace prohibido
+ * quedan cubiertos por esa violación y no se reportan otra vez.
+ */
+
+import path from "node:path";
+
+import { resolveLink } from "../links.mjs";
+import { hasTier, targetTier, tierAdrFiles } from "../registry.mjs";
+import { LINK_RE, LINK_TARGET_RE, PLAIN_ID_RE, readText } from "../text.mjs";
+
+/**
+ * Ejecuta la regla sobre los tres tiers.
+ * @param {ReturnType<import("../registry.mjs").createRegistry>} registry
+ * @param {ReturnType<import("../report.mjs").createReport>} report
+ * @returns {void}
+ */
+export function ruleJerarquia(registry, report) {
+  for (const tier of registry.tiers) {
+    const allowedPrefixes = new Set(
+      [...tier.allowed].filter((target) => hasTier(registry, target)),
+    );
+
+    for (const adr of tierAdrFiles(tier)) {
+      const text = readText(adr);
+      const context = {
+        registry,
+        tier,
+        adr,
+        report,
+        allowedPrefixes,
+        reportedIds: new Set(),
+      };
+
+      scanLinks(context, text);
+      scanPlainIds(context, text.replace(LINK_TARGET_RE, ""));
+    }
+  }
+}
+
+/**
+ * Reporta los enlaces markdown a tiers prohibidos.
+ * @param {object} context
+ * @param {string} text
+ * @returns {void}
+ */
+function scanLinks(context, text) {
+  for (const match of text.matchAll(LINK_RE)) {
+    const label = match[1];
+    const target = match[2];
+    const resolved = resolveLink(context.adr, target);
+    if (resolved === null) {
+      continue;
+    }
+
+    const resolvedTier = targetTier(context.registry, resolved);
+    if (resolvedTier === null || context.tier.allowed.has(resolvedTier)) {
+      continue;
+    }
+
+    addReportedIds(context.reportedIds, `${label} ${target}`);
+    context.report.add(
+      "jerarquia",
+      `${path.relative(context.registry.root, context.adr)} referencia al tier ${resolvedTier} (${target}), prohibido para el tier ${context.tier.prefix}`,
+    );
+  }
+}
+
+/**
+ * Reporta las citas en texto plano con un prefijo no permitido para el tier.
+ * @param {object} context
+ * @param {string} text
+ * @returns {void}
+ */
+function scanPlainIds(context, text) {
+  for (const match of text.matchAll(PLAIN_ID_RE)) {
+    const prefix = match[1];
+    const ident = match[0];
+    if (context.allowedPrefixes.has(prefix) || context.reportedIds.has(ident)) {
+      continue;
+    }
+    context.reportedIds.add(ident);
+    context.report.add(
+      "jerarquia",
+      `${path.relative(context.registry.root, context.adr)} cita en texto plano ${ident} (prefijo ${prefix}), prohibido para el tier ${context.tier.prefix}`,
+    );
+  }
+}
+
+/**
+ * Marca los IDs citados por un enlace prohibido —en la etiqueta o el destino—
+ * para no reportarlos también como cita en texto plano.
+ * @param {Set<string>} reportedIds
+ * @param {string} text
+ * @returns {void}
+ */
+function addReportedIds(reportedIds, text) {
+  for (const match of text.matchAll(PLAIN_ID_RE)) {
+    reportedIds.add(match[0]);
+  }
+}

package/scripts/adr-gate/text.mjs

@@ -0,0 +1,263 @@
+/**
+ * Compatibilidad de texto y rutas con el gate Python histórico.
+ *
+ * La salida del gate es un contrato (A-011, T-017): estas funciones replican
+ * `str.strip()`, `str.splitlines()`, `sorted()` por code point y
+ * `Path.resolve()` de Python. Cualquier cambio aquí cambia los golden files.
+ */
+
+import { lstatSync, readFileSync, readlinkSync } from "node:fs";
+import path from "node:path";
+
+/** Caracteres que `str.strip()` considera espacio en Python (incluye \x1c-\x1f y \x85). */
+const PY_WHITESPACE_CLASS =
+  "[\\t\\n\\v\\f\\r\\x1c-\\x1f \\x85\\xa0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]";
+const PY_STRIP_RE = new RegExp(
+  `^${PY_WHITESPACE_CLASS}+|${PY_WHITESPACE_CLASS}+$`,
+  "gu",
+);
+
+/** Separadores de `str.splitlines()` en Python. */
+const PY_LINE_BREAK_RE = /\r\n|[\r\n\v\f\x1c\x1d\x1e\x85\u2028\u2029]/g;
+
+/** Inicio de línea con la semántica de `re.MULTILINE`: solo después de `\n`. */
+const PY_LINE_START = "(?:^|(?<=\\n))";
+
+/** Mayor code point del plano básico; por encima, un code point ocupa dos unidades UTF-16. */
+const MAX_BMP_CODE_POINT = 0xffff;
+
+export const H1_RE = /^# (A|T|P)-\p{Nd}{3}: .+/u;
+
+export const ORIGINALLY_RE = new RegExp(`${PY_LINE_START}\\*\\*originally\\*\\*:`);
+export const ORIGINALLY_WRONG_RE = new RegExp(
+  `${PY_LINE_START}\\*\\*[Oo]riginally\\*\\*:`,
+);
+export const ENRICHED_RE = new RegExp(
+  `${PY_LINE_START}\\*\\*Enriquecido desde\\*\\*:`,
+);
+export const ENRICHED_WRONG_RE = new RegExp(
+  `${PY_LINE_START}\\*\\*[Ee]nriquecido [Dd]esde\\*\\*:`,
+);
+export const ESTADO_RE = new RegExp(
+  `${PY_LINE_START}\\*\\*Estado\\*\\*: ?([^\\n]+)(?=\\n|$)`,
+);
+
+/** Citas en texto plano a un ID de ADR, con `\b` y `\d` Unicode como en Python. */
+export const PLAIN_ID_RE =
+  /(?<![\p{L}\p{N}_])([A-Z]{1,2})-\p{Nd}{3}(?![\p{L}\p{N}_])/gu;
+
+/** Destino de un enlace markdown inline `](destino)` para la regla `enlaces`. */
+export const LINK_DEST_RE = /\]\(([^)]+)\)/gu;
+
+/** Destino de un enlace markdown inline que se elimina antes del escaneo de
+ * texto plano de la regla `jerarquia`. */
+export const LINK_TARGET_RE = /\]\([^)]*\)/gu;
+
+/** Enlace markdown inline completo: etiqueta y destino. */
+export const LINK_RE = /\[([^\]]*)\]\(([^)]*)\)/gu;
+
+/**
+ * Recorta espacios con la misma semántica que `str.strip()` de Python.
+ * @param {string} value
+ * @returns {string}
+ */
+export function pyStrip(value) {
+  return value.replace(PY_STRIP_RE, "");
+}
+
+/**
+ * Divide un texto por los mismos separadores que `str.splitlines()` de Python,
+ * sin conservar los saltos y sin añadir una línea vacía final.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function splitLines(text) {
+  if (text === "") {
+    return [];
+  }
+
+  const lines = [];
+  let start = 0;
+  for (const match of text.matchAll(PY_LINE_BREAK_RE)) {
+    lines.push(text.slice(start, match.index));
+    start = match.index + match[0].length;
+  }
+  if (start < text.length) {
+    lines.push(text.slice(start));
+  }
+  return lines;
+}
+
+/**
+ * Compara dos cadenas por code point Unicode, como `sorted()` de Python.
+ * @param {string} left
+ * @param {string} right
+ * @returns {number}
+ */
+export function compareCodePoints(left, right) {
+  let leftIndex = 0;
+  let rightIndex = 0;
+
+  while (leftIndex < left.length && rightIndex < right.length) {
+    const leftPoint = left.codePointAt(leftIndex);
+    const rightPoint = right.codePointAt(rightIndex);
+    if (leftPoint !== rightPoint) {
+      return leftPoint - rightPoint;
+    }
+    leftIndex += leftPoint > MAX_BMP_CODE_POINT ? 2 : 1;
+    rightIndex += rightPoint > MAX_BMP_CODE_POINT ? 2 : 1;
+  }
+
+  return left.length - leftIndex - (right.length - rightIndex);
+}
+
+/**
+ * Ordena cadenas por code point sin depender del orden de `readdir`.
+ * @param {string[]} entries
+ * @returns {string[]}
+ */
+export function sortByCodePoint(entries) {
+  return [...entries].sort(compareCodePoints);
+}
+
+/**
+ * Descompone una ruta en los componentes que compara `pathlib.Path`: la raíz
+ * cuenta como primer componente y los separadores repetidos no crean vacíos.
+ * @param {string} value
+ * @returns {string[]}
+ */
+function pathParts(value) {
+  const root = path.parse(value).root;
+  const rest = value.slice(root.length).split(path.sep).filter(Boolean);
+  return root === "" ? rest : [root, ...rest];
+}
+
+/**
+ * Compara dos rutas componente a componente, como `sorted(Path(...))` de Python.
+ * @param {string} left
+ * @param {string} right
+ * @returns {number}
+ */
+export function comparePathComponents(left, right) {
+  const leftParts = pathParts(left);
+  const rightParts = pathParts(right);
+  const limit = Math.min(leftParts.length, rightParts.length);
+
+  for (let index = 0; index < limit; index += 1) {
+    const result = compareCodePoints(leftParts[index], rightParts[index]);
+    if (result !== 0) {
+      return result;
+    }
+  }
+
+  return leftParts.length - rightParts.length;
+}
+
+/**
+ * Resuelve una ruta como `Path.resolve()` de Python: sigue symlinks componente a
+ * componente y, si un componente no existe, conserva el resto sin resolver.
+ * @param {string} input
+ * @returns {string}
+ */
+export function resolvePath(input) {
+  const absolute = path.isAbsolute(input) ? input : path.resolve(input);
+  const root = path.parse(absolute).root;
+  const state = {
+    pending: absolute.slice(root.length).split(path.sep),
+    resolved: root,
+    seen: new Set(),
+  };
+
+  while (state.pending.length > 0) {
+    resolveNext(state);
+  }
+
+  return state.resolved;
+}
+
+/**
+ * Resuelve el siguiente componente pendiente, siguiendo un symlink si lo hay.
+ * @param {{ pending: string[], resolved: string, seen: Set<string> }} state
+ * @returns {void}
+ */
+function resolveNext(state) {
+  const name = state.pending.shift();
+  if (!name || name === ".") {
+    return;
+  }
+  if (name === "..") {
+    state.resolved = path.dirname(state.resolved);
+    return;
+  }
+
+  const candidate = path.join(state.resolved, name);
+  const stats = lstatOrNull(candidate);
+  if (!stats || !stats.isSymbolicLink()) {
+    state.resolved = candidate;
+    return;
+  }
+
+  followSymlink(state, candidate);
+}
+
+/**
+ * Lee `lstat` sin lanzar: un componente inexistente se conserva como texto.
+ * @param {string} candidate
+ * @returns {import("node:fs").Stats | null}
+ */
+function lstatOrNull(candidate) {
+  try {
+    return lstatSync(candidate);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Sustituye el symlink pendiente por su destino; un ciclo conserva la parte
+ * resuelta y deja el resto sin resolver, como `Path.resolve()`.
+ * @param {{ pending: string[], resolved: string, seen: Set<string> }} state
+ * @param {string} candidate
+ * @returns {void}
+ */
+function followSymlink(state, candidate) {
+  if (state.seen.has(candidate)) {
+    state.resolved = path.resolve(candidate, ...state.pending);
+    state.pending = [];
+    return;
+  }
+  state.seen.add(candidate);
+
+  const linkTarget = readlinkSync(candidate);
+  if (!path.isAbsolute(linkTarget)) {
+    state.pending.unshift(...linkTarget.split(path.sep));
+    return;
+  }
+
+  const root = path.parse(linkTarget).root;
+  state.resolved = root;
+  state.pending.unshift(...linkTarget.slice(root.length).split(path.sep));
+}
+
+/**
+ * Junta un directorio y una ruta relativa sin normalizar `.` ni `..`, para que
+ * `resolvePath()` los procese con la misma semántica que Python.
+ * @param {string} directory
+ * @param {string} relative
+ * @returns {string}
+ */
+export function joinUnnormalized(directory, relative) {
+  return path.isAbsolute(relative)
+    ? relative
+    : `${directory}${path.sep}${relative}`;
+}
+
+/**
+ * Lee un ADR con la misma traducción de saltos que el modo texto de Python:
+ * `\r\n` y `\r` se convierten en `\n` antes de aplicar las reglas.
+ * @param {string} file
+ * @returns {string}
+ */
+export function readText(file) {
+  return readFileSync(file, "utf8").replace(/\r\n?/g, "\n");
+}

package/scripts/ensure-bin-exec.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 /**
- * Asegura que el CLI se publique con bit de ejecución.
+ * Asegura que el CLI y el gate de ADRs se publiquen con bit de ejecución.
  *
  * El blob de git solo distingue ejecutable / no ejecutable, y `npm pack`
- * conserva ese modo: un `bin/cli.js` en 100644 produce un tarball que algunos
+ * conserva ese modo: un binario en 100644 produce un tarball que algunos
  * gestores de paquetes no reparan. Se ejecuta en `prepack` para que el
  * artefacto sea correcto por sí mismo (A-007, A-052 §4).
  *
@@ -11,6 +11,11 @@
  */
 import { chmodSync } from "node:fs";
 
+const EXECUTABLES = ["bin/cli.js", "scripts/verify-adr-consistency.mjs"];
+const EXECUTABLE_MODE = 0o755;
+
 if (process.platform !== "win32") {
-  chmodSync("bin/cli.js", 0o755);
+  for (const executable of EXECUTABLES) {
+    chmodSync(executable, EXECUTABLE_MODE);
+  }
 }

package/scripts/verify-adr-consistency.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Gate de consistencia del registro ADR (ADR-0000).
+ *
+ * Valida cinco reglas y sale con código 0 solo si no hay violaciones:
+ *   - jerarquia    los ADRs no referencian tiers prohibidos (A solo cita A; T cita A y T;
+ *                  P cita A y P). Detecta tanto enlaces markdown como citas en texto plano a
+ *                  IDs `<PREFIJO>-NNN`: una cita con un prefijo no permitido para el tier —o
+ *                  con cualquier otro prefijo, incluidos G y PJ— es una violación, porque
+ *                  ningún ADR A/T/P referencia el tier de proyecto. Una misma referencia
+ *                  prohibida se reporta una sola vez aunque aparezca como enlace y como ID.
+ *   - enlaces      todos los enlaces markdown internos (relativos, *.md) resuelven a un
+ *                  archivo existente.
+ *   - frontmatter  el título H1 sigue `# <TIER>-<NNN>: Título` y los campos `originally` /
+ *                  `Enriquecido desde` usan la ortografía exacta.
+ *   - indices      cada ADR aparece en el índice de su tier y el índice no lista ADRs
+ *                  inexistentes.
+ *   - hardcoded    los ADRs activos no duplican listas cuya fuente canónica vive en el
+ *                  paquete (skills → @imolko/ultra-agent) ni en docs/agents/ (punteros).
+ *
+ * El gate resuelve su raíz desde su propia ubicación, no desde `process.cwd()`: se ejecuta
+ * contra el registro del repositorio que lo contiene. La implementación vive en
+ * `scripts/adr-gate/` para respetar las métricas de A-046; este archivo solo orquesta.
+ *
+ * Uso: node scripts/verify-adr-consistency.mjs
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { createRegistry } from "./adr-gate/registry.mjs";
+import { createReport } from "./adr-gate/report.mjs";
+import { ruleEnlaces } from "./adr-gate/rules/enlaces.mjs";
+import { ruleFrontmatter } from "./adr-gate/rules/frontmatter.mjs";
+import { ruleHardcoded } from "./adr-gate/rules/hardcoded.mjs";
+import { ruleIndices } from "./adr-gate/rules/indices.mjs";
+import { ruleJerarquia } from "./adr-gate/rules/jerarquia.mjs";
+import { resolvePath } from "./adr-gate/text.mjs";
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+const ROOT = path.dirname(path.dirname(resolvePath(SCRIPT_PATH)));
+
+/**
+ * Ejecuta las cinco reglas en el orden del gate original y emite el resultado:
+ * violaciones por stderr con exit 1, o el resumen limpio por stdout con exit 0.
+ * @returns {number} código de salida
+ */
+function main() {
+  const registry = createRegistry(ROOT);
+  const report = createReport();
+
+  ruleJerarquia(registry, report);
+  ruleEnlaces(registry, report);
+  ruleFrontmatter(registry, report);
+  ruleIndices(registry, report);
+  ruleHardcoded(registry, report);
+
+  if (report.violations.length > 0) {
+    for (const violation of report.violations) {
+      process.stderr.write(`${violation}\n`);
+    }
+    process.stderr.write(
+      `${report.violations.length} violación(es) en el registro ADR.\n`,
+    );
+    return 1;
+  }
+
+  process.stdout.write("Registro ADR consistente: 0 violaciones.\n");
+  return 0;
+}
+
+process.exitCode = main();

package/skills/writing-for-agents/references/adrs.md

@@ -6,7 +6,7 @@ The format, tier hierarchy, tag vocabulary, and lifecycle are owned by `<adr_dir
 
 ## The levers, instantiated
 
-- **Checkable, exhaustive completion criterion.** The gate `scripts/verify-adr-consistency.py` must exit `0` with zero violations. "Done" is a binary, machine-checked state — not a vague "understanding reached". This is the completion-criterion lever from `SKILL.md`, applied to a whole document family.
+- **Checkable, exhaustive completion criterion.** The gate `scripts/verify-adr-consistency.mjs` must exit `0` with zero violations. "Done" is a binary, machine-checked state — not a vague "understanding reached". This is the completion-criterion lever from `SKILL.md`, applied to a whole document family.
 - **Environment as source of truth (the cache rule).** The gate's `hardcoded` rule *is* the cache principle, enforced by machine.
 - **Single source of truth.** `<adr_dir>/index.md` is the canonical index, enforced by the `indices` gate rule.
 - **Context pointers.** `<adr_dir>/index.md` names each ADR and its tier — a real pointer hub doing both jobs (states what the material is, encodes when to reach it). Each tier's `index.md` is the same object one level down.
@@ -15,5 +15,5 @@ The format, tier hierarchy, tag vocabulary, and lifecycle are owned by `<adr_dir
 ## When writing an ADR
 
 - Follow `ADR-0000` exactly: Nygard sections, the project frontmatter, the tier matching the decision's scope, the approved tag vocabulary, the numbering and lifecycle rules.
-- Run the gate before finishing: `python3 scripts/verify-adr-consistency.py`. Exit `0` is the completion criterion.
+- Run the gate before finishing: `node scripts/verify-adr-consistency.mjs`. Exit `0` is the completion criterion.
 - Link related ADRs by relative markdown path (the `jerarquia` and `enlaces` gate rules check this); point at them, don't restate them.