Converge - Spezifikations-Rückschreibung nach QA

Was macht Converge - Spezifikations-Rückschreibung nach QA?

Schließe den Ausführungskreislauf: Eine Aufgabe, die QA bestanden hat, wird Teil der lebenden Spezifikation. Dieses Skill repräsentiert die ConvergeTool-Rolle im Lebenszyklus. Es definiert den Prozess; Repository-Agentenregeln besitzen weiterhin die Berechtigungen, und dieses Skill gewährt niemals zusätzlichen Zugriff.

Pipeline-Position: dev -> qa -> converge -> archiviertes Bundle + aktualisierte Spezifikation.

Verwenden, wenn

• Das Aufgabenpaket 03-qa-verification.md enthält ein bestätigtes QA_PASSED-Urteil.
• 02-dev-workspace.md die eingefrorene Tabelle der Implementierungsabweichungen enthält (Zeilen oder eine explizite Keine-Zeile).
• Das bestätigte Verhalten der Aufgabe in .specs/02-tech-spec.md aufgenommen, das Paket archiviert und der ursprüngliche Änderungsvorschlag geschlossen werden muss.

Nicht verwenden, wenn

• Implementierung oder QA noch läuft, das Übergabemerkmal nicht gesetzt ist oder REWORK_REQUIRED aktiv ist – warte auf ein stabiles QA_PASSED-Urteil.
• Das Abweichungsprotokoll leer oder fehlend ist – sende die Aufgabe zurück an Dev, anstatt zu raten.
• Sie Spezifikationsinhalte erfinden oder bestehende Spezifikationstexte umschreiben müssten; das ist eine Planungsänderung, keine Konvergenz.

Eingaben

• tasks/<task-id>/01-contract.md - Titel, Nachverfolgbarkeitsanker, optional change_id.
• tasks/<task-id>/02-dev-workspace.md - die Tabelle der Implementierungsabweichungen (eingefrorenes Format).
• tasks/<task-id>/03-qa-verification.md - das bestätigte QA_PASSED-Urteil und Nachweise.
• tasks/<task-id>/04-process.md - abgeleitete Statuskarte und Ereignisprotokoll.
• .specs/02-tech-spec.md - die lebende technische Spezifikation.
• .specs/changes/<change-id>/proposal.md - der ursprüngliche Änderungsvorschlag, falls vorhanden.

Ausgaben

• Ein datierter, attributierter Eintrag pro Aufgabe im Converged changes-Abschnitt der Spezifikation.
• Ein Konvergenzmarker pro Aufgabe: <!-- converged: <task-id> sha256:<hash> -->.
• 04-process.md mit macro_status: "CONVERGED" und einer TASK_CONVERGED-Ereigniszeile (Akteur ConvergeTool).
• Das Aufgabenpaket verschoben (niemals gelöscht) nach tasks/archive/<task-id>/.
• .specs/changes/<change-id>/convergence.md plus Proposal-Status archived, falls ein Proposal existiert.

Prüfen -> anwenden -> verifizieren

1. Prüfen. Klassifiziere Pakete, bevor du etwas schreibst: python .agents/skills/converge/scripts/converge.py check --tasks-dir ./tasks --json Ein Paket ist nur dann konvergenzbereit, wenn QA bestanden ist, keine Nacharbeit aktiv ist, die Abweichungstabelle mindestens eine Zeile oder eine explizite Keine-Zeile enthält und die Spezifikation bereits nicht dessen Marker trägt.
2. Anwenden. Konvergiere ein Paket: python .agents/skills/converge/scripts/converge.py apply --task tasks/<task-id> Verwende zuerst --dry-run, um die geplanten Schreibvorgänge zu prüfen. Der Helfer verweigert mit Exit-Code 1, wenn das Paket nicht konvergenzbereit ist, und verweigert ein vorhandenes Archivziel, außer mit --force.
3. Verifizieren. Führe check erneut aus, bestätige, dass der Marker vorhanden ist, 04-process.md CONVERGED sagt, das Paket archiviert ist und --spec-sha256 mit dem erwarteten CI-Wert übereinstimmt: python .agents/skills/converge/scripts/converge.py --spec .specs/02-tech-spec.md --spec-sha256

