Plan-Linter (Gate 1 Planungsprüfung)

Plan-Linter (Gate-1 Planungsprüfer)

Diese Fertigkeit hat eine einzige, streng abgegrenzte Verantwortung: Gate-1 deterministische statische Validierung von geplanten Aufgabenverträgen und Paketen unter tasks/ vor Entwicklungsbeginn.

• Gate 1 ist ein deterministisches Skript in dieser Fertigkeit: schnell, offline, nur Stdlib.
• Gate 2 ist eine reine Prompt-basierte semantische Überprüfung (review-Fertigkeit, mit references/gate-2-review.md als Fallback).
• Nicht-Ziele: Der Plan-Linter führt KEINEN Code aus, baut KEINE CI-Pipelines auf, führt KEINE AST-/Code-Komplexitätsanalyse durch und prüft KEINE Tests oder die QA-Komplexitäts-/Mutationsnachweise, die in 03-qa-verification.md festgehalten sind (nur Platzhalter-Scan und Existenzprüfung). Alle CI-Pipelines und Verifikationsgatter gehören zu quality-engineering; lokale Tests gehören zu qa.

Gate 1: Deterministische Prüfungen

Prüfung	Standard	Überschreibbar
01-contract.md existiert und hat gültige Metadaten	erforderlich	nein
task_id entspricht dem Verzeichnisnamen	erforderlich	nein
task_id ist eindeutig über alle Pakete hinweg	erforderlich	nein
Anzahl der touch_files	1..3	max_touch_files
Geschätzte Zeilen	50..250	min_diff_lines, max_diff_lines
origin_spec_anchor entspricht #sec-[a-z0-9-]+	erforderlich	require_anchor
adherence_adrs listet mindestens eine ADR auf	erforderlich	require_adrs
dod.type_check, dod.lint, dod.test_file	erforderlich	nein
Anzahl der dod.edge_cases	mindestens 2	min_edge_cases
02-dev-workspace.md, 03-qa-verification.md, 04-process.md existieren	erforderlich	require_docs
Verbotene Touch-Präfixe	tests/acceptance/	forbidden_touch_prefixes
Unaufgelöste Platzhalter in 01/02/03	blockiert	scan_placeholders
Inhaltliche QA-Nachweise in 03-qa-verification.md	nicht geprüft (Gate 3)	nein
Reverse-Topologie: Ändern-Pfade existieren, Erstellen-Pfade existieren nicht	Warnung	check_topology, strict_topology, --repo-root
Größenklasse Mikro: change_id vorhanden, 1 Touch-Datei, kleineres Budget	erforderlich bei Mikro	micro_min_diff_lines, micro_max_touch_files
change_id hat einen offenen Vorschlag im Change-Verzeichnis	erforderlich, wenn --changes-dir angegeben	--changes-dir
Spezifikationsanker-Abdeckungsmatrix (nicht abgedeckte Abschnitte)	Bericht; Fehler mit --require-full-coverage	--spec, --coverage-out
Vertragsanker, die in der Spezifikation fehlen	Warnung; Fehler mit --strict-anchor	--spec
Abhängigkeitsgraph	azyklisch, keine fehlenden Aufgaben	nein

Alles wird geprüft; die Reihenfolge in der Ausgabe ist stabil.

Kurzanleitung

# Standardbericht oder maschinenlesbares JSON
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

# Benutzerdefinierte Konfiguration oder Legacy-Format
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

# Gate-2-Heuristiken und blockierender CI-Modus
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

Das Skript ist optional. Falls Python nicht verfügbar ist, verwenden Sie references/gate-2-review.md als manuelle Checkliste und prüfen Sie dieselben Felder manuell.

Gate 2 ist die separate review-Fertigkeit. Nachdem Gate 1 mit 0 beendet wurde, verwenden Sie die review-Fertigkeit (Plan-Review-Modus), wenn sie installiert ist, für die unabhängige semantische Prüfung. Diese Fertigkeit behält references/gate-2-review.md als eigenständigen Fallback, wenn die Review-Fertigkeit nicht installiert ist; sie ersetzt Gate 1 nie.

