--- contract: digiestate-work-items schema_version: 2 status: angenommen stand: 2026-10-18 --- # Gemeinsamer Work-Item-Datenvertrag Dieser Vertrag ist die einzige Definition der Arbeitsdaten für das [Methodenprofil](../methods/SAFE-PROFIL.md). Dateien und eine spätere Cockpit-API verwenden dieselben Identitäten, Inhalte und Fachregeln. Er spezifiziert den Zugriff; er implementiert weder einen Importer noch atomare Dateischreibvorgänge. ## Projektkonfiguration und führende Quelle Version 2 trennt Portfoliozuordnung, Projektbeteiligung und technische Quelle. Bei ausdrücklich gewähltem Vertrag 1 stattdessen [WORK-ITEMS-V1](WORK-ITEMS-V1.md) und dessen Vorlagen unter docs/templates/v1 verwenden. Ein Legacy-Register mit artifact: work-item-register und schema_version: 2 ist ein anderer Vertrag. Die Auswahl in PROJECT.md und die Struktur bestimmen den Leser, niemals die Zahl schema_version allein. Im Frontmatter der konkreten PROJECT.md steht: ```yaml method_profile: digiestate-safe/2 contract_version: 2 project_id: "" work_management: portfolio_id: "" source_context_id: "" source: files location: docs/work-items ``` portfolio_id ist hier die Voreinstellung für neue Datensätze, keine implizite Freigabe. Ein neuer Projektstart wählt nicht automatisch ein eigenes Portfolio; bis zur fachlichen Auswahl bleibt dieser Wert null und es entstehen keine vollständigen Work-Items. project_id bezeichnet nur das Projekt. Ein Portfolioquellenkontext darf ohne project_id bestehen. source_context_id darf anfänglich denselben UUID-Wert wie ein Projekt verwenden; die Felder sind semantisch unabhängig, eine Beteiligung ändert die Quellroute nicht. Bei source: cockpit ersetzt endpoint die Dateiangabe. source_context_id und Datensatz-IDs bleiben stabil. Endpoint ist eine Basisadresse, kein Secret. Ohne implementierten und autorisierten API-Zugriff bleibt die Quelle files. Ein vertrauenswürdiger Kontext führt bekannte Portfolios (id/name), Projekte (id/name) und Quellkonfigurationen (source_context_id, contract_version, source und location/endpoint) auf. Die lokale PROJECT-Konfiguration ist ein solcher Eintrag; weitere werden ausdrücklich referenziert, nicht durch einen Scan des Dateisystems gesucht. Die Konfiguration eines Quellenkontexts ist dessen einzige schreibende Quellzuordnung. Vor Änderung erst auflösen und Revision prüfen; unbekannte Quellen/Portfolio-/Projekt-IDs nicht erfinden. Work-Item-Texte und Exportdaten verleihen weder Quellzugriff noch Rechte. Die synthetische contexts.yaml bei den Beispielen zeigt diese Metadaten, keine neue globale Registry-Anwendung oder hypothetische API. Andere Projekte verweisen auf IDs und die bekannte Quellkonfiguration statt eine schreibbare Kopie anzulegen. Exporte tragen Herkunft, Snapshotrevision und read_only: true im Manifest und sind keine zweite Quelle. ## Darstellung Im Dateimodus: ein Work-Item je `docs/work-items/.md`, UTF-8, YAML-Frontmatter und ergänzender Markdown-Körper. Frühe Arbeit erhält bereits eine Datei; Bereitschaft bestimmt den nächsten Schritt, nicht die Existenz der Datei. Technische Defaults werden automatisch oder nach festen Regeln ergänzt. Vorlagen sind unvollständige Eingabehilfen, keine gültigen Datensätze. YAML bleibt JSON-kompatibel: nur Objekte, Listen, Strings, endliche Zahlen, Booleans und null. Keine Aliase, Anker, benutzerdefinierten Tags, doppelten Schlüssel oder impliziten Datumstypen. Zeitstempel als zitierte UTC-Strings in RFC-3339-Form mit `Z`. Geld als Betrag in kleinster Einheit plus Währungscode, keine binären Gleitkomma-Geldbeträge. Der Körper wird als `body_markdown` übertragen; fachlich wirksame Kriterien und Entscheidungen stehen strukturiert. Anzeigetitel im Körper dürfen dem Feld `title` nicht widersprechen. `BACKLOG.md` ist ein abgeleiteter Index mit Links, keine zweite Datentabelle. `PLAN.md` ist eine Auswahl geordneter IDs mit Planungskommentar. Work-Item-Status, Blockierung und Freigabe werden darin nicht unabhängig gespeichert. Im API-Modus zeigen beide auf Abfragen/IDs der Quelle. Zusätzliche Architektur-, Fach- und Berichtsdokumente bleiben verknüpfte Artefakte, keine Datensatzkopien. ## Gemeinsame Felder | Feld | Typ und Bedeutung | | --- | --- | | `schema_version` | Integer, für diesen Vertrag 2 | | `id` | Unveränderliche UUIDv7; über alle Projekte eindeutig | | `key` | Stabile Kennung, z. B. TASK-00001; innerhalb des Quellenkontexts eindeutig; 1–100 Zeichen nach `^[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*$` | | `type` | idea, epic, feature, story oder task; Typ bleibt unverändert | | `title` | Nichtleerer verständlicher Titel | | `portfolio_id` | UUIDv7 des fachlichen Portfolios; auch ohne Projektbeteiligung erforderlich | | `source_context_id` | UUIDv7 des technischen Quellenkontexts, unabhängig von Portfolio und Beteiligung | | `revision` | Positive Ganzzahl; pro erfolgreicher Änderung um genau eins erhöhen | | `workflow_id`, `state` | Zusammenpassende Werte aus workflows.yaml | | `owner_id` | Referenz auf fachliche Verantwortung; anfänglich null zulässig | | `assignee_id` | Referenz auf aktuelle Ausführung; anfänglich null zulässig | | `parent_id` | UUID eines übergeordneten Lieferobjekts oder null | | `origin_ids` | Liste der Ursprungs-Work-Items, etwa Ideen | | `project_ids` | Eindeutige UUIDv7-Liste beteiligter Projekte, auch leer; keine Hierarchie, Abhängigkeit, Quellwahl oder Berechtigung | | `depends_on_ids` | Voraussetzungen; nicht automatisch gleichbedeutend mit aktueller Blockierung | | `blockers` | Liste aus `reason` und optional `work_item_id`; kein zusätzliches blocked-Boolean | | `content` | Typabhängiger Inhalt nach der folgenden Tabelle | | `evidence`, `decisions`, `history` | Nachweise, Entscheidungen und Verlauf nach den folgenden Regeln | | `created_at`, `updated_at` | UTC-Zeitstempel; aktualisiert nicht vor erzeugt | | `extensions` | Optionales Objekt mit benannten Erweiterungsräumen, sonst leer | Alle Felder ausser `extensions` sind im vollständigen Datensatz vorhanden. Leere Listen/Objekte und null erhalten unbekannte Inhalte ehrlich. Ein früher Eintrag benötigt keine erfundenen Kriterien oder Entscheidungen. Es gibt kein Pflichtfeld `maturity` und kein frei gepflegtes `ready`-Boolean. IDs referenzieren Datensätze, niemals deren aktuelle Dateipfade. Elternbezüge sind azyklisch: Epic/Idee haben keine Liefereltern; Feature kann einem Epic, Story einem Feature/Epic, Task einer Story/Feature/Epic zugeordnet sein. Null ist bei eigenständiger Arbeit erlaubt. Herkunft und sonstige Referenzen dürfen wechselseitig sein. Zirkuläre Voraussetzungen sind als Planungsfehler sichtbar zu klären; sie rechtfertigen keine künstliche Erfüllung. Portfolio-Epics haben keine Liefereltern. Liefereltern und Kinder gehören zum selben Portfolio, dürfen aber unterschiedliche Projektbeteiligungen oder Quellenkontexte haben. Eine andere Portfoliozuordnung erfordert eine ausdrückliche Übertragung mit Prüfung betroffener Elternbezüge, Entscheidungen und Rechte. Beteiligungen werden nicht automatisch von Eltern geerbt. project_ids, origin_ids und depends_on_ids enthalten keine doppelten IDs; direkte eigene Abhängigkeit ist unzulässig. Voraussetzungen können portfolioübergreifend sein, wenn Referenzen und Leserechte ausdrücklich aufgelöst sind. Eine Beteiligung fügt niemals automatisch eine Voraussetzung oder ein aktuelles Blocker-Objekt hinzu. Die Kennung bleibt bei Änderung von Portfolio oder Beteiligung stabil. Gleiche Kennungen unterschiedlicher Quellenkontexte sind zulässig; Auflösung verwendet UUID oder source_context_id plus Kennung. Dateimodus vergibt Kennungen im serialisierten Schreibweg, die spätere API atomar. Ein Quellenwechsel benötigt explizite Übertragung der Quellzuständigkeit; alte Herkunft bleibt erhalten. ## Typabhängiger Inhalt und Bereitschaft | Typ | Strukturierte Felder in `content` | | --- | --- | | idea | `impulse`, `open_questions`, `next_step`, `closure` | | epic | `problem`, `benefit_hypothesis`, `benefit_metrics`, `mvp`, `investment`, `risks`, `hypothesis_result`, `next_step`, `closure` | | feature | `capability`, `expected_benefit`, `acceptance_criteria`, `verification_plan`, `risks`, `next_step`, `closure` | | story | `outcome`, `examples`, `acceptance_criteria`, `verification_plan`, `risks`, `next_step`, `closure` | | task | `goal`, `non_goals`, `acceptance_criteria`, `verification_plan`, `risks`, `next_step`, `closure` | Felder können zunächst fehlen; vor einem Übergang gelten die Bereitschaftsregeln des Profils. Unbekannte top-level Felder sind ein zu klärender Vertragsfehler. Neue fachliche Felder werden versioniert, nicht still eingeführt oder verworfen. Normative Inhaltstypen: problem, benefit_hypothesis, capability, expected_benefit, outcome, goal, impulse, verification_plan sind String oder null. non_goals, open_questions, risks und examples sind Listen von Strings. next_step ist null oder ein Objekt mit `description` (String) und optional `review_on` (zitierter ISO-Datumstring). Eine Pause benötigt beide Werte. content darf die für den jeweiligen Typ aufgeführten Felder enthalten, keine beliebigen Zusatzfelder. benefit_metrics und acceptance_criteria sind Listen der unten definierten Objekte. mvp und investment sind anfangs null oder die folgenden Objekte: - mvp: scope und learning_question als String/null; limits als Objekt aus effort_hours (nichtnegative endliche Zahl/null), external_cost_minor (nichtnegative Ganzzahl/null) und currency (Währungscode). Vor Pilotstart die tatsächlich geltenden Grenzen konkret festlegen; null bedeutet unbekannt, nicht unbegrenzt oder freigegeben. Ein ausdrücklich ausgeschlossener externer Aufwand wird als 0 erfasst. - investment: alternatives als Liste von Strings, estimate als String/null. Die grobe Schätzung dokumentiert Umfang, Bandbreite und Unsicherheit. Messgrössen: id, description, unit, window und measurement_method als Strings; baseline, target und observed als endliche Zahl oder null, evidence_ids als Stringliste. Eine rein qualitative Hypothese braucht eine ausdrücklich neue Messdefinition im Profil statt eines stillen Wechsels zu einem anderen Datentyp. Kriterien: id/text als Strings, verification als aufgeführter Code, evidence_ids als Stringliste. IDs von Kriterien, Messgrössen, Nachweisen und Entscheidungen sind innerhalb ihres Work-Items eindeutig und werden nicht wiederverwendet. Akzeptanzkriterium: `id`, `text`, `verification` (offen/bestanden/nicht_bestanden), `evidence_ids`. Ein Häkchen ersetzt keinen Nachweis. Vor erfolgreichem Abschluss müssen alle aktuellen Kriterien bestanden und ihre Belege verfügbar sein. Epic-Messgrösse: `id`, `description`, `baseline`, `target`, `unit`, `window`, `measurement_method`, `observed`, `evidence_ids`. Baseline/Beobachtung dürfen null sein; fehlende Daten stützen keine Hypothese. `mvp`: `scope`, `learning_question`, `limits`; `investment`: dokumentierte Alternativen, grobe Aufwands-/Kostenannahmen und Unsicherheit. Vor Start sind die benötigten Angaben und gültige Mittel-/Umfangsfreigabe erforderlich. Hypothesenstatus ist offen/gestuetzt/widerlegt/unklar, unabhängig von der Portfoliostufe. `closure` ist bei Abschluss ein Objekt mit `reason`, `remaining_work_ids` und `responsibility`; davor null. Portfolio-Gründe: uebergeben, verworfen, hypothese_widerlegt, ersetzt. Lieferung mit `beendet`: verworfen/ersetzt; Idee mit `beendet`: ueberfuehrt/verworfen. Erfolgreiche Lieferung: angenommen. Pausen erhalten Grund und Wiedervorlage in `content.next_step`; die aktive WIP-Verpflichtung endet dadurch nicht automatisch. ## Nachweise, Entscheidungen und Verlauf Nachweis: `id`, `kind`, `ref`, `recorded_at`. Art benennt etwa Test, Messung, Beobachtung oder Dokument. Referenz auf einen bestimmten unveränderlichen Stand, etwa Commit plus Pfad oder versionierten geschützten Beleg. Korrigierte Belege bekommen neue IDs. Keine Geheimnisse oder echten Kontaktlisten in Git. Entscheidung: `id`, `kind`, `result`, `by`, `at`, `reason`, `evidence_ids`, `subject_revision`, `scope_snapshot`, `recorded_revision`, `supersedes_id`, `revokes_id`. Die beiden letzten Felder sind null oder eine vorherige Entscheidungs-ID im selben Datensatz. Art etwa pilotfreigabe, abnahme, hypothesenbewertung oder portfolioabschluss. `scope_snapshot` hält die konkret geprüften Feldpfade und Werte fest, z. B. aktuelle Kriterien und Beleg-IDs oder MVP-Umfang und Mittelgrenze. Revision identifiziert den geprüften Stand; Snapshot bindet die Gültigkeit an dessen relevanten Umfang. Vor Verwendung muss dieser Umfang zum aktuellen Inhalt passen. Eine Titelkorrektur muss eine Kriterienabnahme nicht entwerten, geänderte Kriterien tun es. Verbindlicher Mindestumfang des Snapshots (Feldpfad → vollständiger Wert): | Art | Mindestens gebundene Inhalte | | --- | --- | | pilotfreigabe | content.benefit_hypothesis, content.benefit_metrics (Messdefinition), content.mvp, content.investment | | abnahme | content.acceptance_criteria, content.verification_plan und typabhängig content.goal/content.outcome/content.capability | | hypothesenbewertung | content.benefit_hypothesis, content.benefit_metrics, content.hypothesis_result | | portfolioabschluss | content.closure, content.hypothesis_result | Bei pilotfreigabe wird content.benefit_metrics für Snapshot und Vergleich auf id, description, baseline, target, unit, window und measurement_method je Messgrösse projiziert. observed und evidence_ids werden dabei ausgeschlossen. Das ist die einzige definierte Projektion in Vertragsversion 2; andere gebundene Felder werden vollständig verglichen. So können Messungen ergänzt werden, ohne eine unveränderte Pilotfreigabe zu entwerten. Geänderte Messdefinition, Ziel, MVP oder Mittelgrenze benötigen dagegen eine neue Gültigkeitsprüfung. Leere/unvollständige Snapshots sind ungültig. Alle decision.evidence_ids müssen vorhandene unveränderliche Nachweise referenzieren; für Abnahme müssen sie zusätzlich sämtliche aktuellen Kriteriumsbelege umfassen. result verwendet je Art freigegeben/abgelehnt, angenommen/abgelehnt, gestuetzt/widerlegt/unklar oder abgeschlossen/abgelehnt. IDs/by/reason sind nichtleere Strings, at ein UTC-String, subject_revision und recorded_revision positive Ganzzahlen; geprüft wird ein vorheriger Stand, aufgezeichnet wird in der neuen Revision. Entscheidungen werden nicht überschrieben. Eintrag mit kind=widerruf und result=widerrufen benötigt revokes_id und dieselbe fachliche Zuständigkeit; sein Snapshot bindet die ID der widerrufenen Entscheidung. Ersatz benötigt supersedes_id. Pro Entscheidungsart und Work-Item ist die zuletzt aufgezeichnete Entscheidung massgebend (recorded_revision, bei Gleichstand Listenreihenfolge). Eine abgelehnte, widerrufene oder am Umfang ungültige letzte Entscheidung lässt keine alte Zustimmung wieder aufleben. Widerrufene/ersetzte IDs bleiben unwirksam. Eine erneute Freigabe wird als neue zuständige Entscheidung dokumentiert. Nachweis- und Entscheidungsreferenzen sind lokale IDs; Work-Item-/Projektbezüge verwenden UUIDs. closure.reason und responsibility sind nichtleere Strings, remaining_work_ids ist eine UUID-Liste. history.actor_id/action/reason sind nichtleere Strings; revision positiv, from_state null nur bei der Erfassung, sonst gültiger Zustand. Dieselben Typen gelten im Datei- und API-Modus. Verlaufseintrag: `revision`, `at`, `actor_id`, `action`, `reason`, `from_state`, `to_state`. Revision 1 ist die Erfassung mit `from_state: null`; danach fortlaufend und lückenlos. Inhaltsänderungen ohne Statuswechsel haben denselben Vor-/Nachstatus. Aktueller Status und Zeit stimmen mit dem letzten Eintrag überein. Übergänge folgen workflows.yaml und fachlichen Voraussetzungen. Prüfungsrückgabe bleibt im begonnenen Durchlauf; Wiedereröffnung startet einen neuen. Terminalgrund und Verantwortungsübergabe benötigen eine passende Entscheidung. Eine aufgezeichnete Identität ist keine Berechtigung. Personen/Agenten werden über einen vertrauenswürdigen Projektkontext aufgelöst; Dateieinträge sind nachvollziehbare Behauptungen. Die API ermittelt handelnde Identität und Rechte serverseitig. KI-Vorschläge werden nicht als menschliche Zustimmung erfasst. Abnahme durch KI ist nur bei ausdrücklich delegierter Befugnis zulässig. ## Lesen, Schreiben und Konflikte Fachliche Operationen sind Quelle auflösen, lesen/suchen, erfassen, ändern, auswählen, übernehmen, Übergang beantragen und Entscheidung aufzeichnen. Ein Skill verwendet den vereinbarten Zugriff und keine hypothetische API. Jeder Schreibversuch nennt `expected_revision`; die Quellimplementierung prüft sie vor atomarem Speichern von Änderung, Historie und neuer Revision. Ein veralteter Versuch endet als Konflikt ohne Datenverlust. Fehlgeschlagene Wiederholungen erzeugen keine zweite Übernahme oder Freigabe. Die API muss für nicht idempotente Aktionen einen stabilen Operationsschlüssel akzeptieren. Bis ein solcher Dateizugriff existiert, ist genau ein koordinierter Schreiber je Quellenbestand zulässig: Stand erneut lesen, Konflikte klären, vollständige Datei austauschen, prüfen. Git allein koordiniert keine parallelen Worktrees. Behaupte keine technisch atomare Aufgabenübernahme im Dateimodus. Die spätere API muss Erwartungsrevision, Rechte, WIP und Übernahme in der Transaktion prüfen. ## Quellenwechsel und Altbestand 1. Betroffene Portfolios, Projekte und Quellenkontexte bestimmen, Schreibzugriffe anhalten. 2. Snapshot samt Prüfsumme und Herkunft sichern; alte Quelle bleibt führend. 3. Identitäten/Inhalte in gesperrtes Ziel importieren, danach Referenzen auflösen. Keine topologische Reihenfolge aller Beziehungen voraussetzen. 4. Vollständigkeit, IDs, Beziehungen, Körpertexte, Nachweise, Entscheidungen, Erweiterungsfelder und Verlauf prüfen. Externe Bezüge ausdrücklich deklarieren; interne müssen auflösbar sein. Wiederholung erzeugt keine Dubletten und überschreibt keine neuere Revision. Vergleichbare gleiche Revisionen müssen auch denselben Inhalt besitzen; sonst Konflikt. 5. Ziel erst nach Gesamtprüfung aktivieren und Quellkonfiguration umschalten; alte Kopien schreibgeschützt erklären. Erst danach Schreiben wieder zulassen. Nach Aktivierung nicht auf einen veralteten Snapshot zurückschalten. Alte Register mit artifact: work-item-register und schema_version: 2 sind ein anderes Format als Work-Item-Vertrag 2. Historische Kennungen, Taskpfade und Git-Trailer unverändert erhalten. Die ausdrückliche Migration legt ein ID-/Pfad-Mapping an und bewahrt alte Felder, z. B. `extensions.legacy.maturity`. Keine Bereitschaft, Freigabe oder Messhistorie erfinden; unbekannte frühere Zeitpunkte bleiben unbekannt. Vorhandene Legacy-Regeln gelten bis zur Übernahme weiter. ## Ausdrückliche Übernahme von Vertrag 1 Version 1 bleibt unter WORK-ITEMS-V1.md mit ihren Beispielen und Vorlagen verfügbar. Eine Migration ist eine beauftragte Datentransformation, kein Nebeneffekt eines Skill-Updates: 1. Quelldaten unverändert sichern und Prüfsummen bewahren; Schema-/Profilwahl lesen. 2. Portfolio ausdrücklich wählen. Es wird nicht aus home_project_id abgeleitet. 3. Alte home_project_id über eine bestätigte Quellzuordnung auf source_context_id abbilden. Das ist technische Herkunft, keine fachliche Epic-Heimat. 4. project_ids nach bestätigter Beteiligung füllen; home_project_id und related_project_ids nicht ungeprüft als fachliche Wahrheit übernehmen. Bewusst bestätigte bisherige Projektzugehörigkeit darf Beteiligung werden. 5. IDs, Kennungen, Körper, content, Nachweise, Entscheidungen und alte Historie erhalten. Für jeden migrierten Datensatz Revision um eins erhöhen und einen Inhaltsänderungseintrag bei unverändertem Status ergänzen. Alte Kernwerte unter extensions.contract_v1 sichern; geänderte Freigabebasis erneut prüfen. 6. Vollständigkeit, Referenzen, Portfolio-/Quellzuordnung und unveränderte gebundene Entscheidungsinhalte prüfen; dann PROJECT-Auswahl umschalten. Keine Quellenaktivierung im Cockpit oder Erfindung einer Abnahme dabei. ## Erweiterbarkeit und Prüfung Schema-/Profilversionen sind getrennt. Zusätzliche Typen, Workflows oder Rechte werden mit neuen definierten Regeln eingeführt. Leser erhalten unbekannte `extensions` verlustfrei; ohne Verständnis eines neuen Schemas nicht schreiben. Ein Namespaced-Feld allein aktiviert keine neue Rolle, Berechtigung oder Regel. Prüfe strukturell Pflichtkern, Wertebereiche, IDs, Referenzen und Historie sowie fachlich Bereitschaft, aktuelle Entscheidungsbasis, Rechte und Kapazität. Die [Beispiele](examples/README.md) enthalten denselben Vertrag für Software und Vertrieb. Strukturelle Gegenproben beweisen keine technische Schreibsperre, kein API-Verhalten und keine tatsächlich durchgeführte Migration.