@imolko/ultra-agent 0.1.0-beta

package/pi/extensions/qa-guardrail/selection.ts

@@ -0,0 +1,98 @@
+/**
+ * Maps a file to the whitelisted adapter that covers it, using the config's
+ * `include`/`exclude` globs. Pure path logic: no filesystem access.
+ *
+ * `minimatch` is loaded lazily (and cached) on first use, so loading this
+ * module — and the extension that imports it — never requires `minimatch` to
+ * be installed. If it cannot be resolved, selection fails closed (no file
+ * matches, hence no adapter runs), mirroring the lazy-linter contract of
+ * A-049.
+ */
+
+import { createRequire } from "node:module";
+import { relative, resolve } from "node:path";
+import type { QaGuardrailConfig, ToolEntry } from "./types.js";
+
+/** Normalize a path to forward slashes for glob matching. */
+export function toPosixPath(p: string): string {
+  return p.split("\\").join("/");
+}
+
+type Minimatch = (path: string, pattern: string, options?: { dot?: boolean }) => boolean;
+
+let cachedMatcher: Minimatch | null | undefined;
+
+function loadMinimatch(): Minimatch | null {
+  try {
+    const require = createRequire(import.meta.url);
+    const minimatch = require("minimatch") as Minimatch;
+    return (path, pattern) => minimatch(path, pattern, { dot: true });
+  } catch {
+    return null;
+  }
+}
+
+function getMatcher(): Minimatch | null {
+  if (cachedMatcher === undefined) {
+    cachedMatcher = loadMinimatch();
+  }
+  return cachedMatcher;
+}
+
+/** Test seam: replace or clear the cached glob matcher (fail-closed when null). */
+export function setGlobMatcher(matcher: Minimatch | null | undefined): void {
+  cachedMatcher = matcher;
+}
+
+/**
+ * True when `absPath` is selected by the tool entry's include/exclude globs.
+ *
+ * - Files outside `cwd` never match.
+ * - An empty `include` list matches nothing (fail-closed, like ESLint flat config).
+ * - `exclude` wins over `include`.
+ * - A missing glob matcher matches nothing (fail-closed, never a load error).
+ */
+export function isFileSelected(absPath: string, entry: ToolEntry, cwd: string): boolean {
+  const rel = toPosixPath(relative(resolve(cwd), resolve(absPath)));
+  if (rel === "" || rel.startsWith("..")) {
+    return false;
+  }
+
+  const matcher = getMatcher();
+  if (!matcher) {
+    return false;
+  }
+
+  if (entry.include.length === 0) {
+    return false;
+  }
+  const included = entry.include.some((pattern) => matcher(rel, pattern));
+  if (!included) {
+    return false;
+  }
+  if (entry.exclude.length === 0) {
+    return true;
+  }
+  const excluded = entry.exclude.some((pattern) => matcher(rel, pattern));
+  return !excluded;
+}
+
+/**
+ * Return the id of the first enabled tool that covers `file`, or `undefined`.
+ */
+export function selectAdapterId(
+  file: string,
+  config: QaGuardrailConfig,
+  cwd: string,
+): string | undefined {
+  const absPath = resolve(cwd, file);
+  for (const entry of config.tools) {
+    if (entry.enabled === false) {
+      continue;
+    }
+    if (isFileSelected(absPath, entry, cwd)) {
+      return entry.id;
+    }
+  }
+  return undefined;
+}