Exit-Codes

Code	Bedeutung
0	Gate 1 bestanden für jedes Aufgabenpaket
1	Verstöße gefunden (oder ein Vertrags-Frontmatter kann nicht geparst werden)
2	Verwendungs- oder Konfigurationsfehler
3	Unerwarteter interner Fehler

Vertragsformat

Das YAML-Frontmatter von 01-contract.md ist verbindlich. Die darunterliegenden menschlichen Tabellen sind optionale Lesbarkeitshilfen.

---
task_id: task-001-auth
title: "Benutzerauthentifizierung"
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:
    - "leere Anmeldedaten geben 400 zurück"
    - "abgelaufener Token gibt 401 zurück"
---

Regeln:

• task_id muss dem Aufgabenverzeichnisnamen entsprechen; Pfade sind Repository-relativ mit normalen Schrägstrichen.
• touch_files dürfen nicht auf verbotene Präfixe zeigen (standardmäßig tests/acceptance/).
• Lassen Sie keine Platzhalter ({{...}}, [TBD], TODO) in 01/02/03 zurück.

Legacy-Fallback

Verträge ohne YAML-Frontmatter verwenden einen Tabellen-Fallback für Pre-v2-Layouts und geben eine LEGACY_FORMAT-Warnung aus. Fügen Sie --legacy hinzu, um den Fallback zu erzwingen.

Konfiguration

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

Die Schwellenwerte sind Repository-Konventionen, keine universellen Gesetze. Überschreiben Sie sie projektweise; unbekannte Schlüssel erzeugen eine Warnung, falsch typisierte Werte führen zu Exit 2.

JSON-Ausgabe

{
  "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 ist nur vorhanden, wenn --spec übergeben wird; --coverage-out schreibt es in eine Datei.

Jedes Fehlerobjekt hat die Schlüssel task, code, message, file und line. Fehlercodes sind stabile englische Bezeichner (z.B. 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). Archivierte Vorschläge erzeugen CHANGE_ALREADY_ARCHIVED anstelle eines Fehlers, und ignore_task_dirs (tasks/archive) werden niemals als ausstehende Pakete gescannt. Vollständige Fehlerreferenz: references/gate-2-review.md.

Gate 2: Semantische Überprüfung (nur Prompt)

Nachdem Gate 1 bestanden ist, folgen Sie references/gate-2-review.md als unabhängiger Prüfer. Fassen Sie zusammen als entweder:

• Gate 2 Plan Review Bestanden: 0 Auslassungen, 0 Halluzinationen; oder
• Fundliste: Aufgabenverzeichnis, kontaminierte Felder und verletzte ADR-IDs.

Gate 2 ist manuell: Ein Skript kann keine semantische Wahrhaftigkeit beurteilen. Nicht bestehen, ohne dass die Überprüfung durchgeführt wurde.

Portabilität, Grenzen und Nicht-Ziele

Das Skript verwendet nur die Stdlib, löst Pfade relativ zu seinem eigenen Verzeichnis auf und schreibt niemals Dateien.

Strenge Grenzen und Nicht-Ziele:

• Keine Codeausführung: Führt niemals DoD-Befehle, Anwendungscode oder Testsuiten aus.
• Keine CI-Orchestrierung: Baut keine CI-Pipelines auf, verwaltet sie nicht und führt sie nicht aus (gehört zu quality-engineering).
• Keine AST- oder Komplexitätsanalyse: Berechnet keine zyklomatische Komplexität $V(G)$ (gehört zu quality-engineering).
• Keine Test- oder Verifikationsprüfung: Prüft keine QA-Nachweise aus 03. Nur die Existenzprüfung der vier Dokumente und der Scan auf unaufgelöste Platzhalter berühren 03-qa-verification.md; Komplexität, Basiswegabdeckung und Mutations-MSI werden von Gate 3 (quality-engineering/verification_linter.py) geprüft.
• Kein semantisches Urteil: Beurteilt keine semantische Wahrhaftigkeit (Gate 2 ist Prompt-Review).
• Keine RBAC-Durchsetzung: Ersetzt nicht die git-basierte RBAC-Prüfung.