Änderung (Brownfield)

Was macht Änderung (Brownfield)?

Fügen Sie eine begrenzte, überprüfbare Änderung an einer bestehenden Spezifikation und Codebasis hinzu, ohne ein neues PRD schreiben zu müssen. Eine Änderung erzeugt einen Vorschlag plus genau ein Aufgabenbündel aus vier Dokumenten. Nach bestandener Qualitätssicherung werden die bestätigten Änderungen zurück in die Spezifikation geschrieben und der Vorschlag archiviert. Diese Fähigkeit ist Prompt-zentriert: Jeder Schritt hat eine manuelle Rückfallebene und die gebündelten Skripte sind optionale Helfer.

Pipeline-Position: spec-generator -> Änderung -> task-decomposition -> plan-linter (Gate 1) -> review (Gate 2) -> dev -> qa -> converge -> Archiv.

vorhandene Spezifikation + begrenzte Änderung
  -> .specs/change-context/standards.md        (standards_extract.py; implizite Einschränkungen)
  -> .specs/changes/<change-id>/proposal.md    (Lebenszyklus: vorgeschlagen -> angewandt -> archiviert)
  -> tasks/<change-id>/01..04                  (ein Vertrag, ein Bündel)
  -> Gate 1 plan-linter -> Gate 2 review -> dev <-> qa -> converge -> archivierter Vorschlag

Verwendung

• Eine bestehende Spezifikation oder eine ausgelieferte Codebasis benötigt eine inkrementelle Änderung: einen Bugfix, eine kleine Funktion, ein Verhaltenstuning, eine begrenzte NFR-Anpassung.
• Die Änderung kann einen vorhandenen #sec-*-Anker wiederverwenden und passt in das Mikro-/Standard-Diff-Budget.
• Sie möchten den Vorschlag-→-Anwenden-→-Archivieren-Zyklus nutzen, während Sie das 4-Dokument-Aufgabenprotokoll und die Rollen 'Ein Besitzer pro Datei' dieses Repos beibehalten.

Nicht verwenden

