serhii-nochevnyi/shipyard

Lieferband-Regeln

Dieses Projekt betreibt ein Pro-Ticket-Lieferband auf Basis von GSD (siehe docs/gsd_multilevel_delivery_pipeline.md). Pläne dienen gleichzeitig als Tickets; diese Regeln halten sie für die deterministische Ebene des Lieferbands maschinenlesbar.

Sprache. Alle Artefakte – Pläne, Frontmatter, Commits, Code, PR- Texte – werden auf Englisch verfasst. Bei direkter Ansprache des Benutzers antworten Sie in der Sprache des Benutzers; Englisch ist für die Artefakte vorgesehen, die Sprache des Benutzers für die Konversation.

Für Planer (Schreiben von PLAN.md)

1. Vollständiges Frontmatter, immer: phase, plan, title, type, wave, depends_on: [], files_modified: [], requirements: []. Ein leeres requirements ist ein BLOCKER – sowohl der GSD-Planprüfer als auch Gate 2 (validate-graph) lehnen es ab; referenzieren Sie ROADMAP-Anforderungs-IDs oder die externe Tracker-ID, wenn der Plan importiert wurde. wave ist eine Dokumentation für den menschlichen Leser: Der Graph ist maßgeblich und der Validator berechnet die tatsächliche Abhängigkeitstiefe neu und warnt, wenn Ihr Wert abweicht. Halten Sie es wahrheitsgetreu und nicht dekorativ.

2. Lieferblock (additiv, ersetzt niemals GSD-Felder):

   delivery:
     ticket: T-<phase>-<plan>
     risk: niedrig|mittel|hoch        # hoch ERFORDERT human_checkpoint: true
     human_checkpoint: false
     repo: besitzer/name             # NUR wenn die Arbeit in einem anderen Repository liegt
   

   repo ist für jedes Ticket Pflicht, das dieses Repository nicht berührt. Lassen Sie es weg, und das Lieferband verfolgt das Ticket gegen das falsche Repository: Sein PR kann grün sein und nebenan gemerged werden, während das Board für immer pending anzeigt, und jeder Abhängige bleibt hinter einem Ticket blockiert, das sich nie bewegt. Pfade in files_modified sind dann relativ zu DIESEM Repository – niemals ../other-repo/x.ts, was kein Worktree erreichen kann (Gate 2 warnt, State-Sync stellt das Ticket zurück). Abhängigkeiten zwischen Repos kaskadieren nicht: Das übergeordnete Projekt muss zuerst MERGEN, also schneiden Sie die Vertragsseite (Typen/Toolnamen) in ein eigenes Ticket, anstatt den Konsumenten auf ein vollständiges Feature warten zu lassen.

3. Erfinden Sie keine Branchnamen. Der kanonische Branch ist ticket/<ID>-<slug>, wobei der Slug der bereinigte Ticket-Titel ist (Kleinbuchstaben, transliteriert, nicht-alphanumerische Zeichen auf einzelne Bindestriche reduziert, ≤40 Zeichen). Lassen Sie delivery.branch weg – der Graph-Validator generiert ihn; ein expliziter Wert wird nach derselben Regel validiert.

4. files_modified ist ein Vertrag, keine Schätzung – listen Sie jeden Pfad auf, den der Plan berührt. Ein LEERES files_modified führt zu einem Fehler in Gate 2 (es macht die Überprüfung "abhängigkeitsungeordnete Tickets kollidieren nie" möglich und ist der Ausführungsbereich des Executors). Abhängigkeitsungeordnete Pläne mit sich überschneidenden Pfaden führen ebenfalls zu einem Fehler in Gate 2; lösen Sie dies mit einer Abhängigkeit oder einem erneuten Zuschnitt, niemals durch das Erweitern von Glob-Mustern (ein nacktes Glob, das alles abdeckt, wird markiert).

