Spec-Bereitschaftsvertrag

Eine Spec sagt, wie sich eine Domäne verhält; ein Work Item sagt, welchen Ausschnitt ein Agent als Nächstes baut. Diese Seite ist die Referenz dafür, wie beide verbunden sind, wann ein Item bereit ist, welche Tracker-Labels das ausdrücken und wer sie schreibt. Die Spec-Dateien selbst stehen im Delivery-Spec-Format.

Stand

Vertrag, Gates und Bereitschaftsregel sind in der Referenzimplementierung bw-fm27 definiert (agents/work_item.schema.json, tools/qa/check_work_item_depth.py, tools/qa/check_requirement_traceability.py, tools/workitems/sync.py); die entscheidungsbewusste Bereitschaftsregel und das Label spec-ready sind dort seit dem 22.09.2026 gemergt (bw-fm27 #230), und der erforderliche Status gate-class, der gegatete Änderungen für ihren Freigeber zurückhält, am selben Tag (bw-fm27 #238) — siehe Gate-Klassen. SupaCloud berechnet noch keine Bereitschaft und liest oder schreibt noch keine Tracker-Labels; das ist als SC-2 und SC-20 in Issue #1448 geplant, dessen Paket die Briefs der Module als blueprints/SC-2.md und blueprints/SC-20.md enthält.

Work-Item-Felder, die ein Item an eine Spec binden

Ein Work Item ist ein YAML-Vertrag (agents/work_items/WI-*.yaml in der Referenzimplementierung). Drei Felder binden es an Specs:

Feld	Form	Bedeutung
spec_refs	Liste von Klausel-IDs (<DOM>-R-###), eindeutig, mindestens eine	die Klauseln, die dieses Item umsetzt
decision_refs	Liste von Entscheidungs-IDs (DEC-<DOM>-###), eindeutig, mindestens eine, wenn vorhanden	die Designentscheidungen, von denen das Item abhängt; es bleibt blockiert, bis jede freigegeben ist
acceptance[]	Objekte mit text (mindestens 8 Zeichen) und verifies (Klausel-IDs, eindeutig, mindestens eine)	jeder Eintrag nennt die Klauseln, die er nachweist

# Ausschnitt eines Work Items; ein vollständiges Item hat mindestens drei Abnahmeeinträge
spec_refs: [ECON-R-004, ECON-R-005]
decision_refs: [DEC-ECON-005]
acceptance:
  - text: A season budget above the board's ceiling is rejected with the ceiling named
    verifies: [ECON-R-004]

Zwei weitere Felder behalten ihre Bedeutung:

• complexity (T0 bis T3) wählt die Review-Tiefe auf der Merge-Leiter des Projekts: T0 merged, sobald jedes Gate grün ist; T1 fügt einen unabhängigen Review-Agenten hinzu; T2 braucht zwei unabhängige Reviews von verschiedenen Modellanbietern oder ein Human Gate; T3 wird von einem Menschen geführt.
• human_gate: true markiert ein Item, das selbst eine Entscheidung ist, die vor Beginn der Arbeit fällt. Ein Item, das eine freigegebene Spec umsetzt, trägt stattdessen decision_refs statt eines eigenen Gates.

Abnahmeeinträge als einfache Strings sind die Form vor den Specs. Sie bleiben für Items ohne spec_refs gültig, damit ein Backlog Domäne für Domäne migrieren kann.

Bindungsregeln und die Gates, die sie durchsetzen

Regel	Gate
Mit spec_refs ist jeder Abnahmeeintrag ein Objekt, dessen verifies Klauseln aus den eigenen spec_refs des Items nennt	Depth-Gate
Jede Klausel in spec_refs existiert in einer Spec	Depth-Gate
Jede Klausel in spec_refs wird von mindestens einem Abnahmeeintrag nachgewiesen	Traceability-Gate — eine beanspruchte, aber durch nichts belegte Klausel schlägt fehl
decision_refs gehören zu einer Domäne, auf die die spec_refs des Items verweisen, und existieren in deren decisions.yaml	Depth-Gate
decision_refs oder verifies ohne spec_refs werden abgelehnt	Depth-Gate
Höchstens sechs Klauseln in spec_refs und höchstens acht Abnahmeeinträge — ein größeres Item wird geteilt	Depth-Gate
Die Zahl der Items ohne spec_refs darf nur fallen	Depth-Gate, Baseline unmigrated_work_items, die nur schrumpft

Jedes Item, ob an eine Spec gebunden oder nicht, erfüllt außerdem die Tiefenregeln eines Vertrags: ein Ziel von mindestens 120 Zeichen, das sagt, was sich ändert und warum, mindestens drei Abnahmekriterien von mindestens acht Wörtern, mindestens ein Kriterium, das einen Fehlerfall nennt, mindestens zwei Evidence-Einträge, mindestens ein Kommando, eine Anforderung, die im Katalog auflöst, und Notizen. Die Zahl der Items, die das verfehlen, ist eine zweite Baseline, die nur schrumpft (shallow_work_items). Beide Baselines liegen in einer Datei mit eigener Policy-Zeile: Jedes migrierte Item senkt eine Zahl im selben Pull Request, und eine anzuheben braucht eine benannte menschliche Entscheidung.

Woher die Anforderungs-IDs kommen

Tiefenprüfung und Traceability-Prüfung kennen keine eigene ID-Form. Beide lösen die Anforderungsverweise eines Work Items und die satisfies-Verweise einer Spec über das Projektprofil (specs/project.yaml) auf — dieselbe eine Definition, die Spec-Validator und Spec-Gate lesen und die die Katalogdatei, die Listen mit Anforderungen und Abnahmekriterien sowie die ID-Muster nennt. Ein Repository, dessen Profil fehlt oder fehlerhaft ist, lässt diese Prüfungen laut und mit Namen fehlschlagen; nichts fällt auf eingebaute ID-Formen zurück. Siehe Das Projektprofil.

Die Traceability-Prüfung geht bei Items mit spec_refs eine Ebene tiefer: Jede Klausel, die ein Item beansprucht, muss von mindestens einem seiner eigenen Acceptance-Einträge belegt werden. Eine Klausel, die geführt aber von nichts belegt wird, ist ein Anspruch ohne Beweis und schlägt fehl.

Zwei Arten von Baseline

Nicht jede Baseline in dieser Kette arbeitet gleich, und der Unterschied zählt, sobald ein Pull Request neuen Umfang übernimmt:

Baseline	Regel
Spec-Abdeckung (spec-coverage-baseline.json: Katalog-IDs, die keine Domäne besitzt)	muss der aktuellen Anzahl gleichen. Eine Anzahl darüber ist ein Rückschritt; eine Baseline darüber ist Spielraum, der den nächsten Rückschritt durchlassen würde. Ein Pull Request, der einer Domäne neue Katalog-IDs gibt, schreibt sie in derselben Änderung mit --write-baseline neu.
Traceability (uncovered_must_p1, uncovered_acceptance_criteria) und Work-Item-Tiefe (shallow_work_items, unmigrated_work_items)	nur schrumpfend, ohne die Gleichheitsregel: Die Zahl darf frei fallen, und nur eine anzuheben braucht eine benannte menschliche Entscheidung.

Gate-Klassen und dieser Vertrag

Bereitschaft sagt, dass ein Item beginnen darf; Gate-Klassen sagen, welche fertige Änderung noch auf einen Menschen wartet. Das sind getrennte Mechanismen, und ein Projekt braucht beide. In der Referenzimplementierung enthält die Klassenkarte (tools/qa/gate_classes.yaml) für jede der beiden Spec-Dateien, die dieser Vertrag berührt, eine eigene Regelart: decision_answers auf specs/*/decisions.yaml und parameter_ranges auf specs/*/parameters.yaml, beide Klasse G1. Eine Entscheidung zu beantworten oder den freigegebenen Bereich eines Parameters zu verschieben, wird also für den Owner zurückgehalten — während einen Standardwert innerhalb seines Bereichs zu tunen frei bleibt. Der Status heißt gate-class und ist auf dem main der Referenzimplementierung neben ihren drei core-ci-Kontexten ein erforderlicher Check. Die vollständige Klassenliste steht in Wie SupaCloud sich in ein spec-getriebenes Projekt einfügt.

uv run python tools/fmctl.py validate work-items    # Schema-, Tiefen- und Verweisregeln
uv run python tools/fmctl.py validate requirements  # Traceability, einschließlich unbelegter Klauseln

Bereitschaft

Ein Item ist bereit (ready), wenn alles davon gilt:

1. jedes Item in seinen dependencies hat ein geschlossenes Issue;
2. jede Entscheidung in seinen decision_refs hat status: approved;
3. jede Spec, auf die seine spec_refs zeigen, hat den Status design-approved, implementing oder verified.

Ein Item ohne spec_refs und ohne decision_refs ist allein durch seine Abhängigkeiten bereit. Ein Item ist spec-ready, wenn es bereit ist und spec_refs hat: Es setzt freigegebene Klauseln unter freigegebenen Entscheidungen um, ein Dispatcher darf es also einem Agenten geben, ohne jemanden zu fragen.

Bereitschaft schlägt geschlossen fehl: Eine unbekannte Entscheidung, eine unlesbare Spec oder die Template-Domäne machen ein Item nie bereit. Ein geschlossenes Issue trägt gar kein Bereitschaftslabel.

Tracker-Labels

Die Bereitschaftsregel wird im Tracker als Labels veröffentlicht, damit jedes Werkzeug — ein Dispatcher, ein Board, ein Mensch — dieselbe Tatsache liest.

Label	Gesetzt, wenn	Entfernt, wenn
ready	das Item bereit ist	es das nicht mehr ist oder das Issue geschlossen wird
blocked	das Item offen und nicht bereit ist	es bereit wird oder das Issue geschlossen wird
spec-ready	das Item bereit ist und spec_refs hat	eine Abhängigkeit wieder geöffnet wird, eine referenzierte Entscheidung nicht mehr freigegeben ist, die Spec auf draft zurückgeht oder das Issue geschlossen wird
human-gate	der Vertrag human_gate: true hat	der Vertrag es nicht mehr hat — das Label spiegelt den Vertrag in beide Richtungen

Der Schreiber setzt außerdem die Marker-Labels auf jedes Issue — work-item, das Komplexitätslabel T0 bis T3 und skill/<owner_skill> —, legt jedes Label an, auf das er sich stützt und das noch nicht existiert, und ordnet in der Referenzimplementierung jedem Issue einen Meilenstein pro Lieferwelle zu. Er legt ein Issue für ein Work Item an, das noch keines hat, aber er schließt oder öffnet nie ein Issue und entfernt nie ein Label außerhalb der vier aus der Tabelle. Eine Konsistenzprüfung meldet jedes Label, das den Verträgen und Specs widerspricht, und endet mit einem Fehlercode:

uv run python tools/fmctl.py workitems sync -- --check     # nur lesend; Fehlercode bei Drift
uv run python tools/fmctl.py workitems sync -- --dry-run   # zeigt die Schreibvorgänge, die es ausführen würde
uv run python tools/fmctl.py workitems sync                # fehlende Issues anlegen, neu labeln

Ein Tracker-Schreiber

Genau ein System schreibt die Bereitschaft in den Tracker, und in einem spec-getriebenen Projekt auf SupaCloud ist dieses System SupaCloud:

• SupaCloud leitet die Bereitschaft wie oben aus den Work-Item-Verträgen und Specs des Repositorys ab und pflegt ready, blocked, spec-ready und human-gate über die bestehende Forge-Verbindung des Projekts — das Credential, mit dem das Projekt bereits klont, Pull Requests öffnet und mergt.
• Die CI des Repositorys hält keine Tracker-Credentials. Ihre Gates lesen das Repository — und ein Gate, das einen Pull Request beurteilt, liest diesen mit dem eigenen Job-Token der Forge —, aber keines schreibt in den Tracker.
• Ein Projekt braucht dafür keinen Bot-Account und kein CI-Secret.

Zwei Schreiber widersprechen sich, sobald einer hinterherhinkt, und ein Bot-Account pro Projekt mit CI-Secret ist Einrichtung, die jedes neue Projekt wiederholen müsste. Der erste Entwurf der Referenzimplementierung ließ die Synchronisation als geplanten CI-Job unter einem eigenen Bot-Account laufen; er wurde am 22.09.2026 genau aus diesen Gründen verworfen.

Bis SupaCloud die Labels schreibt

tools/workitems/sync.py aus der Referenzimplementierung berechnet dieselbe Regel und schreibt dieselben Labels. Starte es aus einer Owner-Sitzung mit dem eigenen Forge-Token des Owners in FORGEJO_TOKEN (FORGEJO_API_BASE und FORGEJO_REPO wählen Forge und Repository). Ohne Token bricht es laut ab, statt still zu bestehen. Wenn SupaCloud die Regel übernimmt, bleibt dieses Skript ihre ausführbare Referenz.

Was ein Dispatcher mit den Labels macht (geplant)

SC-2 macht die Backlog-Aufnahme von SupaCloud label-bewusst. Die empfohlene Regel für ein spec-getriebenes Projekt dispatcht genau die offenen Issues, die work-item, ready und spec-ready tragen und keines mit blocked; ein Item, das vor dem Dispatch ein Pflichtlabel verliert, geht in einen nicht dispatchbaren Zustand zurück, und ein geschlossenes Issue bricht sein wartendes Item ab. T3-Items werden nie dispatcht. Das Komplexitätslabel wählt außerdem die Fähigkeitsstufe (Tier), auf der die Arbeit läuft (SC-3). Nichts davon gibt es heute in SupaCloud — siehe Wie SupaCloud sich in ein spec-getriebenes Projekt einfügt.