@hecer/yoke 1.22.0 → 1.23.0

package/docs/superpowers/specs/2026-10-04-yoke-1.23-efficiency-design.md

@@ -0,0 +1,120 @@
+# Yoke 1.23.0: verlässliche Effizienzbasis
+
+Datum: 2026-10-04. Status: **Vom Nutzer freigegeben („Ist freigegeben“); Änderungen für 1.23 lokal umgesetzt und unabhängig geprüft, offene Abnahmen im [Validierungsbericht](../../RELEASE-VALIDATION-1.23.0.md), kein veröffentlichter Release**. KI-erstellter Entwurf aus dem NEXUS-Benchmark. Ausgangspunkt: 1.22.0, Commit `e2e3c18`.
+
+## Ziel und Entscheidung
+
+Messbar vermeidbare Einrichtungs-, Diagnose-, Integrations- und Nachweisfehler beheben. Yoke soll zuverlässig anzeigen, was läuft, warum etwas blockiert und welche Zeit-/Verbrauchsdaten vollständig oder unbekannt sind. Qualitäts-, HEAD-, Source- und geschützte Abnahmegates bleiben verbindlich.
+
+Empfohlen ist ein Minor-Release 1.23.0, weil neben Fehlerkorrekturen additive Diagnose-/Telemetryverträge entstehen. Alternativen: 1.22.1 nur für unmittelbare P0-Fixes oder größerer Scheduler-/Routingumbau. Der kleine Hotfix reicht für korrekte Messung und Belege nicht aus; für den Umbau fehlt ein gemessener Schedulerengpass.
+
+Nicht im Scope: neue Dashboardoberfläche, neue Modelle/Provider, Cloudtelemetrie, Installation anderer Plugins, abgeschwächte Tests, pauschale Sandboxaufweitung, garantierte Effizienzprozente. Native Subagenten nicht aus einem Yoke-Worker starten. Vor Änderungen vorhandene Recovery-, Evidence-, Kontext- und Telemetriemodule verwenden.
+
+## Architektur und Verträge
+
+CLI-Erkundung bleibt read-only. Preflight trennt Konfiguration und operative Fähigkeiten. Bestehender Reporter bleibt die gemeinsame Statusbasis für CLI und Verbraucher. Infrastrukturfehler erhalten strukturierte Ursachen. Artefakte werden vor Cleanup sourcegebunden gesichert. Integration verwendet die bestehenden Locks und Fingerprints; ein verlorener Lock oder verändertes HEAD kann niemals als Erfolg erscheinen.
+
+Telemetry wird lokal und additiv erweitert. Fehlende Guardian-/Approvaldaten sind unbekannt; eine nicht vom Provider zugängliche Session wird nicht mit Nullkosten ersetzt. Neue Felder unterscheiden gemessene Werte, abgeleitete Werte und Coverage. Keine zweite Orchestrierungsschicht.
+
+## Storyset und Definition of Done
+
+Jede Story beginnt mit einem reproduzierbar fehlenden Verhaltenstest. Keine Produktionsänderung vor RED. Vorhandene Tests erweitern statt paralleler Testinfrastruktur. Nach GREEN fokussierte Prüfungen und notwendige Integrations-/geschützte Gates ausführen. Ausführlicher Schrittplan und PRD entstehen nach Freigabe.
+
+### E1 — Hilfe und Flagvalidierung ohne Seiteneffekte
+
+Dateien: `src/cli.ts`, CLI-Tests unter `tests/`.
+
+- `yoke setup --help`, `yoke retrofit --help` und entsprechende `-h`-Aufrufe geben Hilfe und Exit 0, ohne Konfigurations-, Datei-, Prozess- oder Registrymutation.
+- Hilfe funktioniert auch mit angegebenem Zielpfad. Tests vergleichen vollständige Dateibauminhalte und relevante Dispatch-Spies vor/nach Aufruf.
+- Unbekannte oder inkompatible Flags der verändernden Befehle werden vor dem Dispatch mit Exit != 0 und verständlicher Ursache abgewiesen. Bestehende dokumentierte Aufrufe bleiben kompatibel.
+- Gemeinsame CLI-Hilfe wird wiederverwendet; kein neuer CLI-Frameworkumbau.
+
+### E2 — Laufzeitdateien und saubere Wiederaufnahme
+
+Dateien: `src/retrofit/gitignore.ts`, `src/loop/git.ts` nur bei tatsächlich belegter Restlücke, `tests/retrofit/gitignore.test.ts`.
+
+- Retrofit ignoriert `.yoke/supervision/` idempotent und erhält vorhandene Ignoreeinträge.
+- Die bestehende Ausnahme in `RUNTIME_PATHS` wird berücksichtigt; keine breit gefasste Freigabe anderer `.yoke`-Dateien.
+- Integrationstest: PRD-Assessment/Supervision allein verschmutzt einen frisch eingerichteten Checkout nicht; unversionierte Nutzerdatei blockiert weiterhin.
+- Bereits getrackte Runtime-Dateien werden nicht ohne ausdrückliche Migration gelöscht oder heimlich aus dem Index genommen; Diagnose nennt sie.
+
+### E3 — Korrekter kompakter Parallelstatus
+
+Dateien: `src/loop/run-command.ts`, `src/loop/reporter.ts`, `tests/loop/loop-status-render.test.ts`, `tests/loop/parallel-status-regressions.test.ts`.
+
+- Kompakter Status enthält aktive Worker mit Story/Phase, aktive Integration und Wartezustand. Kein `undefined` und kein `story=none` als einzige Beschreibung bei aktiven Storyworkern.
+- Serieller Status, kein Statusfile, leerer Workerpool, Integration ohne Implementierungsworker und abgeschlossener Loop sind getestet.
+- Bisherige Top-Level-Felder bleiben kompatibel; Parallelfelder additiv und deterministisch sortiert. Kompakte Ausgabe bleibt einzeilig.
+- Das Entfernen des Integratorstatus alleine meldet keinen Integrationsabschluss. Erfolg erst nach bestätigter Integration; Ablehnung hat eine eigene Meldung.
+
+### E4 — Browserdiagnosen mit tatsächlicher Ursache
+
+Dateien: `src/smoke/command.ts`, `tests/smoke/command.test.ts`, `tests/smoke/journeys.test.ts`.
+
+- Paketauflösung, fehlendes Browserbinary, eindeutige Sandbox-/Berechtigungsfehler und sonstige Launchfehler werden getrennt ausgewiesen.
+- Unklare Fehler bleiben `launch-failed` mit redigierter Originalursache; keine spekulative Sandboxdiagnose aus beliebigem Fehlertext.
+- Exit != 0 bei Startfehler, keine erfolgreichen Flowbelege und keine Aufforderung zur Paketinstallation bei bereits verfügbarem Paket.
+- Erfolgreiche Starts, target-relative Paketauflösung, Windows-Pfade, Cleanup und Source-Fingerprintverhalten bleiben getestet.
+
+### E5 — Operativer Preflight für RTK und Code-Intelligence
+
+Dateien: `src/retrofit/planners/codex.ts`, `canon/tools/codex-rtk-hook.mjs`, `src/code-intelligence/mcp-server.ts`, `src/code-intelligence/coordinator.ts`; vorhandene Audit-/Setup-/Backendmodule vor Erweiterung lokalisieren. Tests: `tests/retrofit/planners-codex.test.ts`, `tests/retrofit/codex-rtk-hook.test.ts`, `tests/code-intelligence/mcp-client.test.ts` plus relevante bestehende Backendtests.
+
+- RTK-Integration ist idempotent; nur Yoke-eigene Legacyhooks migrieren, fremde Hooks erhalten. Bei fehlendem nativen Hook keine behauptete automatische Kompression.
+- Echtes Codex-Toolschema und installierte RTK-Version prüfen; native Antworten verwenden. Shellrewrite nicht automatisch für verschachtelte Code-Mode-Aufrufe behaupten.
+- Preflight zeigt konfigurierten Modus, auflösbaren Workspace-Identifier und tatsächliche Backendabdeckung getrennt. Fehlende Backends führen zu explizit degradiertem Status und dokumentiertem Fallback.
+- Konfigurierter Workspace-Identifier ist entweder der tatsächlich akzeptierte Identifier oder wird mit eindeutiger Migrationsdiagnose abgewiesen; keine still ignorierte Einstellung.
+- Für unbekannte Workspace-IDs keine Cross-Workspace-Abfrage. Read-only Preflight verändert das Projekt nicht.
+
+### E6 — Kandidaten, Proofs und Abschluss sauber erhalten
+
+Dateien: vorhandene Candidate-/Integration-/Evidence-/Cleanupmodule unter `src/loop/`, `src/smoke/command.ts`; vorhandene Recovery-/Completiontests erweitern.
+
+- Erforderliche Belege bleiben nach isolierter Integration/Cleanup vorhanden, mit Source-/Config-/Environmentbindung und Datei-Hashmanifest. Retention nutzt vorhandene Evidenceverträge.
+- Belege mit Pfadtraversal oder Symlinkescape werden nicht übernommen. Fehlgeschlagene Übernahme verhindert Abschluss; Kandidat bleibt für Recovery erhalten.
+- Completion-Reruns schreiben in einen Runtimepfad; ausgewählte finale Assets werden explizit und einmal übernommen. Nutzeränderungen werden niemals automatisch mitcommittet.
+- Integration meldet busy bis zur tatsächlichen Abnahme. Source-/HEADwechsel lehnt weiter ab und invalidiert alte Nachweise.
+- Bei unverändertem Kandidaten Recovery zunächst neu verifizieren/integrieren; Implementierung nur bei konkretem Reparaturbedarf. Dafür vorhandenen Recoverypfad prüfen, nicht umgehen.
+- Externe Prozesse können nicht zwangsweise durch advisory Locks gestoppt werden; Fingerprint-/HEADprüfungen bleiben der verbindliche Schutz.
+
+### E7 — Tatsächliche Schreibbereiche und isolierte Runtime-Caches
+
+Dateien: vorhandene Scheduler-/Worker-/Candidate-/Worktree-/Dependencymodule; Tests: bestehende Parallel-/Recovery-/Schedulingtests.
+
+- Kandidatendiff wird gegen `writes` abgeglichen. Pfadabweichungen mit geänderten Dateien und möglichen Siblingkollisionen diagnostizieren. Deklarationen sind keine Sandbox.
+- Bei unerwarteter Kollision keine Integration aufgrund alter Nichtüberlappungsannahme; vorhandene Abnahme-/Recoveryverträge verwenden.
+- Gemeinsamer Paketdownloadcache ist zulässig, writable Laufzeitcaches gehören zum Worktree. Kein Schreiben in Root-`.vite-temp` und keine pauschale Sandboxlockerung.
+- Netzwerkfehler werden von Test-/Codefehlern getrennt. Offline-Cachemiss wird explizit berichtet, kein blindes endloses Retry.
+- Paket-/Lockfilewechsel invalidiert Wiederverwendung; Cold/Warm-Setup getrennt messen.
+
+### E8 — Vollständige lokale Zeit-/Usageübersicht
+
+Dateien: vorhandene Provider-/Telemetry-/Event-/Reportermodule, bestehende Telemetrietests.
+
+- Pro Rolle und Versuch: gemessener Input, Cache-Lesen, Output, Usagequelle, Coverage und fehlende Daten. Provider-/Parent-/Childansichten nicht doppelt zählen.
+- Guardian-/Approvaldaten nur erfassen, wenn vom Host verfügbar und eindeutig zuordenbar. Sonst Coverage-Lücke statt 0 oder erfundener Summe.
+- Workerprozessdauer, Summe und Vereinigungsdauer paralleler Intervalle getrennt ausgeben. Infrastruktur-/Observer-/Produktfehler getrennte Kategorien.
+- Fehlende Preise bleiben unbekannt. Cache-Lesen bleibt in Input enthalten. Reasoning-Output nicht nochmals addieren.
+- Routine-Statusbeobachtung benötigt keinen Modellaufruf; bestehende lokale Ereignisse verwenden. Sichtbare Messlücken bleiben erhalten.
+
+### E9 — Verbesserungsnachweis und Release
+
+- Regressionen des NEXUS-Laufs als deterministische Harnessfälle abnehmen; Layoutdefekt mit befülltem Incident-/Eventzustand und sichtbaren Panelunterkanten im Projektbenchmark reproduzieren.
+- Browserbelege setzen bestätigten Serverstart und nachvollziehbare App-/Sourceidentität voraus. Fremder belegter Port wird als Fehler erkannt, nicht als gültiger Nachweis.
+- Gepaarter Vorher-/Nachherbenchmark unter kontrollierten Bedingungen; erste Stufe mindestens drei Paare je Cold/Warm-Zustand, Messharness read-only während Sourcegates.
+- Ergebnis mit Stichprobenzahl, empirischer Spanne, offenen Warte-/Kostenlücken und unveränderter Testqualität. Kein garantierter Sparwert.
+- Produktionsdiff erhält unabhängige Codeprüfung und bei relevanten Grenzen unabhängige Sicherheitsprüfung. Implementer übernimmt diese Rollen nicht selbst. Fehlende Evidenz blockiert Releasebehauptung.
+- Releasechecks: `npm run lint`, `npm run build`, `npm test`, `npm run docs:check`, `npm run package:check`, `npm run audit:ci` sowie geschützte/Integrationsgates des Repositories.
+- Version erst für den fertigen Release synchronisieren: package/lockfile, Canon-/Providermanifeste, README; datierter CHANGELOG mit Verhalten, Migrationen und Grenzen. Tag/Publish erst nach Releasegates; GitHub-CI/npm-Veröffentlichung bestätigen, bevor der Release als veröffentlicht gilt.
+
+## Reihenfolge und Grenzen
+
+1. E1–E4: unmittelbare reproduzierbare Fehler.
+2. E5: keine angeblichen Effizienztools ohne operative Funktion.
+3. E6–E7: Belege, Integration und parallele Schreib-/Cachegrenzen.
+4. E8: vollständige und ehrliche Messbasis.
+5. E9: Vergleich und Release.
+
+Für E6–E8 vor Umsetzung den aktuellen Callgraph und vorhandene Verträge eingrenzen. Die Messung beweist den Fehler im Benchmark, aber nicht, dass jeder aktuelle Pfad dieselbe Restlücke hat. Bereits korrekte Schutzmechanismen bleiben erhalten.
+
+Keine Zeitprognose für diese Stories aus den sieben UI-Stories ableiten. Keine Installation oder authentifizierte Modellbenchmarkkosten allein durch diesen Entwurf auslösen. Nach Freigabe detaillierten Ausführungsplan und validiertes PRD erstellen; dann Implementierung test-first starten.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "yoke",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "Cross-agent coding harness for eight supported CLIs: curated skill canon, mechanical safety gates, autonomous loop with proof artifacts. CLI: npm i -g @hecer/yoke",
   "contextFileName": "GEMINI-EXTENSION.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hecer/yoke",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "One harness, eight agents, zero trust in \"done\" — cross-agent coding harness for Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, Kilo, Pi and Hermes: one skill canon, mechanical safety gates, an autonomous loop with screenshot/video proofs.",
   "type": "module",
   "bin": {