package/pi/extensions/qa-guardrail/types.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared types for the qa-guardrail extension.
+ *
+ * These are the public contracts the modules exchange. They are intentionally
+ * small: a violation is the only shape that crosses the adapter boundary, and
+ * the config shape is the only shape that crosses the config boundary.
+ */
+
+/** A single lint violation, normalized from whatever the linter reports. */
+export interface Violation {
+  /** Rule id (e.g. "max-params"). `null` for fatal parse errors. */
+  ruleId: string | null;
+  /** Human-readable description from the linter. */
+  message: string;
+  /** 1-based line number. `0` when the linter reports no location. */
+  line: number;
+  /** 1-based column number. */
+  column: number;
+  /** ESLint severity: 1 = warning, 2 = error. */
+  severity: number;
+  endLine?: number;
+  endColumn?: number;
+}
+
+/** One tool entry in `.pi/qa-guardrail.json`. */
+export interface ToolEntry {
+  /** Whitelisted adapter id, e.g. "eslint". */
+  id: string;
+  /** Glob patterns of files this tool covers. Empty = covers nothing. */
+  include: string[];
+  /** Glob patterns of files this tool must never cover. */
+  exclude: string[];
+  /** Marker file names used to locate the project root (e.g. "package.json"). */
+  rootMarkers: string[];
+  /** Optional kill switch. Defaults to true. */
+  enabled?: boolean;
+}
+
+/** Root shape of `.pi/qa-guardrail.json`. */
+export interface QaGuardrailConfig {
+  tools: ToolEntry[];
+}
+
+/** Context handed to an adapter's `lint` call. */
+export interface LintContext {
+  /** Project root (directory containing the linter config, found via rootMarkers). */
+  root: string;
+  /** pi's current working directory. */
+  cwd: string;
+}
+
+/** Uniform adapter interface: `lint(file) → Violation[]`. */
+export interface LintAdapter {
+  /** Whitelisted id, e.g. "eslint". */
+  id: string;
+  /**
+   * Lint one file and return its violations. Returns `[]` for a clean or
+   * ignored file. Never fails silently: when linting is impossible (linter
+   * missing or its configuration broken), the implementation throws — the
+   * runner catches, warns, and skips feedback. Loading the extension never
+   * requires the linter.
+   */
+  lint(file: string, ctx: LintContext): Promise<Violation[]>;
+}

package/scripts/copy-assets.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+set -euo pipefail
+
+# Copia los prompts de fase del subcomando ship al árbol compilado (dist-node),
+# de modo que se publiquen como payload del paquete (A-039) y se lean en runtime.
+echo "Copiando prompts de ship..."
+mkdir -p dist-node/ship/prompts
+cp -r src/ship/prompts/. dist-node/ship/prompts/
+
+echo "Assets copiados correctamente."

package/scripts/reconcile-tags.sh