5. Nennen Sie, was dies bereits tut, bevor Sie planen, es zu schreiben. Die Kontext-Lektüre jedes Plans muss entweder auf die bestehende Implementierung verweisen, die das Ticket erweitert (pfad:zeile – der Transformer, Sorter, Middleware, Helper, Endpunkt, auf dem es aufbaut), oder die Prüfung protokollieren, die keine gefunden hat: welches Verhalten Sie gesucht haben und die zwei oder drei plausiblen Orte, an denen Sie gesucht haben. Suchen Sie nach VERHALTEN, nicht nach dem Namen, den Sie dem neuen Code geben wollen – ein Duplikat heißt fast immer bereits anders, was genau der Grund ist, warum es die Überprüfung überlebt. "Ich habe keins gesehen" ist nicht dasselbe wie "Ich habe gesucht"; nur die zweite Aussage ist ein Plan, dem ein Leser vertrauen kann. Dies ist das billigste Tor im Lieferband: Ein unbemerktes Duplikat wird vom Integrator eine ganze Phase später gefunden, nachdem andere Tickets bereits darauf aufgebaut haben, und dann ist das Entfernen ein eigenes Ticket. Anders als §4 kann dies nicht maschinell aus dem Frontmatter geprüft werden – Gate 2 sieht es nie, Drift-Check stützt nur die Tickets ab, die es neu bewertet; daher ist das Aufschreiben die Kontrolle.

6. Verifikationsbefehle sind auf das Ticket beschränkt, nicht auf das Projekt. Schreiben Sie die engsten Befehle, die tatsächlich files_modified abdecken – die spezifischen Testdateien oder Filter, die Typüberprüfung und Linting über die berührten Pfade. Ein bloßes npm test / make test / die gesamte e2e-Suite ist hier KEIN Verifikationsbefehl: Es gehört zu CI, das es einmal pro Push auf der dafür gebauten Hardware ausführt. Der Executor führt diese bei JEDEM Versuch aus, und die Fix-Rollen führen sie bei jeder Runde erneut aus – ein nicht eingegrenzter Befehl ist also nicht einmal langsam, sondern die Taktfrequenz des gesamten Lieferbands, multipliziert mit jedem Ticket, das parallel in seinem eigenen Worktree läuft. Zwei Eigenschaften machen einen Befehl nutzbar: Er muss in einem nackten Worktree ohne externe Dienste laufen, und er muss für die Fehler DIESES Tickets fehlschlagen. Ein Befehl, der nicht eingegrenzt werden kann (eine Suite, die eine Live-Datenbank, einen Browser, eine bereitgestellte Umgebung benötigt), ist ein reiner CI-Check – sagen Sie das unter Teststrategie und lassen Sie ihn aus den Verifikationsbefehlen heraus, anstatt dem Executor etwas zu übergeben, das er nicht ausführen kann.

7. depends_on treibt die Kaskade, nicht nur die Reihenfolge. Bei der Epic-gestapelten Auslieferung (Standard) PRt ein Wurzel-Ticket (leeres depends_on) in den Phasen-Epic-Branch; ein abhängiges Ticket kaskadiert – es PRt in den Branch seines primären Elternteils, OHNE auf einen Merge zu warten, sodass der Fluss nie blockiert. Deklarieren Sie Abhängigkeiten präzise: Eine fiktive Abhängigkeit serialisiert den Fluss, eine fehlende übergibt dem Executor eine unvollständige Basis. Der Validator leitet das Epic (epic/<phasen-verz), den primären Elternteil und pr_base ab; mehrere gleichphasige Elternteile (ein Diamant) erzeugen eine Warnung – linearisieren Sie, wenn praktikabel. Halten Sie Abhängigkeiten innerhalb einer Phase. Eine phasenübergreifende Abhängigkeit kann nicht kaskadieren – es gibt keinen gemeinsamen Branch zum Stapeln – daher bleibt das abhängige Ticket blockiert, bis die gesamte Phase des Elternteils auf dem Standard-Branch gelandet ist. Der Validator warnt vor jeder dieser Abhängigkeiten; schneiden Sie stattdessen neu zu.

8. IDs sind kanonisch: T-<2-stellige Phase>-<2-stelliger Plan>. Schreiben Sie T-01-02, niemals T-1-2 – der Validator normalisiert beide, aber Branches, PR-Titel und Jira-Labels werden überall sonst zeichenfolgenbasiert verglichen.

