Plan Linter (Validador de Planificación Gate 1)

¿Qué hace Plan Linter (Validador de Planificación Gate 1)?

Este skill tiene una única responsabilidad estrictamente delimitada: validación estática determinística Gate 1 de los contratos y paquetes de tareas planificados bajo tasks/ antes de comenzar el desarrollo.

• Gate 1 es un script determinístico en este skill: rápido, offline, solo con la biblioteca estándar.
• Gate 2 es una revisión semántica solo con indicaciones (skill review, con references/gate-2-review.md como respaldo).
• No objetivos: plan-linter NO ejecuta código, NO construye ni ejecuta pipelines de CI, NO realiza análisis AST/complejidad de código, y NO audita pruebas ni la evidencia de complejidad/mutación registrada en 03-qa-verification.md (solo escaneo de marcadores de posición y comprobaciones de existencia). Todos los pipelines de CI y puertas de verificación son propiedad de quality-engineering; las pruebas locales son propiedad de qa.

Puerta 1 (Gate 1): comprobaciones determinísticas

Comprobación	Valor por defecto	Sobrescribible
01-contract.md existe y tiene metadatos válidos	requerido	no
task_id es igual al nombre del directorio	requerido	no
task_id es único entre todos los paquetes	requerido	no
Número de touch_files	1..3	max_touch_files
estimated_lines	50..250	min_diff_lines, max_diff_lines
origin_spec_anchor coincide con #sec-[a-z0-9-]+	requerido	require_anchor
adherence_adrs lista al menos un ADR	requerido	require_adrs
dod.type_check, dod.lint, dod.test_file	requerido	no
Número de dod.edge_cases	al menos 2	min_edge_cases
02-dev-workspace.md, 03-qa-verification.md, 04-process.md existen	requerido	require_docs
Prefijos de touch prohibidos	tests/acceptance/	forbidden_touch_prefixes
Marcadores de posición sin resolver en 01/02/03	bloqueado	scan_placeholders
Evidencia de QA a nivel de contenido en 03-qa-verification.md	no auditada (Puerta 3)	no
Topología inversa: rutas de modificar existen, rutas de crear no	advertencia	check_topology, strict_topology, --repo-root
size_class micro: change_id presente, 1 archivo tocado, presupuesto menor	requerido cuando micro	micro_min_diff_lines, micro_max_touch_files
change_id tiene una propuesta abierta bajo el directorio de cambios	requerido cuando se da --changes-dir	--changes-dir
Matriz de cobertura de anclajes de especificación (secciones descubiertas)	informe; error con --require-full-coverage	--spec, --coverage-out
Anclajes de contrato ausentes en la especificación	advertencia; error con --strict-anchor	--spec
Grafo de dependencias	acíclico, sin tareas faltantes	no

Todo se comprueba; el orden en la salida es estable.

Inicio rápido

# Informe estándar o JSON legible por máquina
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --json

# Configuración personalizada o formato heredado
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --config plan-linter.json
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --legacy

# Heurísticas de Gate 2 y modo CI bloqueante
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks \
  --repo-root . --spec .specs/02-tech-spec.md --changes-dir .specs/changes --json
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks \
  --spec .specs/02-tech-spec.md --strict-topology --strict-anchor --require-full-coverage

El script es opcional. Si Python no está disponible, usa references/gate-2-review.md como lista de verificación manual y revisa los mismos campos manualmente.

Gate 2 es el skill review separado. Después de que Gate 1 salga con 0, usa el skill review (modo plan-review) cuando esté instalado para la auditoría semántica independiente. Este skill mantiene references/gate-2-review.md como un respaldo autónomo cuando el skill review no está instalado; nunca reemplaza Gate 1.

Códigos de salida

Código	Significado
0	Gate 1 pasó para cada paquete de tareas
1	Se encontraron violaciones (o no se puede analizar el frontmatter de un contrato)
2	Error de uso o configuración
3	Error interno inesperado

Formato del contrato

El frontmatter YAML de 01-contract.md es la fuente autoritativa. Las tablas humanas debajo de él son ayudas de legibilidad opcionales.

---
task_id: task-001-auth
title: "Autenticación de usuario"
module: auth
dependencies: [task-000-bootstrap]
estimated_lines: 120
touch_files:
  - action: create
    path: src/auth/service.py
  - action: modify
    path: src/auth/routes.py