Manueller Fallback (kein Python)

Wenn der Helfer nicht verfügbar ist, führe dieselben Schritte manuell aus und halte die Marker exakt:

1. Bestätige, dass QA_PASSED in 03 gesetzt ist und kein REWORK_REQUIRED aktiv ist.
2. Lese die Abweichungszeilen aus 02; lehne ein leeres Protokoll ab.
3. Hänge (nicht bearbeiten) einen Eintrag an den Converged changes-Abschnitt der Spezifikation an: eine ### <task-id>-Überschrift, die Abweichungstabelle und den <!-- converged: <task-id> sha256:<hash> -->-Marker. Berechne den Hash mit einem beliebigen SHA-256-Tool über die normalisierte Aufgaben-ID und die Zeilen.
4. Setze macro_status auf CONVERGED in 04 und füge die TASK_CONVERGED / ConvergeTool-Zeile an.
5. Verschiebe, niemals lösche, das Paket nach tasks/archive/<task-id>/; archiviere das Proposal und schreibe convergence.md, wenn ein Änderungsvorschlag existiert.
6. Führe den Verifizierungsschritt erneut aus und protokolliere die Nachweise.

Verweigerungsbedingungen

Stoppe und melde, anstatt zu konvergieren, wenn eine dieser Bedingungen zutrifft:

• QA nicht bestanden - 03 hat kein gesetztes QA_PASSED, oder REWORK_REQUIRED ist noch aktiv.
• Ungeklärte Nacharbeit - erneute Testnachweise zeigen, dass die Aufgabe sich in der Nacharbeit befindet; warte auf ein neues Urteil.
• Leeres Abweichungsprotokoll - die Tabelle der Implementierungsabweichungen fehlt oder hat keine DEV-Zeile und keine explizite Keine-Zeile.
• Spezifikationsdrift - eine modify/remove-Abweichung verweist auf einen #sec-*-Anker, den die Spezifikation nicht enthält; die Spezifikation und das Abweichungsprotokoll widersprechen sich. Führe check/apply mit --strict in CI aus, um diese Warnung in eine Verweigerung umzuwandeln.
• Archivkollision - tasks/archive/<task-id>/ existiert bereits und --force wurde nicht angegeben.

Strukturelle Abweichungen (neue Module, geänderte Grenzen, neue ADR-Entscheidungen) müssen an spec-generator eskalieren; sie werden niemals stillschweigend konvergiert.

Historie und Zuordnung

Konvergenz überschreibt niemals die Historie: Sie hängt einen datierten, attributierten Abschnitt an, anstatt bestehende Spezifikationstexte zu bearbeiten. Vorhandene Einträge bleiben byte-für-byte stabil, und jeder Eintrag nennt die Quellaufgabe, das QA-Urteil und den ConvergeTool-Akteur. Bearbeite niemals einen alten Konvergenzeintrag, um eine neue Aufgabe passend zu machen; füge einen neuen Eintrag hinzu und protokolliere den Konflikt.

Referenzen

• references/convergence-protocol.md - Zustandsmaschine, wer was schreibt, Archivlayout, Idempotenzmarker, Konfliktregeln und strukturelle Eskalation.
• Rollengrenzen: references/role-boundaries.md — Schreibumfang, Invarianten und das ehrliche Durchsetzungsmodell (gebündelt; keine externen Dateien erforderlich).
• Aufgabenpaketformat und Rollenlebenszyklus: task-decomposition-Skill (wenn installiert).
• Übergabe-Eingabe: dev-Skill; Urteilseingabe: qa-Skill.
• Repository-Regeln: Lese AGENTS.md und ggf. Rollenregeldateien, wenn das übernehmende Projekt sie definiert; sie können zusätzliche Anforderungen hinzufügen, sind aber für dieses Skill nicht erforderlich.

Ehrliche Grenzen

Dieses Skill gewährt keinen Schreibzugriff und kann keine Rollenisolation erzwingen. Wo das Repository CI (z. B. eine git-basierte Rollenprüfung) oder Branch-Schutz hat, ist dies die maßgebliche Ebene. Der gebündelte Helfer ist ein optionaler deterministischer Assistent; die Marker und die schriftlichen Nachweise sind der Vertrag.