@@ -0,0 +1,94 @@
+#!/bin/bash
+set -euo pipefail
+
+# Reconciliación de etiquetas git desde el registry (T-025): cada versión
+# publicada en npm que no tenga etiqueta git se etiqueta en el commit que la
+# produjo, que npm expone como `gitHead`. Idempotente: las etiquetas que ya
+# existen no se recrean ni se mueven.
+#
+# El push usa el remote configurado por `scripts/release-build.sh`, que lleva
+# incrustada la credencial GITLAB_TOKEN (https://oauth2:${GITLAB_TOKEN}@...).
+# No se imprime la URL del remote ni el valor de la variable.
+
+source ./ci-helpers.sh
+
+PACKAGE_NAME="@imolko/ultra-agent"
+
+section_start "reconcile_tags" "Reconciliar etiquetas git con el registry"
+
+# 1. Leer las versiones publicadas. Un paquete aún no publicado no tiene nada
+#    que reconciliar: la primera versión se publica a mano con 2FA (T-025).
+set +e
+PUBLISHED_JSON="$(npm view "$PACKAGE_NAME" versions --json 2>/dev/null)"
+NPM_VIEW_CODE=$?
+set -e
+
+if [ "$NPM_VIEW_CODE" -ne 0 ] || [ -z "$PUBLISHED_JSON" ]; then
+  log_info "El paquete $PACKAGE_NAME aún no tiene versiones publicadas; no hay nada que reconciliar."
+  section_end "reconcile_tags"
+  exit 0
+fi
+
+VERSIONS_FILE="$(mktemp)"
+INPUT_FILE="$(mktemp)"
+trap 'rm -f "$VERSIONS_FILE" "$INPUT_FILE"' EXIT
+
+# Convierte el array JSON de versiones en una versión por línea.
+printf '%s\n' "$PUBLISHED_JSON" | node -e '
+  let data = "";
+  process.stdin.on("data", (c) => { data += c; });
+  process.stdin.on("end", () => {
+    const versions = JSON.parse(data) ?? [];
+    for (const version of versions) process.stdout.write(version + "\n");
+  });
+' > "$VERSIONS_FILE"
+
+# 2. Construye la entrada JSON para el CLI de reconciliación: las versiones
+#    publicadas con su `gitHead` (del registry, no del estado local) y las
+#    etiquetas git ya existentes.
+{
+  printf '{"published":['
+  first=1
+  while IFS= read -r version; do
+    [ -z "$version" ] && continue
+    git_head="$(npm view "${PACKAGE_NAME}@${version}" gitHead --json 2>/dev/null || true)"
+    if [ "$first" -eq 1 ]; then first=0; else printf ','; fi
+    if [ -n "$git_head" ]; then
+      # `npm view ... --json` devuelve el valor ya codificado como cadena JSON.
+      printf '{"version":"%s","gitHead":%s}' "$version" "$git_head"
+    else
+      printf '{"version":"%s","gitHead":null}' "$version"
+    fi
+  done < "$VERSIONS_FILE"
+
+  printf '],"existingTags":['
+  first=1
+  while IFS= read -r tag; do
+    [ -z "$tag" ] && continue
+    if [ "$first" -eq 1 ]; then first=0; else printf ','; fi
+    printf '"%s"' "$tag"
+  done < <(git tag --list)
+  printf ']}\n'
+} > "$INPUT_FILE"
+
+# 3. La decisión (qué versiones faltan) vive en el CLI; el shell solo crea y
+#    empuja las etiquetas planeadas.
+PLANS="$(node dist-node/reconcile.cli.js < "$INPUT_FILE")"
+
+if [ -z "$PLANS" ]; then
+  log_info "Todas las versiones publicadas ya tienen etiqueta; nada que reconciliar."
+else
+  while IFS=$'\t' read -r version commit; do
+    [ -z "$version" ] && continue
+    # Defensa de idempotencia: no recrear una etiqueta ya existente.
+    if git rev-parse -q --verify "refs/tags/$version" >/dev/null 2>&1; then
+      log_info "La etiqueta $version ya existe; se omite."
+      continue
+    fi
+    git tag "$version" "$commit"
+    git push origin "refs/tags/$version"
+    log_success "Etiqueta $version creada en $commit y empujada."
+  done <<< "$PLANS"
+fi
+
+section_end "reconcile_tags"