origin_spec_anchor: "#sec-auth"
adherence_adrs: [ADR-001]
dod:
  type_check: "npm run type-check"
  lint: "npm run lint"
  test_file: "tests/acceptance/test_auth.ts"
  edge_cases:
    - "credenciales vacías devuelven 400"
    - "token expirado devuelve 401"
---

Reglas:

• task_id debe ser igual al nombre del directorio de la tarea; las rutas son relativas al repositorio con barras inclinadas.
• touch_files no puede apuntar a prefijos prohibidos (tests/acceptance/ por defecto).
• No dejes marcadores de posición ({{...}}, [TBD], TODO) en 01/02/03.

Respaldo heredado

Los contratos sin frontmatter YAML usan un respaldo basado en tabla para diseños previos a v2, imprimiendo una advertencia LEGACY_FORMAT. Añade --legacy para forzar el respaldo.

Configuración

{
  "max_touch_files": 3,
  "min_diff_lines": 50,
  "max_diff_lines": 250,
  "require_anchor": true,
  "require_adrs": true,
  "min_edge_cases": 2,
  "require_docs": ["02-dev-workspace.md", "03-qa-verification.md", "04-process.md"],
  "forbidden_touch_prefixes": ["tests/acceptance/"],
  "scan_placeholders": true,
  "micro_min_diff_lines": 10,
  "micro_max_touch_files": 1,
  "check_topology": true,
  "strict_topology": false,
  "ignore_task_dirs": ["archive"]
}

Los umbrales son convenciones del repositorio, no leyes universales. Sobrescríbelos por proyecto; las claves desconocidas producen una advertencia, mientras que los valores mal tipificados salen con código 2.

Salida JSON

{
  "gate": "1",
  "passed": true,
  "tasks_scanned": 3,
  "errors": [],
  "warnings": [],
  "coverage": {
    "spec": ".specs/02-tech-spec.md",
    "spec_anchors": 3,
    "covered": ["#sec-alpha", "#sec-beta"],
    "uncovered": ["#sec-gamma"],
    "contract_anchors_missing_from_spec": [],
    "coverage_ratio": 0.6667
  }
}

coverage solo está presente cuando se pasa --spec; --coverage-out lo escribe en un archivo.

Cada objeto de error tiene las claves task, code, message, file y line. Los códigos de error son identificadores en inglés estables (por ejemplo, MISSING_DOC, TASK_ID_MISMATCH, DAG_CYCLE, PLACEHOLDER, TOUCH_FILE_MISSING, FORBIDDEN_TOUCH_FILE, BDD_MISSING_PRECONDITION, BDD_MISSING_ACTION, BDD_MISSING_OUTCOME, BDD_INVALID_SCENARIO, SPEC_SECTION_UNCOVERED). Las propuestas archivadas producen CHANGE_ALREADY_ARCHIVED en lugar de un error, y ignore_task_dirs (tasks/archive) nunca se escanean como paquetes pendientes. Referencia completa de errores: references/gate-2-review.md.

Puerta 2 (Gate 2): revisión semántica (solo con indicaciones)

Después de que Gate 1 pase, sigue references/gate-2-review.md como un revisor independiente. Resume como:

• Gate 2 Plan Review Passed: 0 omissions, 0 hallucinations; o
• Lista de hallazgos: directorio de tarea, campos contaminados, e IDs de ADR violados.

Gate 2 es manual: un script no puede juzgar la veracidad semántica. No continúes a menos que se haya revisado.

Portabilidad, límites y no objetivos

El script solo usa la biblioteca estándar, resuelve rutas relativas a su propio directorio y nunca escribe archivos.

Límites estrictos y no objetivos:

• Sin ejecución de código: nunca ejecuta comandos de DoD, código de aplicación o suites de pruebas.
• Sin orquestación de CI: no construye, gestiona ni ejecuta pipelines de CI (responsabilidad de quality-engineering).
• Sin análisis AST o de complejidad: no calcula complejidad ciclomática $V(G)$ (responsabilidad de quality-engineering).
• Sin auditoría de pruebas o verificación: no audita la evidencia de QA en 03. Solo la comprobación de existencia de cuatro documentos y el escaneo de marcadores de posición sin resolver tocan 03-qa-verification.md; la complejidad, la cobertura de caminos base y el MSI de mutación son auditados por Gate 3 (quality-engineering/verification_linter.py).
• Sin juicio semántico: no juzga la veracidad semántica (Gate 2 es revisión con indicaciones).
• Sin control de RBAC: no reemplaza la auditoría RBAC basada en git.