Plan Linter (Validateur de la Porte 1)

Que fait Plan Linter (Validateur de la Porte 1) ?

Cette compétence a une responsabilité unique et strictement délimitée : la validation statique déterministe de la Porte 1 des contrats et bundles de tâches prévus sous tasks/ avant le début du développement.

• Porte 1 : un script déterministe dans cette compétence : rapide, hors ligne, stdlib uniquement.
• Porte 2 : une révision sémantique par prompt uniquement (compétence review, avec references/gate-2-review.md en solution de repli).
• Non-objectifs : plan-linter n'exécute PAS de code, ne construit ni n'exécute de pipelines CI, n'effectue PAS d'analyse AST/complexité de code et n'audite PAS les tests ni les preuves de complexité/QA enregistrées dans 03-qa-verification.md (seulement une vérification d'existence et un balayage des espaces réservés). Tous les pipelines CI et les portes de vérification sont gérés par quality-engineering ; les tests locaux sont gérés par qa.

Porte 1 : vérifications déterministes

Vérification	Par défaut	Remplaçable
01-contract.md existe avec des métadonnées valides	requis	non
task_id est égal au nom du répertoire	requis	non
task_id est unique entre les bundles	requis	non
nombre de touch_files	1..3	max_touch_files
estimated_lines	50..250	min_diff_lines, max_diff_lines
origin_spec_anchor correspond à #sec-[a-z0-9-]+	requis	require_anchor
adherence_adrs liste au moins un ADR	requis	require_adrs
dod.type_check, dod.lint, dod.test_file	requis	non
nombre de dod.edge_cases	au moins 2	min_edge_cases
02-dev-workspace.md, 03-qa-verification.md, 04-process.md existent	requis	require_docs
préfixes de touch interdits	tests/acceptance/	forbidden_touch_prefixes
espaces réservés non résolus dans 01/02/03	bloquant	scan_placeholders
Preuves de QA au niveau du contenu de 03-qa-verification.md	pas audité (Porte 3)	non
Topologie inverse : les chemins de modification existent, les chemins de création n'existent pas	avertissement	check_topology, strict_topology, --repo-root
size_class micro : change_id présent, 1 fichier touché, budget plus petit	requis lorsque micro	micro_min_diff_lines, micro_max_touch_files
change_id a une proposition ouverte sous le répertoire de changement	requis lorsque --changes-dir est fourni	--changes-dir
Matrice de couverture des ancres de spécification (sections non couvertes)	rapport ; erreur avec --require-full-coverage	--spec, --coverage-out
Ancres de contrat absentes de la spécification	avertissement ; erreur avec --strict-anchor	--spec
Graphe de dépendances	acyclique, pas de tâches manquantes	non

Tout est vérifié ; l'ordre dans la sortie est stable.

Démarrage rapide

# Rapport standard ou JSON lisible par machine
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

# Configuration personnalisée ou format legacy
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

# Heuristiques de la Porte 2 et mode CI bloquant
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

Le script est optionnel. Si Python n'est pas disponible, utilisez references/gate-2-review.md comme checklist manuelle et révisez les mêmes champs à la main.

La Porte 2 est la compétence review séparée. Après que la Porte 1 se termine avec le code 0, utilisez la compétence review (mode plan-review) si elle est installée pour l'audit sémantique indépendant. Cette compétence conserve references/gate-2-review.md comme solution de repli autonome lorsque la compétence review n'est pas installée ; elle ne remplace jamais la Porte 1.

Codes de sortie

Code	Signification
0	Porte 1 réussie pour chaque bundle de tâches
1	Violations trouvées (ou un frontmatter de contrat ne peut pas être parsé)
2	Erreur d'utilisation ou de configuration
3	Erreur interne inattendue

Format du contrat

Le frontmatter YAML de 01-contract.md est faisant autorité. Les tableaux humains ci-dessous sont des aides à la lecture optionnelles.

---
task_id: task-001-auth
title: "Authentification utilisateur"
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:
    - "des identifiants vides renvoient 400"
    - "un jeton expiré renvoie 401"
---

Règles :

• task_id doit être égal au nom du répertoire de la tâche ; les chemins sont relatifs au dépôt avec des barres obliques.
• touch_files ne peut pas pointer vers des préfixes interdits (tests/acceptance/ par défaut).
• Ne laissez pas d'espaces réservés ({{...}}, [TBD], TODO) dans 01/02/03.

Solution de repli legacy

Les contrats sans frontmatter YAML utilisent une solution de repli basée sur des tableaux pour les mises en page pré-v2, en affichant un avertissement LEGACY_FORMAT. Ajoutez --legacy pour forcer la solution de repli.

Configuration

{
  "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"]
}

Les seuils sont des conventions de dépôt, pas des lois universelles. Remplacez-les par projet ; les clés inconnues produisent un avertissement, tandis que les valeurs mal typées font sortir avec le code 2.

Sortie 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 est présent uniquement lorsque --spec est passé ; --coverage-out l'écrit dans un fichier.

Chaque objet d'erreur a les clés task, code, message, file et line. Les codes d'erreur sont des identifiants anglais stables (p. ex. 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). Les propositions archivées produisent CHANGE_ALREADY_ARCHIVED au lieu d'une erreur, et ignore_task_dirs (tasks/archive) ne sont jamais scannés comme bundles en attente. Référence complète des erreurs : references/gate-2-review.md.

Porte 2 : révision sémantique (prompt uniquement)

Après que la Porte 1 a réussi, suivez references/gate-2-review.md en tant que réviseur indépendant. Résumez comme :

• Révision du plan Porte 2 réussie : 0 omissions, 0 hallucinations ; ou
• Liste des constatations : répertoire de la tâche, champs contaminés et identifiants ADR violés.

La Porte 2 est manuelle : un script ne peut pas juger de la véracité sémantique. Ne passez pas sans avoir révisé.

Portabilité, limites et non-objectifs

Le script est stdlib uniquement, se résout par rapport à son propre répertoire et n'écrit jamais de fichiers.

Limites strictes et non-objectifs :

• Pas d'exécution de code : n'exécute jamais les commandes de DoD, le code d'application ou les suites de tests.
• Pas d'orchestration CI : ne construit, ne gère ni n'exécute de pipelines CI (géré par quality-engineering).
• Pas d'analyse AST ou de complexité : ne calcule pas la complexité cyclomatique $V(G)$ (géré par quality-engineering).
• Pas d'audit de test ou de vérification : n'audite pas les preuves QA de 03. Seulement la vérification d'existence des quatre documents et le balayage des espaces réservés non résolus touchent 03-qa-verification.md ; la complexité, la couverture des chemins de base et le MSI de mutation sont audités par la Porte 3 (quality-engineering/verification_linter.py).
• Pas de jugement sémantique : ne juge pas la véracité sémantique (Porte 2 est une révision par prompt).
• Pas d'application du RBAC : ne remplace pas l'audit RBAC basé sur git.

Références

• Checklist de la Porte 2
• Référence des codes d'erreur
• Spécification technique