package/scripts/release-beta.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+set -euo pipefail
+
+# Publica la versión beta: la versión se deriva de los tipos de Conventional
+# Commits (A-033 §7) — feat→minor, fix→patch, breaking→major — vía
+# `dist-node/version.cli.js`. Sustituye las keywords ad hoc UPGRADE_*_VERSION.
+
+DEFAULT_BASE_VERSION="0.0.0"
+
+source ./ci-helpers.sh
+
+section_start "reconcile_tags" "Reconciliar etiquetas git publicadas"
+  # T-025: antes de derivar la versión, etiquetar en su `gitHead` toda versión
+  # ya publicada que no tenga etiqueta. Idempotente; empuja con GITLAB_TOKEN.
+  bash scripts/reconcile-tags.sh
+section_end "reconcile_tags"
+
+section_start "new_version_beta" "Calcular la nueva versión beta"
+  LATEST_BETA_TAG=$(git tag --list "*-beta" --sort=-version:refname | head -n 1)
+  if [ -z "$LATEST_BETA_TAG" ]; then
+    BASE_VERSION="$DEFAULT_BASE_VERSION"
+    COMMITS=$(git log --pretty=format:"%s")
+  else
+    BASE_VERSION="${LATEST_BETA_TAG%-beta}"
+    COMMITS=$(git log "${LATEST_BETA_TAG}..HEAD" --pretty=format:"%s")
+  fi
+  log_info "Último tag beta: ${LATEST_BETA_TAG:-<ninguno>}"
+  log_info "Versión base: $BASE_VERSION"
+
+  set +e
+  NEXT_BASE=$(printf '%s\n' "$COMMITS" | node dist-node/version.cli.js "$BASE_VERSION")
+  code=$?
+  set -e
+
+  if [ "$code" -ne 0 ]; then
+    log_info "No hay commits que muevan versión (feat/fix/breaking); se omite la publicación beta."
+    exit 0
+  fi
+
+  NEW_VERSION="${NEXT_BASE}-beta"
+  log_success "Versión a publicar: $NEW_VERSION"
+section_end "new_version_beta"
+
+section_start "publish_npm" "Publicando en npm"
+  npm version "$NEW_VERSION" --no-git-tag-version --allow-same-version || exit 1
+  echo "@imolko:registry=https://registry.npmjs.org/" > .npmrc
+  # Token stage-only (NPM_TOKEN), no el JWT OIDC: en el camino directo npm lo
+  # reemplaza por el token intercambiado vía OIDC (NPM_ID_TOKEN); en staging
+  # es la credencial que el mantenedor aprueba con 2FA.
+  echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" >> .npmrc
+
+  # T-025: el camino sale del claim `runner_environment` del token OIDC, no de
+  # una heurística sobre el runner. direct → npm publish (OIDC); staged →
+  # npm stage publish (token stage-only + aprobación 2FA).
+  PUBLICATION_PATH="$(node dist-node/publication.cli.js "${NPM_ID_TOKEN:-}")"
+
+  if [ "$PUBLICATION_PATH" = "direct" ]; then
+    log_info "Camino de publicación: direct (Trusted Publishing OIDC)"
+    npm publish --tag beta --access public || exit 1
+  else
+    log_info "Camino de publicación: staged (stage-only + 2FA)"
+    npm stage publish --tag beta --access public || exit 1
+  fi
+section_end "publish_npm"

package/scripts/release-build.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+set -euo pipefail
+
+source ./ci-helpers.sh
+
+# Pisos de toolchain para el camino OIDC de Trusted Publishing (T-025).
+# - Node ≥ 22.14.0: piso de runtime del flujo OIDC y de npm 11.
+# - npm ≥ 11.5.1: por debajo de esta versión `npm publish` no completa el
+#   intercambio OIDC y el camino directo fallaría de forma silenciosa.
+#   Se verifica en el job para evitar deriva.
+# - npm ≥ 11.21.0: piso de dist-tags por OIDC. Este flujo no publica dist-tags
+#   por OIDC, así que no se exige; queda documentado para no endurecer el job
+#   sin necesidad (T-025, notas adicionales del PRD).
+REQUIRED_NODE="22.14.0"
+REQUIRED_NPM="11.5.1"
+
+section_start "verify_toolchain" "Verificar pisos de versión de node y npm"
+  node -v
+  NODE_VERSION="$(node -v | sed 's/^v//')"
+  if ! printf '%s\n%s\n' "$REQUIRED_NODE" "$NODE_VERSION" | sort -V -C; then
+    log_error "node $NODE_VERSION no cumple el piso $REQUIRED_NODE requerido para Trusted Publishing (OIDC)."
+    exit 1
+  fi
+  log_success "node $NODE_VERSION cumple el piso $REQUIRED_NODE"
+
+  NPM_VERSION="$(npm -v)"
+  log_info "npm $NPM_VERSION"
+  if ! printf '%s\n%s\n' "$REQUIRED_NPM" "$NPM_VERSION" | sort -V -C; then
+    log_error "npm $NPM_VERSION no cumple el piso $REQUIRED_NPM requerido para Trusted Publishing (OIDC)."
+    exit 1
+  fi
+  log_success "npm $NPM_VERSION cumple el piso $REQUIRED_NPM"
+section_end "verify_toolchain"
+
+section_start "configure_git" "Configurar git y remote de push"
+  git config --global user.email "${GIT_USER_EMAIL}"
+  git config --global user.name "${GIT_USER_NAME}"
+  # La credencial GITLAB_TOKEN queda incrustada en el remote. No se imprime ni
+  # `git remote -v` ni el valor de la variable: la URL no debe aparecer en claro.
+  git remote set-url origin "https://oauth2:${GITLAB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
+section_end "configure_git"
+
+section_start "fetch_tags" "Traer historial y etiquetas completas"
+  # Tolerar el clon ya completo: `--unshallow` falla si el repositorio no es
+  # superficial, y ese caso no es un error.
+  git fetch --unshallow --tags || true
+  git fetch origin "+refs/tags/*:refs/tags/*"
+section_end "fetch_tags"
+
+section_start "build" "Construir el paquete"
+  npm install
+  npm run build
+section_end "build"