• Wenn die Arbeit eine Neuentwicklung ist oder noch keine übergeordnete Spezifikation existiert: verwenden Sie prd-generator, dann spec-generator, dann task-decomposition.
• Wenn die Änderung eine neue Architekturentscheidung, eine neue Komponentengrenze, eine neue querschnittliche Invariante oder einen brandneuen Spezifikationsabschnitt (einen neuen #sec-*-Anker) benötigt: eskalieren Sie an spec-generator anstatt es in eine Änderung hineinzuschmuggeln.
• Wenn Sie lediglich eine genehmigte Spezifikation in Aufgaben aufteilen müssen: verwenden Sie task-decomposition.
• Wenn Sie lediglich vorhandene Bündel oder Vorschläge prüfen müssen: verwenden Sie plan-linter.
• Wenn die Aufgabe bereits geplant ist und auf Implementierung/Verifizierung wartet: verwenden Sie dev / qa.

Eingaben

• Die Basisspezifikation: standardmäßig .specs/02-tech-spec.md (und deren modulare Teile).
• Die Anforderung für die begrenzte Änderung, verfasst vom Anforderer in einfacher Sprache.
• Der in Schritt 1 generierte Bericht über die Repository-Konventionen.
• Optional: das vorhandene Aufgabenbündel, an das die Änderung anknüpft, sowie die relevanten ADRs.

Ausgaben

Artefakt	Besitzer nach dem Gerüstbau	Zweck
.specs/change-context/standards.md	Tooling	Deterministische Repository-Standards und implizite Einschränkungen (generiert, niemals manuell bearbeitet).
.specs/changes/<change-id>/proposal.md	Planer	Vorschlag für begrenzte Änderung: Motivation, inkrementelles Diff, Auswirkungsbereich, Invarianten/NFR, Rollback, Verifizierung.
.specs/changes/<change-id>/convergence.md	Converge-Tooling	Wird nach bestandener Qualitätssicherung geschrieben; zeichnet auf, was in die Spezifikation zurückgeführt wurde.
tasks/<change-id>/01-contract.md ... 04-process.md	Planer / Dev / QA / Tooling	Genau ein Bündel aus vier Dokumenten, das die Vorlagen der Aufgabenzerlegung wiederverwendet.

Der Vorschlag ist kein PRD und keine Ersatzspezifikation. Es ist ein Delta, das die vorhandenen Anker benennt, die es ändert. Vollständiger Lebenszyklus und Größenregeln: references/brownfield-protocol.md.

Arbeitsablauf

1. Repository-Standards extrahieren (einmal pro Konfigurationsänderung):

   python .agents/skills/change/scripts/standards_extract.py --repo-root . --json
   python .agents/skills/change/scripts/standards_extract.py --repo-root . --check
   

   Lesen Sie .specs/change-context/standards.md vor der Planung. Der Abschnitt „Implizite Einschränkungen" ist bindend: Verwenden Sie nur die darin belegten Befehle, respektieren Sie das deklarierte Testlayout, Laufzeitumgebungen und vorhandene Anker. Exit-Code 1 von --check bedeutet, dass der Bericht veraltet ist; regenerieren Sie ihn vor der Planung. Bearbeiten Sie den Bericht niemals manuell.

2. Gerüst für den Vorschlag und ein Aufgabenbündel erstellen (der einzige Schritt, der Dateien schreibt):

   python .agents/skills/change/scripts/scaffold_change.py \
     --change-id CHG-001-rate-limit \
     --title "Rate limit login attempts" \
     --anchor "#sec-auth-tokens" \
     --kind modify \
     --size-class micro --estimated-lines 40 \
     --touch-files "modify:src/auth/rate_limit.py" \
     --repo-root .
   

   Der Gerüstbauer validiert Anker gegen die Basisspezifikation, berechnet base_spec_sha256 und delegiert an task-decomposition (scaffold_task.py) oder gibt ein minimales Inline-Bündel aus, wenn dieses fehlt. Verwenden Sie --dry-run zur Vorschau und --force, um Wegwerf-Durchläufe zu überschreiben.

3. Planer füllt den Vorschlag und den Vertrag aus. Ersetzen Sie Platzhalter im Vorschlag (Motivation, [CHG-<n>]-Blöcke, Pfade, Invarianten/NFR, Rollback, Verifizierung) und Platzhalter im Vertrag (module, adherence_adrs, dod, Randfälle, Invarianten-Text). Erfinden Sie keine Pfade oder Anker. Lassen Sie die Rollenformulare 02/03 leer; behalten Sie im Vorschlag status: proposed bei.

4. Gate 1, dann Gate 2. Führen Sie das deterministische Gate 1 aus, dann die unabhängige semantische Überprüfung:

   # Vom Repository-Stammverzeichnis aus ausführen. Der Gate 1-Helfer setzt voraus, dass die plan-linter-Fähigkeit installiert ist.
   python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --repo-root . --spec .specs/02-tech-spec.md --changes-dir .specs/changes
   python .agents/skills/change/scripts/lint_change.py --change-id CHG-001-rate-limit --repo-root .
   

   Gate 1 muss vor der Implementierung bestanden sein; Gate 2 darf keine BLOCKED- oder REQUEST CHANGES-Ergebnisse melden.

5. Implementieren und verifizieren. Führen Sie dev (nur deklarierte touch_files, füllen Sie 02 aus, übergeben Sie) und qa (unabhängige Tests unter tests/acceptance/, füllen Sie 03 aus, ein Urteil) aus. Der Vorschlag wechselt zu applied, sobald Implementierung und Verifizierung bestanden sind.

6. Zusammenführen und archivieren. Nach QA_PASSED führen Sie converge aus, um bestätigte Abweichungen an .specs/02-tech-spec.md anzuhängen, convergence.md zu schreiben, das Bündel nach tasks/archive/ zu verschieben und den Vorschlag auf status: archived zu setzen. Ohne converge führen Sie das identische Anhängen manuell durch.

Manuelle Rückfallebene (kein Python)

1. Erstellen Sie manuell eine Liste der Standards: Repository-Stammkonfigurationen, Test-/Quellcodebäume, Laufzeitumgebungen, #sec-*-Anker.
2. Kopieren Sie assets/templates/proposal.template.md nach .specs/changes/<change-id>/proposal.md, füllen Sie jedes Token ({{...}}) aus und berechnen Sie base_spec_sha256.
3. Erstellen Sie das Bündel aus vier Dokumenten unter tasks/<change-id>/ unter Verwendung der task-decomposition-Vorlagen oder der Rückfallebene in references/brownfield-protocol.md.
4. Führen Sie die Gate 1 / Gate 2-Checklisten manuell aus; dokumentieren Sie die Nachweise im Bündel.
5. Befolgen Sie die Arbeitsschritte 5–6 mit denselben Artefakten.

Qualitätssicherungs-Checkliste

• Standardsbericht erstellt und aktuell (standards_extract.py --check beendet mit 0).
• Vorschlag-Vorspann vollständig, status: proposed, kind korrekt, base_spec_sha256 aktuell.
• Jeder [CHG-<n>]-Block benennt einen echten #sec-*-Anker, der in der Basisspezifikation existiert.
• Es existiert genau ein Aufgabenbündel; change_id entspricht der Vorschlags-ID und origin_spec_anchor ist einer der impact_anchors des Vorschlags.
• Diff-Budget eingehalten: Mikro ist 1 berührte Datei (Standard 10-49 Zeilen); Standard ist 1-3 Dateien (Standard 50-250 Zeilen). Zahlen im plan-linter-Konfiguration konfigurierbar.
• Gate 1 besteht für den ausgefüllten Vertrag und der Vorschlag ist offen (proposed/applied).
• Gate 2-Überprüfung hat keine blockierenden Feststellungen; der Prüfer ist unabhängig und hat nur Leserechte.
• Dev hat nur touch_files implementiert; QA hat genau ein Urteil mit Nachweisen ausgestellt.
• Converge hat Deltas an die Spezifikation angehängt und der Vorschlag ist archived.

Anti-Halluzinations-Regeln

• Erfinden Sie niemals Dateipfade. Jeder touch_files-Eintrag muss eine vorhandene Datei zum modify sein oder eine neue Datei in einem vorhandenen Verzeichnis zum create (Repository-relativ, mit Schrägstrichen).
• Jeder Diff-Block benennt einen echten Anker. Verwenden Sie einen vorhandenen #sec-*-Anker wieder; der Gerüstbauer und der Linter lehnen fehlende oder verschobene Anker ab.
• Erfinden Sie keine Befehle oder Konventionen. Im Vertrag DoD dürfen nur Befehle vorkommen, die durch die deklarierte Konfiguration (den Standardsbericht) belegt sind.
• Eine strukturelle Änderung wird eskaliert. Wenn die Änderung einen neuen Spezifikationsabschnitt/-anker, eine neue Komponente, ein neues ADR oder eine Invariantenänderung benötigt, stoppen Sie und verwenden Sie spec-generator.
• Übertreiben Sie die Tore nicht. Gate 1 ist deterministische Buchhaltung, Gate 2 ist Prompt-Überprüfung; Git und CI bleiben maßgeblich.

Hilfsskripte

• scripts/standards_extract.py — deterministischer Standards-Extraktor; schreibt .specs/change-context/standards.md (--json, --check, --dry-run, --version).
• scripts/scaffold_change.py — erstellt Vorschlag und ein Aufgabenbündel (--dry-run, --force, --json, --version).
• scripts/lint_change.py — Prüfung auf Konsistenz von Vorschlag/Bündel und Abweichung von der Basisspezifikation (--json, --version).

Alle Helfer sind stdlib-only, lösen ihr eigenes Verzeichnis auf und beenden mit 0 (Erfolg), 1 (Gate-Fehler), 2 (Nutzungsfehler), 3 (Unerwarteter Fehler).

Fehlerbehandlung

• Fehlende Basisspezifikation: Stopp. Eine Brownfield-Änderung erfordert eine Basisspezifikation; das Gerüst verlässt mit 2.
• Unbekannter Anker: Stopp und verwenden Sie einen vorhandenen Anker wieder, oder eskalieren Sie an spec-generator.
• Veralteter Bericht oder Spezifikationsabweichung (Exit 1): Bericht regenerieren, Vorschlag rebasen, Gate 1 erneut ausführen; base_spec_sha256 niemals manuell bearbeiten.
• Änderungsverzeichnis existiert: Nur mit --force erneut ausführen, wenn es sich um einen Wegwerf-Versuch handelt; andernfalls den vorhandenen Vorschlag bearbeiten.
• Skripte nicht verfügbar: Manuelle Rückfallebene befolgen; der Workflow ist Prompt-zentriert.

Ehrliche Grenzen

• Der Standardsbericht beschreibt deklarierte Konfiguration, nicht unbedingt erzwungene Praxis; er ist ein Prompt für den Planer, kein Nachweis der Einhaltung.
• base_spec_sha256 erkennt jede Byte-Änderung an der Basisspezifikation; nach der Zusammenführung ist der archivierte Vorschlag von Abweichungsprüfungen ausgenommen.
• Optionale Skripte können umgangen werden; CI plus Repository-Berechtigungen bleiben maßgeblich.