9. Keine nachgestellten #-Kommentare zu einem Wert. Setzen Sie einen Kommentar in eine eigene Zeile. files_modified: [a.ts] # anmerkung faltete früher den Kommentar in den letzten Pfad; der Parser entfernt ihn jetzt korrekt, aber Gate 2 lehnt dennoch jeden Wert ab, der # enthält, da dies fast immer ein Leck ist.

10. Gate 2 ist mechanisch: Es besteht nur, wenn der Graph-Validator mit Exit-Code 0 beendet wird. Jira/GitHub Issues, ROLLOUT.md oder Prosa-Zusammenfassungen sind niemals ein Ersatz für materialisierte PLAN-Dateien.

11. Jira ist eine Projektion, nicht die Quelle der Wahrheit. Standardmäßig (es sei denn, pipeline.jira.enabled: false oder kein Jira MCP ist verbunden) exportiert die Dekomposition den validierten Graphen nach Jira (ein Epic pro Phase, ein Issue pro Ticket) auf Englisch, nach Gate 2 – niemals davor, niemals stattdessen. Das Projekt wird automatisch aufgelöst und gecacht; ein Jira-Fehler darf die Dekomposition nicht blockieren; PLAN-Dateien bleiben kanonisch.

Für Executoren (Implementieren eines Tickets)

1. Bleiben Sie innerhalb von files_modified. Änderungen außerhalb des Rahmens gehören zu einem anderen Ticket – eskalieren Sie, anstatt den Umfang stillschweigend zu erweitern.
2. Lesen Sie die vorhandene Implementierung, bevor Sie eine neue schreiben. Alles, was der Plan unter §5 genannt hat, plus alle reuse_candidates, die Ihnen das Lieferband aus dem Drift-Check übergeben hat: Lesen Sie zuerst jede davon und erweitern Sie sie, anstatt eine parallele Ebene daneben zu legen. Wenn ein Kandidat wirklich nicht passt, sagen Sie warum in Ihrem Nachweis – das ist ein legitimes Ergebnis; ihn stillschweigend zu ignorieren ist es nicht. Wiederverwendung berechtigt niemals dazu, files_modified zu verlassen: Wenn das Daraufaufbauen Sie außerhalb des Rahmens führen würde, ist das eine Eskalation außerhalb des Rahmens (§1), keine breitere Diff.
3. Atomare Commits mit dem Ticket-ID-Präfix: feat(T-01-02): ….
4. Führen Sie die Verifikationsbefehle des Plans lokal auf Grün aus, bevor Sie fertig melden; beanspruchen Sie niemals Verifikation ohne Befehlsausgabe. Führen Sie diese Befehle aus – seien Sie nicht "gründlich", indem Sie sie auf die gesamte Suite ausweiten (§6): CI ist für den vollständigen Lauf verantwortlich, und eine Suite, die Sie hier gestartet haben, blockiert Ihren eigenen Worktree und jeden anderen Executor, der die Maschine teilt. Wenn die Befehle des Plans fehlerhaft sind oder die Änderung offensichtlich nicht abdecken, korrigieren oder verengen Sie sie im Plan und sagen Sie dies in Ihrem Nachweis; das stillschweigende Ersetzen durch npm test ist keine Korrektur.
5. Worktree und Branch stammen vom Lieferband (tickets.json) – erstellen Sie keine Branches oder Worktrees ad hoc. Ihre PR-Basis wird ebenfalls vom Lieferband aufgelöst (delivery-state.json → base: der Epic-Branch für ein Wurzel-Ticket, der Eltern-Branch für ein abhängiges) – öffnen Sie unter Epic-Stacked niemals einen PR direkt in main/master.
6. Halten Sie beim Commit an. Führen Sie kein push aus, öffnen Sie keinen Pull Request, berühren Sie keine Reviewer. Der Orchestrator überprüft den Worktree mechanisch (git log <base>..HEAD), bevor er etwas veröffentlicht – diese Prüfung fängt den Fall "der Agent hat Erfolg gemeldet und nichts geändert" ab, und sie funktioniert nur, wenn die Veröffentlichung nicht in den Händen des zu prüfenden Agenten liegt. Geben Sie stattdessen Ihren Verifikationsnachweis und einen PR-Text zurück.