package/scripts/release.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+set -euo pipefail
+
+# Publica la versión estable: promueve el último tag beta quitando el sufijo
+# `-beta` (A-033 §7, canal beta→estable). No usa keywords ad hoc.
+
+source ./ci-helpers.sh
+
+section_start "reconcile_tags" "Reconciliar etiquetas git publicadas"
+  # T-025: antes de derivar la versión, etiquetar en su `gitHead` toda versión
+  # ya publicada que no tenga etiqueta. Idempotente; empuja con GITLAB_TOKEN.
+  bash scripts/reconcile-tags.sh
+section_end "reconcile_tags"
+
+section_start "new_version" "Calcular la versión estable a publicar"
+  LATEST_BETA_TAG=$(git tag --list "*-beta" --sort=-version:refname | head -n 1)
+  if [ -z "$LATEST_BETA_TAG" ]; then
+    log_error "No se encontró ningún tag beta para publicar"
+    exit 1
+  fi
+
+  RELEASE_VERSION="${LATEST_BETA_TAG%-beta}"
+  if git rev-parse "$RELEASE_VERSION" >/dev/null 2>&1; then
+    log_error "La versión $RELEASE_VERSION ya existe como tag"
+    exit 1
+  fi
+
+  log_success "Versión a publicar: $RELEASE_VERSION"
+section_end "new_version"
+
+section_start "publish_npm" "Publicando en npm"
+  npm version "$RELEASE_VERSION" --no-git-tag-version --allow-same-version || exit 1
+  echo "@imolko:registry=https://registry.npmjs.org/" > .npmrc
+  # Token stage-only (NPM_TOKEN), no el JWT OIDC: en el camino directo npm lo
+  # reemplaza por el token intercambiado vía OIDC (NPM_ID_TOKEN); en staging
+  # es la credencial que el mantenedor aprueba con 2FA.
+  echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" >> .npmrc
+
+  # T-025: el camino sale del claim `runner_environment` del token OIDC, no de
+  # una heurística sobre el runner. direct → npm publish (OIDC); staged →
+  # npm stage publish (token stage-only + aprobación 2FA).
+  PUBLICATION_PATH="$(node dist-node/publication.cli.js "${NPM_ID_TOKEN:-}")"
+
+  if [ "$PUBLICATION_PATH" = "direct" ]; then
+    log_info "Camino de publicación: direct (Trusted Publishing OIDC)"
+    npm publish --access public || exit 1
+  else
+    log_info "Camino de publicación: staged (stage-only + 2FA)"
+    npm stage publish --access public || exit 1
+  fi
+section_end "publish_npm"

