Hinweis 2026-09-22 (SPEC-202): Spec-Worktrees entstehen seit SPEC-202 ausschließlich über die eingebaute Worktree-Funktion (
.claude/worktrees/);worktree-manager.shist deprecated undcode -nist aus allen ausgelieferten Anweisungen verbannt. Wo dieses Konzept einen Executor aufworktree-manager.sh --yesoder einen Session-Moduscodeplant (Abschnitt 6.2), gilt SPEC-198 in der Fassung seiner Amendments A1/A2. Der Text unten ist unverändert als Konzeptstand belassen.
Spec als projektübergreifendes Ordnungskriterium¶
Konzeptionsarbeit vom 2026-09-13/14. Beschreibt, was die Spec als Ordnungskriterium über Bugs, Proposals, Worktrees, Sessions und alle registrierten Projekte hinweg operativ bedeutet, wie ein Spec-Board darauf aufsetzt, und in welcher Reihenfolge die dafür nötigen Specs entstehen. Alle Zahlen wurden am 2026-09-13/14 im Repo gemessen und rotten ab diesem Datum.
1. Problem¶
In Projekten mit mehreren Specs fehlt jede Übersicht: welche Specs existieren, welche sind fertig, welche laufen gerade, welche wären startbar, welche sind durch andere blockiert. Gewünscht ist ein Kanban-Board über alle registrierten Projekte, das im Team genutzt wird (also gehostet), auf dem eine Karte von Backlog nach "In Arbeit" geschoben wird und das bei paralleler Arbeit eine Claude-Session im eigenen Worktree auslöst. Bugs sind eine zweite Kartenart in derselben Darstellung, ebenfalls verschiebbar. Für Specs wie Bugs muss sichtbar sein, ob sie blockiert sind, und blockierte Karten dürfen nicht aktiviert oder bewegt werden.
Ergebnis der Analyse in einem Satz: Fast alle Bausteine existieren; was fehlt, ist eine erklärte Wahrheitsquelle je Lebenszyklus, ein projektübergreifender Schlüssel und ein generierter statt handgepflegter Index. Ohne diese drei Dinge zeigt jedes Board einen falschen Stand.
2. Entscheidungen des Owners (2026-09-14)¶
| # | Entscheidung | Gewählt |
|---|---|---|
| D1 | Projektübergreifende Identität | <Projekt-ID>:SPEC-NNN (z. B. F055:SPEC-012), nur beim Aggregieren gebildet, nie gespeichert. Lokale IDs, Branches, Regexe, Guards bleiben. |
| D2 | Monorepo-Entwurf (docs/architecture/product-monorepo-architecture.md) |
Zurückgezogen (superseded). Gerettet: Projekt-Resolver und "specs/ wird nie automatisch committet". |
| D3 | Interaktive Oberfläche | Gehostet auf Cloudflare für das Team; Wahrheit bleibt in Git und auf den Rechnern, ein lokaler Executor führt Absichten aus. Welle 1 lokal und lesend. |
| D4 | Ergebnis der Konzeptionssession | Dieses Dokument, Hygiene-Korrekturen, Specs der Roadmap. |
Offen, in den Specs zu klären: D5 state.yaml als erklärte Wahrheit (empfohlen); D6 specs/
kanonisch mit specs_directory:-Override; D7 projektübergreifende depends_on (empfohlen: nein,
null Vorkommen heute); D8 entschieden 2026-09-14: Ja, der Plattform-Neubau nutzt den Toolkit-Workflow. Damit ist S-9 anlegbar (Abschnitt 7).
3. Befunde¶
3.1 Bausteine, die es schon gibt¶
| Baustein | Wo | Stand am 2026-09-14 |
|---|---|---|
| Projektübergreifender Aggregator | plugins/vt-pm-intake/skills/domain-dashboard/scripts/aggregate.sh (SPEC-120) |
liest intake/projects.yaml → .design-state.yaml → state.yaml → Bugs, Owner, Markdown nach Obsidian. Las nur dir:; 11 von 13 Projekten nutzen specs_dir: und fielen still auf die Registry zurück — mit SPEC-195 FR-7/D16 liest parse_design_state specs_dir: wie dir: und zusätzlich den Legacy-Block specchen_status:. |
| Wellen/Blocker | plugins/vt-product-dev/skills/activate/SKILL.md Step 2b/3c |
nur als Prosa (das LLM rechnet); END STATES = {completed, archiviert}; /vt-d-complete Step 6 nutzt nur completed. ready/blocked werden nie persistiert. Es gibt kein Wellen-Skript. |
| Phasenableitung | plugins/vt-product-dev/skills/statusline-spec-phase/scripts/spec-phase.sh |
spec_phase, spec_id_from_branch; eine zweite, abweichende Ableitung lebt in aggregate.sh derive_phase(). |
| Worktree je Spec | plugins/vt-base/skills/git-worktree/scripts/worktree-manager.sh, /vt-d-activate Step 6.7 (SPEC-093) |
funktioniert; create ist interaktiv (zwei read-Prompts, kein --yes) und wechselt das Primär-Checkout auf main. |
| Live-Sessions | claude agents --json (CLI 2.1.270) |
je Session cwd, status (busy/idle/waiting/null), waitingFor, name, sessionId, pid; Index ~/.claude/sessions/<pid>.json. SPEC-167 FR-4 verwarf eine Cross-Session-Sicht, weil dieses Register damals fehlte. |
| Session-Start | claude --bg -n <name>, claude attach/logs/stop, code -n <pfad> (an fünf Stellen vertraglich getestet) |
nichts im Toolkit startet heute eine Session. claude -w und spawn_task legen Worktrees unter .claude/worktrees/ auf claude/*-Branches an, unsichtbar für spec_id_from_branch. |
| Break-Glass | gate_bypass: mit Datum und Grund in sechs state.yaml |
existiert, wird nirgends gezählt oder angezeigt. |
| ADRs | /vt-d-adr, docs/decisions/ADR-NNN-*.md mit spec_id, supersedes, superseded_by |
Kante Spec → ADR vorhanden, nur nicht sichtbar. |
| Cloudflare | scripts/docs-build.sh (Pages baut die MkDocs-Doku), Cloudflare-Plugin-Marktplatz installiert |
Hosting-Präzedenz. |
3.2 Die Statusquelle ist das eigentliche Problem¶
- Drei Spiegel je Spec ohne erklärte Wahrheit: Registry
specs_status,specs/<dir>/state.yaml,spec.md-Frontmatter (130 von 177 driften; dort stehen Dokumentzustände wiedraft,planned,implemented). Guard 54 sagt "glaube state.yaml", Guard 89 sagt "die Registry ist autoritativ". 19 Dateien lesenspecs_status. - Registry-Formen in freier Wildbahn:
dir:/specs_dir:/file:+specs_directory, Flow-Style (F015), Inline-Kommentare, fremde Werte (built,deployed,registered,superseded,complete); in F055 zweispecs_status-Blöcke (9 von 15 weichen ab; Guard 54 sieht nur den flachen). Registry-eigene Annotationen (completed_date136,notes43,scope_history,renumbered_*) sind aus keiner anderen Quelle ableitbar; vier Einträge haben kein Verzeichnis. - Spec-Ordner variieren:
specs/(9 Projekte),05-specs/(2, C040 hat beide),docs/specs/(S003, P01),02-specs/ohne jeden Zustand (C010), F015 keiner. Scaffold legtspecs/nicht an. - Kein Feld verbindet Spec ↔ Worktree ↔ Session (
branch:in 3 von 179state.yaml). Worktree-Ordnername ≠ Branch; Zuordnung nur über Branch oder.active-spec. - Jedes Projekt hat seine eigene SPEC-001. Drei Projektregister mit verschiedenen Schemata
(
intake/projects.yaml, Monorepo-projects.yaml,configs/project-config.yaml).last_synced: nullin allen 13 Einträgen;/vt-p-project-synchatte nie zurückgeschrieben, deshalb lagen 18 Proposals uneingesammelt in Projekten. - Bugs: eigenes Schema (severity/domain, keine typisierte Abhängigkeit);
/vt-d-completeschreibtstatus: verified, das nirgends gelesen wird.related_spec:in 118 undrelated_bug:in 121state.yaml, beide untypisiert. Bug-IDs sind überallocate_spec_id.py --kind bugallokierbar. - Blockierung existiert nur als Prosa: fünf Bugs tragen
blocks:in drei Formen (Liste, ID, Fließtext), kein Skill liest das Feld./vt-d-activateerkenntblocked (SPEC-NNN)und fragt dann "Activate anyway?", verweigert also nicht; bei Bugs warnt es, wennfix-readyoderinvestigation.mdfehlt, und fragt ebenfalls.aggregate.shzeigt Bugs nur mitreported/triaged.
3.3 Die zurückgestellten Proposals¶
Die beiden lange zurückgestellten SDD-Dokumente des Owners lagen untracked und nie qualifiziert in
intake/inbox/ des Primär-Checkouts. Sie sind mit diesem Konzept qualifiziert worden:
- SDD-Artefakthierarchie für den Plattform-Neubau v0.5 (2026-07-25) →
intake/knowledge/workflows/als Referenzwissen. Inhalt: Capability → PRD → Spec → Requirement (permanente Achse) vs. Change/Vorhaben → Spec-Deltas (temporale Achse); "Registry wird generiert, nie gepflegt"; lebende, versionierte Specs; Gates G1–G9; Bug-Typologie A–E mit eiserner Regel und Break-Glassspec_debt; Graphmodell →registry.json→ SQLite → MkDocs; Audit-Report; RACI. - SDD-Harness-Datenvertrag v0.2 (2026-07-25) →
intake/pending/from-research/alsdeferred-to-spec-Proposal. Inhalt: JSON-Schema für Spec-Frontmatter mit EARS-Requirements, Statusübergänge,approved_version, Gate-Prädikate,registry.json-Format mitnodes/edges/gate_results, Bau-Reihenfolge Parser → Registry-Generator → G7/G4/G9.
Kein Neubau-Projekt ist registriert. Abschnitt 5 hält fest, was daraus übernommen wird.
Weitere zurückgestellte Proposals im Toolkit (56 deferred-to-spec, 39 davon ohne Spec):
| Dokument | Verdikt | Wohin |
|---|---|---|
intake/processed/from-research/2026-05-13-inbox-unify-folder-structure-pd-and-coding.md |
Splitten: Specs-Ort und Frage E (State-Bookkeeping) ins Konzept; A/B/D ruhen (kein Konsument, kein gemessener Schmerz); C (OneDrive → Repo) bleibt Owner-Entscheidung | S-3, S-1/S-2 |
intake/processed/from-projects/2026-08-29-spec-kopien-driften-ohne-dass-es-jemand-merkt.md |
Zurückgezogen (der Autor hat das Design selbst verworfen); eine Zeile überlebt: jede unvermeidliche Kopie trägt die Version ihrer Quelle | S-5 |
intake/processed/2026-03-17-worktree-activate-integration.md |
umgesetzt als SPEC-093 (completed 2026-03-23), Status nie nachgezogen | erledigt |
SPEC-181 (specified) |
erweitern auf vier Lebenszyklen | S-2 |
SPEC-164 (specified) |
unverändert; definiert die "unattached"-Spur des Boards | Abschnitt 4.5 |
F055 docs/toolkit-proposals/2026-09-08-registry-fuehrt-jede-spec-zweimal.md |
wichtigste Voraussetzung: ein Schreiber statt Edit-Anweisung | S-1 |
F055 docs/toolkit-proposals/2026-09-07-prueftor-ledger-driftet-in-drei-formen.md |
Vokabular-Teil nach S-2; Gate-Writer ist eine eigene kleine Spec außerhalb dieser Roadmap | S-2 |
V004 docs/toolkit-proposals/spec-status-archiviert.md (applied), step-level-tracking.md |
Evidenz für END STATES als Menge; Step-Tracking bleibt separat (Board zeigt Phase, nicht Steps) | S-2 |
docs/decisions/2026-08-29-spec-ist-ein-internes-implementierungsartefakt.md, docs/solutions/patterns/cross-repo-spec-tracking.md |
Axiome | Abschnitt 4 |
4. Konzept¶
4.1 Axiome (bereits entschieden, wiederverwendet)¶
Eine interne Spec je Feature (Entscheidung 2026-08-29). Eine Spec lebt im Repo, dem ihr Deliverable
gehört (cross-repo-spec-tracking.md). Das Toolkit kennt andere Repos nur über intake/projects.yaml.
4.2 Fünf Begriffe, mehr nicht¶
| Begriff | Bedeutung |
|---|---|
| Spec | Change-förmig, endlich: specified → in_progress → completed / archiviert / rejected / parked. Im SDD-Vokabular ein Change/Vorhaben mit eingebettetem Anforderungsdelta, nicht die lebende L3-Spec (Abschnitt 5). |
| Bug | Zweite Kartenart mit eigenem Lebenszyklus; hängt über related_spec an einer Spec oder ist bewusst "unattached". |
| Projekt | Registriertes Repo in intake/projects.yaml; liefert das Schlüsselpräfix. |
| Capability | Optionales Freitextfeld capability: im Frontmatter, nur Gruppierung; kein Register, kein ID-Bestandteil, kein Gate. |
| Index | .design-state.yaml (specs_status, bugchen_status): abgeleitet, nie autoritativ. |
Nicht eingeführt: lebende Spec, Version, Freigabe, Requirement-Knoten.
4.3 Identität¶
<Projekt-ID>:SPEC-NNN bzw. <Projekt-ID>:BUG-NNN. Die Projekt-ID ist die Kurznummer, die jedes
Repo-Verzeichnis schon trägt (F055, V004, V025), aus einem neuen id:-Feld in
intake/projects.yaml (Fallback aus name:). Der Schlüssel wird abgeleitet, nie gespeichert. Die
SDD-Alternative (Capability in der ID, SPEC-CUST-014) wurde mit D1 verworfen: eine Umbenennung
würde 300 IDs entwerten.
Das Feld heißt spec_root: und nicht specs_dir: (SPEC-195 D1): specs_dir: ist in den
.design-state.yaml der Projekte der Ordner EINER Spec, spec_root: der Ordner ALLER Specs eines
Projekts. Ein Unterrepo, das eigene Specs nummeriert, bekommt id: aus Elternnummer plus
Komponentennummer (F015-01) und parent: (SPEC-195 D4); board: false nimmt ein privates
Projekt aus jeder projektübergreifenden Ansicht (SPEC-195 D6). Die Reihenfolge des Spec-Orts ist
einmal erklärt: .design-state.yaml specs_directory → intake/projects.yaml spec_root → specs/;
ein explizites specs_directory: null gilt als Erklärung "hier nicht" (SPEC-195 D9). Das Toolkit
selbst wird nie registriert und löst ohne Eintrag auf V025 auf (SPEC-195 D3). Die D-Nummern in
diesem Absatz sind die aus specs/195-project-identity-and-spec-location/decisions.md, nicht die
D1–D8 dieses Dokuments.
Die Asana-Konfiguration configs/project-config.yaml wird über dieselbe Projektnummer verbunden —
dokumentiert, nicht gebaut (SPEC-195 FR-6). Die Datei wird aus Asana generiert
(generated_from_asana:), deshalb steht der Hinweis hier und nicht dort. Fehlt die Entsprechung,
ist das eine sichtbare Warnung, nie ein Fehler: die Board-Identität hängt an
intake/projects.yaml, nicht an Asana.
4.4 Eine Wahrheitsquelle je Lebenszyklus¶
| Lebenszyklus | Autoritativ | Spiegel (regenerierbar) |
|---|---|---|
| Spec | specs/<dir>/state.yaml → status |
Index specs_status (gerendert); spec.md-Frontmatter status (Geburtswert oder entfernt) |
| Bug | vor Promotion intake/pending/bugs/BUG-NNN.md, danach bugs/<dir>/state.yaml |
Index bugchen_status |
| Proposal | Intake-Kopie → toolkit_proposal_status |
Projektkopie in docs/toolkit-proposals/ (swept_to: + source_commit:) |
| Gate | state.yaml → *_gate.status (+ Gate-Dateien) |
keiner; Vokabular deklarieren |
4.5 Wie Dinge an der Spec hängen¶
Gespeichert wird eine Richtung, die Rückrichtung leitet das Board ab:
| Relation | Gespeichert | Abgeleitet |
|---|---|---|
| Spec → Projekt | nichts; der Spec-Ordner liegt im registrierten path: |
Resolver Pfad → Projekt-ID |
| Bug → Spec | related_spec: |
Spec → Bugs; null = Spur "unattached bugs" |
| Proposal → Spec | spec.md source: |
Spec → Proposals; deferred-to-spec ohne Rückverweis = Spur "orphaned deferrals" |
| Spec → Spec | depends_on, supersedes, split_into, duplicate_of |
ready / blocked / wave |
| Spec → ADR | spec_id: im ADR-Frontmatter |
Kante decided_by |
| Worktree → Spec | nichts (optional .active-spec im Worktree) |
git worktree list --porcelain → Branch → ID |
| Session → Spec | nichts | claude agents --json → cwd → Worktree → ID |
| Priorität | spec.md priority:; PM-Override toolkit-global (SPEC-122) |
effektive Priorität + Drift-Marker |
Nie gespeichert: zusammengesetzter Schlüssel, ready/blocked/wave, Phase, Links, Drift-Flags.
Lokal vs. global. Projektlokal: Spec-Ordner, state.yaml, bugs/, Index,
docs/toolkit-proposals/. Toolkit-global: intake/projects.yaml (einziges Register des Boards; die
Asana-Konfiguration wird per Projektnummer gejoint, nicht gemerged), Intake, Vokabular-Quelle,
Overrides, gerenderte Boards.
4.6 Zwei Kartenarten, ein Blockierungsmodell¶
| Spec | Bug | |
|---|---|---|
| Wahrheit | specs/<dir>/state.yaml |
bugs/<dir>/state.yaml |
| Bereit, wenn | alle Blocker in einem END STATE, Status specified |
alle Blocker in einem END STATE, Status fix-ready und investigation.md vorhanden |
| END STATES | completed, archiviert |
fixed, resolved, verified, wontfix, duplicate (deklariert in S-2) |
| Branch | feature/spec-N-* |
fix/bug-NNN-* |
| Bestehende Kanten | depends_on, source: |
related_spec, related_bug (untypisiert), blocks (Prosa) |
Ein typisiertes Feld für beide: blocked_by: [SPEC-…, BUG-…] in state.yaml, Vorwärtsrichtung
gespeichert, Rückrichtung blocks abgeleitet. depends_on bleibt für Spec → Spec und wird beim
Rechnen mit blocked_by vereinigt. Erlaubt sind alle vier Kombinationen: Spec wartet auf Spec, Spec
wartet auf Bug, Bug wartet auf Spec, Bug wartet auf Bug. related_* bleibt informativ und blockiert
nie. Die fünf Prosa-blocks: werden einmalig übersetzt (S-5).
Der Wellen-Algorithmus rechnet über den vereinigten Graphen eines Projekts. Ergebnis je Karte:
ready, blocked (BUG-192 open, SPEC-003 in_progress) mit dem Status jedes Blockers, Welle,
blocks: N.
Durchsetzung, nicht Anzeige. Eine blockierte Karte kann nicht nach "In Progress" bewegt und nicht
aktiviert werden: /vt-p-spec-board move und /vt-d-activate verweigern mit E_BLOCKED und nennen
die Blocker; nur --force "<Grund>" hebt das auf und schreibt dependency_override: {reason, by, at}
in die state.yaml, das Board zeigt dann das Badge forced. Das ersetzt das heutige "Activate
anyway?". Nicht fix-fähige Bugs sind ebenso nicht aktivierbar, mit Hinweis auf /vt-d-investigate-bug.
4.7 Wo das Kriterium bricht¶
| Fall | Ehrliche Antwort |
|---|---|
Knowledge-Work-Deliverables ohne state.yaml |
Projektzeile "kein Spec-Tracking"; das Board erfindet keinen Status. |
| OneDrive-PD-Projekte | nur Projektphase aus .design-state.yaml current_phase, nie Spec-Ebene. |
| Externe Entwickler-Repos (C010, Prosa-Status) | dokumentierte Ausnahme "unknown (prose)", keine Drift-Flags. |
| Bugs ohne Spec | eigene Spur; nie eine erzwungene Spec. |
| Quickfix / Fast Lane (SPEC-164; SDD: Fix-Lane) | Board ist blind und sagt es. |
| Drei Projektregister | joinen, nicht mergen; fehlender Join sichtbar. |
5. Verhältnis zum SDD-Modell des Plattform-Neubaus¶
5.1 Die zentrale Abgleichung: Change vs. Spec¶
| Eigenschaft | SDD L3-Spec | SDD Change/Vorhaben | Toolkit-Spec |
|---|---|---|---|
| Lebensdauer | lebend, versioniert | endlich | endlich |
| Identität | je Verhalten, genau eine Capability | je Release-Bündel, kreuzt Capabilities | je Feature-Änderung, Branch, Worktree, Gates |
| Freigabe | LPM-Gate | Planung/PM | keine ("nobody signs it off"); Aktivierung ersetzt Freigabe |
| Enthält Requirements? | ja, versioniert | nein, referenziert Specs | ja, einmalig; das Delta ist inline |
| Nach Abschluss | bleibt wahr | archiviert | historisches Dokument |
Das Toolkit fasst SDD-Change und dessen Spec-Deltas in einem Artefakt zusammen (die
OpenSpec-"Delta-Spec"-Form, die das SDD-Dokument selbst zitiert). Das ist kohärent mit der
Entscheidung vom 2026-08-29 und erklärt die 75 % Frontmatter-Drift: der Dokumentstatus eines Change
ist nach der Geburt bedeutungslos, nur der Arbeitsstatus zählt. Folgen: Karten = Changes
(= Toolkit-Specs); Swimlanes = Projekt, optional Capability; Spalten = Arbeitszustände. Eine spätere
Neubau-Registry liefert ihre lebenden Specs nur als Referenzknoten, ihre CHG-* als Karten. Die
Entscheidung vom 2026-08-29 wird nicht ersetzt; sie regelt Adressat und Kardinalität, nicht ob ein
Projekt seine eigenen Artefakte intern freigeben darf.
5.2 Verdikte¶
| SDD-Idee | Verdikt | Wohin |
|---|---|---|
| Zwei Achsen, Change vs. Spec | übernommen (Vokabular) | 4.2, 5.1 |
| Registry generiert, nie gepflegt | Prinzip übernommen, Form angepasst: ein Renderer, ein Schreiber, ein Diff-Guard. Die handgepflegte Datei bleibt, weil 19 Konsumenten, 5 Formen und 136 Annotationen daran hängen | S-1 |
Status ins Frontmatter statt state.yaml |
abgelehnt (Dokumentstatus ≠ Arbeitsstatus); Frontmatter-status einfrieren oder aus dem Template entfernen, Guard-89-Ratchet dann stilllegen |
S-2 |
Vokabular draft/in_review/approved/…, version, approved_version |
Quell-Vokabular → Spalten-Mapping als Daten (SPEC-181 FR-8); Version und Freigabe zurückgestellt | S-2 |
supersedes/superseded_by, nie löschen, Rückverweisregel |
Kanten-Vokabular depends_on, supersedes/superseded_by, split_into/parent_spec, duplicate_of, blocked_by |
S-2, S-4 |
Gates als reine Prädikate; gate_results-Form |
Board-Befunde als benannte Prädikate checks[] (drift, ref-integrity, cycle, unknown-status, tombstone, bypass-without-reason, work-without-activation, count-gate) |
S-4 |
G9 spec_debt, Break-Glass gezählt |
gate_bypass als Badge, Zählung, Befund ohne Grund. Arbeitstagskalender abgelehnt |
S-4 |
| G1/G2/G3, G8 | zurückgestellt (CI, Stack, Testinventar); G8 höchstens Badge | — |
| G4 Größe (>15 Requirements, "und" im Titel) | später als Zeile in /vt-d-spec-check |
außerhalb |
Graphmodell → registry.json → MkDocs → SQLite |
Board-JSON = striktes Subset des SDD-registry.json (5.3); MkDocs/Pages-Veröffentlichung als Welle 1.5; SQLite zurückgestellt |
S-4, S-6 |
| Bug-Typologie A–E, "Code oder Spec falsch?" | Triage-Ergebnis Spec (legt Spec mit source: = Bug an), resolution: fix|spec|not-a-bug, Spur "Bugs → braucht Spec" |
S-5 |
| Eiserne Regel, Discovery/Specs, Challenge-Gate, RACI/CODEOWNERS, EARS im Frontmatter, Audit-Report, Kontextpaket, DoR/DoD | zurückgestellt an den Neubau bzw. abgelehnt (Duplikat oder Zehn-Rollen-Governance) | Harness-Proposal |
| WIP 2 phasenversetzt; "Agentenläufe sind Jobs"; Review-Kapazität als Engpass | Header-Metriken WIP und "in review"; Session-Spalte als Job-Monitor; Zuschau-Statusline abgestuft | S-4, S-6 |
| Kopie trägt Version der Quelle | swept_to: trägt source_commit: (Kurz-SHA), kein SemVer |
S-5 |
| ~1500-Zeilen-Deckel | NFR-Budget (Board-Kern ≤ ~1200 Zeilen), Überschreitung = Review-Befund | S-4, S-6 |
| Dateien + Git als Wahrheit, DB generiert und wegwerfbar | bestätigt D3 unabhängig | 6.4 |
5.3 Board-JSON als Subset des SDD-registry.json¶
Jeder vom SDD definierte Schlüssel behält Name und Bedeutung: generated_at, commit,
nodes[type, id, status, capability, spec_debt], edges[from, to, type], checks[] in der Form von
gate_results. Alles Toolkit-eigene liegt unter attrs (Knoten) oder trägt das Präfix vt:
(Kantentypen vt:reports_against, vt:sourced_from, vt:worked_in, vt:runs_in). Knotentypen:
Spec, Bug, Project, ADR. Eine spätere Neubau-Registry lädt in denselben Leser; das
SQLite-Schema nodes(id, type, attrs) / edges(from, to, type) bleibt anwendbar.
6. Board-Architektur¶
6.1 Welle 1 — lesendes Board, lokal (S-4)¶
Neue Skill /vt-p-spec-board in plugins/vt-pm-intake/skills/spec-board/ mit scripts/board.sh
(Bash 3.2 + awk wie aggregate.sh; genau ein python3-Aufruf für JSON). Sourced aggregate.sh,
spec-phase.sh und zwei neue geteilte Stücke in vt-base: plugins/vt-base/lib/spec-registry.sh
(Parser für alle Registry-Formen, resolve_spec_dir, known_spec_status, --render <spec>) und
plugins/vt-base/bin/spec-waves.sh (der erste echte Wellen-Algorithmus über Specs und Bugs; END
STATES einmal deklariert, Zyklen gemeldet; /vt-d-activate und /vt-d-complete rufen ihn auf).
Spalten, für Specs und Bugs dieselben, erste Regel gewinnt: Needs attention · Done ·
Archiviert/Parked (archiviert bleibt ein eigenes Wort) · Review/Finalize · In Progress · live ·
In Progress · no session · Blocked · Ready · Backlog. Kartenart als Typ-Badge; --group-by
project|capability|type. Bug-Zuordnung: reported/triaged → Backlog, fix-ready +
investigation.md → Ready oder Blocked, investigating/in_progress/partially-fixed → In
Progress, fixed/resolved/verified → Done, wontfix/duplicate/deferred → Archiviert/Parked,
reopened → Ready oder Blocked, open → Needs attention. Badges: bypass, forced, drift,
registry-only, no-worktree, blocks:N. Header: Zählgate (Zeilen = Registry-Einträge), Bypass-Zahl,
WIP je Person/Projekt, "in review: N". Live-Overlay über git worktree list --porcelain und
claude agents --json; Ausfall → unavailable, Exit 0. Ausgabe: Markdown, JSON (5.3), Terminal.
Schreibt nichts.
6.2 Welle 1b — Befehle, der eine Schreiber, der Executor (S-1, S-6-Vorstufe)¶
plugins/vt-base/bin/spec-status-write.py (stdlib) schreibt state.yaml, rendert den
Registry-Block und wendet ihn auf jeden specs_status-Block an; atomar, kommentarerhaltend,
verweigert doppelte Schlüssel. Guard 54 bekommt "gerenderter Block == Registry-Block".
worktree-manager.sh --yes. /vt-p-spec-board move <Projekt>:<SPEC-NNN|BUG-NNN>
in_progress|parked|backlog [--worktree] [--session none|code|claude-bg] [--force "<Grund>"],
open, sessions. Der Executor prüft in dieser Reihenfolge: Schema → Idempotenz → frischer Zustand →
Blocker (E_BLOCKED) → Bug-Readiness (E_NOT_FIX_READY) → Deckel → Primär-Checkout dirty →
Branch/Worktree wiederverwenden → Live-Session im Ziel → ausführen. Review/Done/Rejected sind nicht
verschiebbar. Session-Modi: code (code -n <absoluter-pfad>), claude-bg
(claude --bg -n "SPEC-NNN <slug>" im Worktree). Nicht benutzt: claude -w, spawn_task, --tmux,
claude rm.
6.3 Welle 1.5 — Veröffentlichung read-only¶
Board-Markdown/JSON über die bestehende MkDocs/Pages-Pipeline (scripts/docs-build.sh) publizieren,
bevor Worker und D1 gebaut werden.
6.4 Welle 2 — gehostetes Team-Board auf Cloudflare (S-6, D3)¶
Prinzip: Git bleibt die Wahrheit, der Rechner bleibt der Ort der Ausführung, Cloudflare hostet
Sicht und Absichten. UI: Pages, HTML5-Drag-and-drop, keine CDN-Abhängigkeiten. API: Worker + D1
(snapshots, rows, intents, results); Durable Object erst bei Live-Push. Auth: Cloudflare Access
mit VisiTrans-E-Mails, Service-Tokens je Rechner, Cf-Access-Authenticated-User-Email =
requested_by. Lokal: /vt-p-spec-board sync pusht einen sanitisierten Snapshot (Projekt-ID, Spec,
Status, Spalte, Branch, Session-Status; nie absolute Pfade, Prompts, Secrets), zieht eigene Intents,
führt sie über den Executor aus, pusht Ergebnisse. Intents laufen nur auf dem Rechner der
anfordernden Person; Divergenz zwischen Rechnern wird angezeigt, nicht aufgelöst; die Cloud schreibt
nie in Git. Blockierte und nicht fix-fähige Karten sind kein Drop-Ziel für "In Progress"; der
Executor prüft dieselbe Regel erneut. Session-Spalte = Job-Monitor mit Ergebnisbenachrichtigung.
Fallback ohne Cloud: board-snapshots-Branch.
7. Roadmap¶
Hygiene, erledigt mit diesem Konzept: Status-Nachzug für das Worktree-Proposal (SPEC-093), Rückzug
des Spec-Kopien-Proposals, Rückzug des Monorepo-Entwurfs, erster /vt-p-project-sync-Lauf gegen
F055 und V004, Qualifizierung der beiden SDD-Dokumente. Offen als Projektentscheidung F055: den
zweiten specs_status-Block abbauen.
| # | Arbeitstitel | Größe | depends_on | Schaltet frei |
|---|---|---|---|---|
| S-1 | Ein Renderer, ein Schreiber, ein Diff-Guard für Index und state.yaml |
M | — | vertrauenswürdiger Index; Voraussetzung für jedes move |
| S-2 | SPEC-181 erweitern: vier Lebenszyklen, END STATES je Typ, Spalten-Mapping als Daten, Kanten-Vokabular mit blocked_by, Synonyme, verified/open klären, Frontmatter-status einfrieren |
M | SPEC-181 | Board zählt nie einen fremden Wert als aktiv; Blocker sind Daten |
| S-3 | Projektidentität und Spec-Ort: id:, parent:, spec_root:, board: in intake/projects.yaml, resolve_project.sh über plugins/vt-base/lib/project-registry.sh, scaffold legt specs/ an — SPEC-195 |
S | — | zusammengesetzter Schlüssel |
| S-4 | Spec-Board v1, lesend, lokal: Specs und Bugs als Karten, spec-waves.sh geteilt, JSON als SDD-Subset, checks[], bypass/forced, NFR-Budget |
L | S-3 | die fehlende Übersicht |
| S-5 | Proposal↔Spec- und Bug↔Spec-Schluss: spec_id: ins Proposal, applied bei Abschluss, swept_to: + source_commit:, Triage-Ergebnis Spec, blocked_by abfragbar, /vt-d-activate verweigert hart |
S | S-1, S-2 | Blockierung greift auch ohne Board |
| S-6 | Spec-Board v2, gehostet für das Team (Welle 1b, 1.5, 2; /vt-d-shape vorab) |
L | S-1, S-4 | Karte ziehen im Team |
| S-7 (abgestuft) | Multi-Session-Statusline, nur falls nach S-6 noch gewünscht | S | S-6 | — |
| S-8 (spekulativ) | Projektübergreifende depends_on (nur bei D7 = ja) |
M | S-4 | — |
| S-9 (freigegeben durch D8 = Ja, 2026-09-14) | SDD-Harness-Kern als Toolkit-Bibliothek: schema-validierter Frontmatter-Parser, nodes/edges-Renderer, registry-interne Prädikate (G4/G7/G9-Analoga) | M | SPEC-194, SPEC-181 A1, SPEC-196 | der Neubau baut auf dem Toolkit auf statt auf einem zweiten Framework |
Angelegt am 2026-09-14: S-1 = SPEC-194, S-2 = SPEC-181 Amendment A1, S-3 = SPEC-195, S-4 = SPEC-196,
S-5 = SPEC-197, S-6 = SPEC-198, S-9 = SPEC-200 (nach D8 = Ja). S-7 und S-8 bleiben Roadmap-Einträge ohne Spec; der Stand aller
sieben steht in .design-state.yaml und im Änderungsledger, nicht hier.
8. Risiken des Über-Übernehmens¶
| Risiko | Guard |
|---|---|
Freigabe durch die Hintertür (approved_by, approved_version) |
Change-förmige Natur ist deklariert; keine Freigabefelder in S-2 |
| SemVer auf Change-förmigen Specs | Git-SHA statt Version (S-5) |
| Requirements im Frontmatter | abgelehnt; bräche Birth-Gate, DoR/DoD-Guard und 177 Specs |
| CI-Gates für Projekte ohne CI | das Board meldet Prädikate; nur der Diff-Guard von S-1 blockiert, und nur wo die Suite läuft |
| Audit-Maschinerie im Toolkit | nur "nie Zeilen löschen, Bypässe zählen" wird geerbt |
| Framework-Eigenbau | NFR-Budget; S-9 gated durch D8 |
| Capability-Wildwuchs | Freitextfeld, kein Register, kein Gate |