package/scripts/verify-adr-consistency.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""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 no referencia T/P/proyecto;
+                 T/P no se referencian entre sí ni al tier de proyecto).
+  - 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).
+
+Uso: python3 scripts/verify-adr-consistency.py
+"""
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+ADR_DIR = ROOT / "docs" / "adr"
+
+TIER_DIRS = {
+    "A": ADR_DIR / "foundational",
+    "T": ADR_DIR / "typescript",
+    "P": ADR_DIR / "python",
+}
+
+H1_RE = re.compile(r"^# (A|T|P)-\d{3}: .+")
+ORIGINALLY_RE = re.compile(r"^\*\*originally\*\*:", flags=re.MULTILINE)
+ORIGINALLY_WRONG_RE = re.compile(r"^\*\*[Oo]riginally\*\*:", flags=re.MULTILINE)
+ENRICHED_RE = re.compile(r"^\*\*Enriquecido desde\*\*:", flags=re.MULTILINE)
+ENRICHED_WRONG_RE = re.compile(r"^\*\*[Ee]nriquecido [Dd]esde\*\*:", flags=re.MULTILINE)
+
+# Anchors caducados: la fuente canónica de los skills pasó al paquete y el hub de
+# punteros pasó a docs/agents/ (A-052). Un ADR activo no debe repetirlos.
+STALE_ANCHORS = (".pi/skills/", ".pi/repo-config.md")
+
+violations = []
+
+
+def report(rule: str, message: str) -> None:
+    violations.append(f"[{rule}] {message}")
+
+
+def is_active_adr(text: str) -> bool:
+    match = re.search(r"^\*\*Estado\*\*: ?(.+)$", text, flags=re.MULTILINE)
+    if not match:
+        return True
+    state = match.group(1).strip()
+    return state not in ("Reemplazado", "Deprecado")
+
+
+def tier_adr_files(tier: str):
+    return sorted(TIER_DIRS[tier].glob(f"{tier}-*.md"))
+
+
+def link_targets(text: str):
+    """Devuelve los destinos de los enlaces markdown inline `](dest)`. """
+    return re.findall(r"\]\(([^)]+)\)", text)
+
+
+def resolve_link(adir_file: Path, target: str):
+    """Resuelve un target de enlace relativo contra el directorio del ADR."""
+    target = target.strip()
+    if target.startswith(("<", ">")) or "://" in target or target.startswith("#"):
+        return None  # URL externa, autolink o ancla pura — fuera del gate
+    # Ignorar fragmentos (#ancla)
+    target = target.split("#", 1)[0]
+    if not target:
+        return None
+    if not target.endswith(".md"):
+        return None
+    return (adir_file.parent / target).resolve()
+
+
+def target_tier(resolved: Path):
+    """Clasifica un archivo resuelto en su tier (o None si está fuera del registro)."""
+    try:
+        rel = resolved.relative_to(ADR_DIR)
+    except ValueError:
+        return None
+    parts = rel.parts
+    if len(parts) >= 2:
+        if parts[0] == "foundational":
+            return "A"
+        if parts[0] == "typescript":
+            return "T"
+        if parts[0] == "python":
+            return "P"
+    if rel.name.startswith("ADR-0000") or rel.name == "index.md":
+        return "meta"
+    return "project"
+
+
+ALLOWED_TARGETS = {
+    "A": {"A", "meta"},
+    "T": {"A", "T", "meta"},
+    "P": {"A", "P", "meta"},
+}
+
+
+def rule_jerarquia() -> None:
+    for tier, allowed in ALLOWED_TARGETS.items():
+        for adr in tier_adr_files(tier):
+            text = adr.read_text(encoding="utf-8")
+            for target in link_targets(text):
+                resolved = resolve_link(adr, target)
+                if resolved is None:
+                    continue
+                resolved_tier = target_tier(resolved)
+                if resolved_tier is None:
+                    continue
+                if resolved_tier not in allowed:
+                    report(
+                        "jerarquia",
+                        f"{adr.relative_to(ROOT)} referencia al tier {resolved_tier} ({target}), prohibido para el tier {tier}",
+                    )
+
+
+def rule_enlaces() -> None:
+    for md in sorted(ADR_DIR.rglob("*.md")):
+        text = md.read_text(encoding="utf-8")
+        for target in link_targets(text):
+            resolved = resolve_link(md, target)
+            if resolved is None:
+                continue
+            if not resolved.exists():
+                report("enlaces", f"{md.relative_to(ROOT)} enlaza a un archivo inexistente: {target}")
+
+
+def rule_frontmatter() -> None:
+    for tier in ("A", "T", "P"):
+        for adr in tier_adr_files(tier):
+            text = adr.read_text(encoding="utf-8")
+            rel = adr.relative_to(ROOT)
+
+            first_line = text.splitlines()[0] if text.splitlines() else ""
+            if not H1_RE.match(first_line):
+                report("frontmatter", f"{rel}: el título H1 no sigue `# <TIER>-<NNN>: Título`")
+
+            if not ORIGINALLY_RE.search(text):
+                report("frontmatter", f"{rel}: falta el campo `**originally**:` (minúsculas)")
+
+            # Detectar ortografía incorrecta del campo
+            for line in text.splitlines():
+                stripped = line.strip()
+                if ORIGINALLY_WRONG_RE.match(stripped) and not ORIGINALLY_RE.match(stripped):
+                    report("frontmatter", f"{rel}: `originally` debe ir en minúsculas")
+                    break
+
+            for line in text.splitlines():
+                stripped = line.strip()
+                if ENRICHED_WRONG_RE.match(stripped) and not ENRICHED_RE.match(stripped):
+                    report("frontmatter", f"{rel}: el campo opcional debe escribirse `**Enriquecido desde**:`")
+                    break
+
+
+def rule_indices() -> None:
+    for tier in ("A", "T", "P"):
+        index = TIER_DIRS[tier] / "index.md"
+        if not index.exists():
+            report("indices", f"falta el índice del tier {tier}: {index.relative_to(ROOT)}")
+            continue
+
+        index_text = index.read_text(encoding="utf-8")
+        # Enlaces dentro del tier (`./<nombre>.md`)
+        index_targets = {t for t in link_targets(index_text) if t.startswith("./") and t.endswith(".md")}
+
+        adr_files = tier_adr_files(tier)
+        for adr in adr_files:
+            target = f"./{adr.name}"
+            if target not in index_targets:
+                report("indices", f"{adr.relative_to(ROOT)} no aparece en el índice de su tier")
+
+        for target in index_targets:
+            resolved = (TIER_DIRS[tier] / target[2:]).resolve()
+            if not resolved.exists():
+                report("indices", f"el índice {index.relative_to(ROOT)} lista un ADR inexistente: {target}")
+
+
+def rule_hardcoded() -> None:
+    for tier in ("A", "T", "P"):
+        for adr in tier_adr_files(tier):
+            text = adr.read_text(encoding="utf-8")
+            if not is_active_adr(text):
+                continue
+            for anchor in STALE_ANCHORS:
+                if anchor in text:
+                    report(
+                        "hardcoded",
+                        f"{adr.relative_to(ROOT)} duplica el ancla caducada `{anchor}` (fuente canónica: paquete/docs/agents)",
+                    )
+
+
+def main() -> int:
+    rule_jerarquia()
+    rule_enlaces()
+    rule_frontmatter()
+    rule_indices()
+    rule_hardcoded()
+
+    if violations:
+        for v in violations:
+            print(v, file=sys.stderr)
+        print(f"{len(violations)} violación(es) en el registro ADR.", file=sys.stderr)
+        return 1
+
+    print("Registro ADR consistente: 0 violaciones.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())