@hecer/yoke 1.6.1 → 1.7.0

package/docs/PRODUCT-DIRECTION-2026-09-05.md

@@ -0,0 +1,183 @@
+# Yoke: Produktstand und Gesprächsgedächtnis
+
+Stand: 2026-09-05. Grundlage: Repository-Analyse und anschließende Produktdiskussion mit dem Nutzer.
+
+Dieses Dokument sichert die wesentlichen Befunde, Vorschläge und Nutzerpräferenzen der Sitzung. Die automatische claude-mem-Erinnerung meldete einen Ausfall; ihre Speicherung wurde nicht vorausgesetzt. Es ist kein Implementierungsnachweis und kein Auftrag, sämtliche Vorschläge ungefragt umzusetzen. Vor Implementierung den aktuellen Code und die Prioritäten prüfen.
+
+## Nutzerabsicht und akzeptierte Richtung
+
+- Yoke soll gegenüber der Konkurrenz interessanter und ein regelmäßig genutztes Entwicklerwerkzeug werden.
+- Codex, Claude und Gemini sollen funktional gleichwertig integriert sein. Gleiche Modellintelligenz ist damit weder zugesagt noch messbar belegt.
+- Der Nutzer begrüßte die Richtung: überprüfbare Abnahme, Ziele, Wiederaufnahme und Anbieterwechsel.
+- Tokenverbrauch und Entwicklungszeit sollen sinken: deterministische Werkzeuge, kleine/schnelle Modelle, gezielte Eskalation und sinnvolle Parallelität.
+- Neue Nutzeridee: bessere Zeitschätzungen für alle Tasks; bestehende ETA verbessern.
+- Neue Nutzeridee: ein Dashboard für Yoke mit Übersicht und Detailansichten für jedes Projekt. Interesse ist festgehalten; Umfang und Gestaltung sind noch nicht beschlossen.
+- Der Nutzer bat ausdrücklich darum, die gesamte bisherige Diskussion dauerhaft zu sichern.
+
+## Ausgangsbefund der Prüfung
+
+Geprüft: Yoke 1.6.2, Commit d066058. Keine Produktcodeänderungen oder neuen authentifizierten Modellbenchmarks während der Analyse.
+
+- Gesamtsuite: 1018 bestanden, 2 übersprungen, 1 Test-Timeout von insgesamt 1021 Tests.
+- Betroffen: tests/loop/parallel-cli.integration.test.ts, Test "does not integrate when the target rewinds during integrated gates". Gesamtlauf überschritt das 5-Sekunden-Limit; separater Lauf mit 20-Sekunden-Limit bestand in etwa 1,42 Sekunden Testzeit. Kein damit nachgewiesener Integrationsfehler; Testinstabilität untersuchen.
+- TypeScript-Prüfung und docs:check bestanden.
+- Vorhandene Nutzeränderungen wurden nicht angefasst: .gitignore, .omo/, .playwright-mcp/, docs/community-outreach-2026-08-20.md, docs/launch-copy-2026-08-21.md.
+
+### Stärken
+
+- Mechanische Prüfkommandos und strukturierte Akzeptanzkriterien; neue Standardkonfigurationen verlangen Kriteriennachweise.
+- Gemeinsamer Canon mit nativen Skill-Paketen und Werkzeugkonfiguration für drei Anbieter.
+- Abhängigkeiten, parallele Worker, Arbeitsbäume, Locks, Prozessüberwachung und Integrationswarteschlange.
+- Schema-validierte Reviews und optionaler Qualitätsvergleich mit vertauschter Kandidatenreihenfolge und Konsistenzprüfung.
+- Expliziter, versionierbarer Projektkontext und lokale Belege; kompakte Ausgabe mit Artefaktverweisen.
+- Benchmarkdokumentation benennt fehlende Telemetrie und fehlgeschlagene Läufe.
+
+### Konkrete Lücken und Grenzen
+
+1. Serielles --isolate entfernt den Arbeitsbaum im finally auch bei Fehlern; GitOps verwendet worktree remove --force. Unfertige Änderungen können verloren gehen. Siehe src/loop/loop.ts und src/loop/git.ts.
+2. Ausgeführte Tests sind nicht automatisch unabhängige Abnahmetests: Implementierer kann im untersuchten Pfad Testdateien und Testskripte ändern. Geschützte Abnahmen bzw. Kontrolle von Testabschwächungen fehlen.
+3. Reviews, Audit, integrierte Abschlussprüfung und Browserbelege sind teils optional. README-Garantien müssen zwischen unterstützt, aktiviert und nachgewiesen unterscheiden.
+4. flow-smoke prüft Seitenaufruf, Fehler und optionale Selektoren; kein genereller Nachweis mehrstufiger Benutzerabläufe.
+5. repositoryFingerprint erfasst Inhalte bestehender unversionierter Dateien nicht; bei Git-Fehlern liefert es einen leeren String. Zusätzliche Reviewer-Schreibkontrolle ist damit unvollständig.
+6. Routing nutzt grobe Kostentiers und Erfolgsquoten. Fehlende Telemetrie wird teilweise als 0 aggregiert. Vollständige Kosten für Controller, Worker, Reviews, Reparaturen und Kandidaten fehlen als verlässlicher Gesamtvertrag.
+7. Design-Scan prüft Stilmerkmale wie Lila/Verläufe; kein allgemeiner UX-, Accessibility- oder KI-Autorschaftsnachweis.
+8. Bisherige Benchmarks belegen keine allgemeine Überlegenheit gegenüber nativen Agenten oder Konkurrenz.
+
+### Anbieterparität
+
+- Codex: Skills, Aufrufrichtlinie, Rollen, JSON-Ausgabe, Modell/Reasoning, RTK-Hook. Direkte Verbindung zum nativen Goal-Zustand fehlt im untersuchten Code. Adaptives Routing deaktiviert native Multi-Agent-Funktionalität bewusst.
+- Claude: Skills, manuelle Aufrufsteuerung, Streaming-JSON, Modell/Effort, RTK-Hook mit Plattformbedingungen. Native strukturierte Ausgabe und Teamfunktionen sind nicht durchgängig ausgenutzt.
+- Gemini: native Skills plus Slash-Commands vorhanden. Adapter fordert kein stream-json an, obwohl Auswertung JSON-Ereignisse erwartet und Reviews berichtete Modellidentität verlangen. Gemeinsame Reasoning-/Bare-Optionen werden nicht entsprechend umgesetzt. Installer-Annahme fehlender Rewrite-Hooks ist veraltet; BeforeTool unterstützt Argumentänderungen.
+- Native Provider-Funktionen einzeln nutzen und auf ein gemeinsames Ergebnisformat abbilden; nicht auf identische APIs aller Anbieter warten.
+- Reale Vertragsfälle je CLI/Version/Plattform: Implementierung, Review, Ausgabe, Modellidentität, Telemetrie, Rechte, Abbruch, Wiederaufnahme und Skill-Aufruf.
+- Lokal geprüft: codex-cli 0.153.4, Claude Code 2.1.200, Gemini CLI 0.33.1. Verfügbare CLI bedeutet keine nachgewiesene Authentifizierung oder erfolgreiche Modellaufgabe.
+
+### Benchmarkgrenzen
+
+bench/RESULTS.md dokumentiert eine Codex-Routingstudie mit drei Vergleichspaaren. Alle versteckten Abnahmen bestanden; Median ungefähr 33,8 % weniger Laufzeit und 11 % weniger frische Eingabetokens. Vergleich: Routing an/aus innerhalb Yokes, nicht Yoke gegen natives Codex. Andere Architekturaufgaben blieben SELF und bezahlten Controller-Overhead. Keine allgemeinen Sparprozente versprechen.
+
+## Produktwette: täglicher Nutzen
+
+Yoke beantwortet: "Kann ich diese Änderung übernehmen, und wie bekommen wir sie bei offenen Befunden fertig?"
+
+Vorgeschlagene Positionierung: gemeinsame Abnahme- und Fortsetzungsschicht für Coding-Agenten. Native Agenten verfolgen Ziele; Yoke hält überprüfbaren Projektzustand, Kriterien und Abnahme stabil. Kein unnötiger zweiter Orchestrator über nativen Goals.
+
+### Einstieg: yoke check (Vorschlag, noch kein implementierter Befehl)
+
+- Bestehendes Repository, vorhandener Diff und konkrete Anforderung reichen für den Einstieg; vollständiger Retrofit soll nicht Voraussetzung sein.
+- Ausgabe unterscheidet bestanden, fehlgeschlagen und nicht überprüft.
+- Bevorzugt ausführbare Befunde: Testreproduktion, Browserablauf, Vertragsverletzung statt spekulativer Review-Kommentare.
+- Beispielvorführung: bestehende Tests grün, Yoke reproduziert eine doppelte Bestellung bei Doppelklick, Reparatur und erneute Abnahme belegen die Behebung.
+- Belege sind an den tatsächlich geprüften Codezustand gebunden.
+- Kritische Abnahmetests gegebenenfalls durch gezielte Mutation prüfen: erkennt der Test den passenden absichtlich eingebauten Fehler?
+
+### Wiederaufnahme und Anbieterwechsel
+
+Übergabepaket enthält Ziel, Kriterien, Patch/Arbeitsstand, Umgebung, bestandene Prüfungen, offene Fehler, verworfene Ansätze, Berechtigungen und verbleibendes Budget. Änderungen und Belege bleiben bei Fehlern erhalten. Anbieterwechsel erhält überprüften Zustand und verlangt keine erneute Erklärung durch den Nutzer.
+
+Blocker unterscheiden: Implementierungsfehler, Infrastruktur/Rate-Limit, fehlende Zugangsdaten, echte Produktentscheidung. Ein Anbieterwechsel löst nicht jede Blockade.
+
+### Zielmodell
+
+Gemeinsamer Zielzustand verbindet PRD, Kriteriennachweise, Änderungs-Inbox, Budget, Blocker, Wiederaufnahme und integrierte Abschlussprüfung. Native Codex Goals integrieren, keine Abschlussgarantie allein aus Modelltext ableiten. Modell darf Lösungsweg wählen; verbindliche Abnahmebedingungen bleiben nachvollziehbar.
+
+### Zielgruppe und Differenzierung
+
+Vorgeschlagener erster Fokus: Entwickler und kleine Teams mit bestehenden TypeScript-Webprojekten und bereits genutzten Coding-Agenten. Erst dort Einrichtung und Abnahme zuverlässig machen.
+
+Skills, Autonomie, frischer Kontext und Zweitmeinungen sind kein exklusiver Vorsprung. Aktuelle Konkurrenz: native Codex Goals/Subagenten, Superpowers auch mit Codex/Gemini, gstack mit Codex/QA/Reviews, GSD Core mit mehreren Hosts und Phasenworkflow.
+
+Aufbauender Vorteil: robuste Projektintegration, wiederverwendbare Abnahmefälle, zuverlässige Wiederaufnahme, echte Erfolgsdaten nach Aufgabentyp und nützliche PR-Berichte. Team-Zahlungsbereitschaft ist eine unbestätigte Hypothese.
+
+Validierung: zehn passende Entwickler mit echten Änderungen; Zeit bis zum nützlichen Befund, Reproduzierbarkeit, Fehlalarme, eingesparte Nachprüfung und freiwillige Wiederverwendung messen.
+
+## Token-, Kosten- und Geschwindigkeitsstrategie
+
+Optimierungsziel: Kosten und Zeit pro unabhängig abgenommener Änderung, einschließlich Fehlversuchen und menschlicher Nacharbeit. Tokenzahl, Geldkosten und Wartezeit getrennt betrachten.
+
+1. Deterministische Aktionen ohne Modell: Formatter/Linter, AST-/LSP-Renames, Schema-Generatoren, Logparser, Versionssynchronisierung, geprüfte Codemods und Symbolsuche. Voraussetzungen/Nachbedingungen prüfen.
+2. Regeln vor Routing-Modell: eindeutige Aufgaben ohne Controller-Aufruf zuordnen; unklare Fälle durch Modell entscheiden lassen.
+3. Ausführungsstufen Werkzeug / Schnell / Standard / Stark. Risiko, Testbarkeit, Umfang und beobachtete Ergebnisse bestimmen die Auswahl; Dateianzahl oder Modell-Selbstvertrauen reichen nicht.
+4. Günstiger Erstversuch nur bei geeigneten Aufgaben; Abnahme, begrenzte Reparatur, dann Eskalation mit Patch und Fehlerbelegen. Wiederholte Fehler erkennen. Erwartete Gesamtkosten inklusive Eskalation optimieren.
+5. Aufgabenbezogene Kontextpakete: Ziel, Kriterien, Symbole, Verträge, Tests und relevante Entscheidungen. Weitere Informationen bei Bedarf abrufen; Parent-Historie nicht standardmäßig kopieren.
+6. Gemeinsame Exploration/Indexierung wiederverwenden und per Codezustand/Dateihash invalidieren. Keine vier identischen Repository-Erkundungen durch vier Worker.
+7. Stabile Prompt-Präfixe, passende Modellkontinuität, gemessene Cache-Treffer. Caching reduziert nicht automatisch logischen Kontext; keine Cache-Übernahme zwischen Anbietern annehmen. CLI- und API-Fähigkeiten unterscheiden.
+8. Parallelität nach Abhängigkeiten, Schreibbereichen, kritischem Pfad und Ressourcen. Schnittstellen zuerst; danach unabhängige Implementierung. Ein gemeinsames Limit für Yoke-Worker und native Subagenten.
+9. Prüfungen stufenweise: schnelle deterministische Prüfungen, betroffene Tests, Integration, semantisches Review, erforderliche Gesamtprüfung. Ergebnisse nur bei passenden Code-/Umgebungs-/Konfigurationsständen wiederverwenden.
+10. Kleine verwandte Aufgaben bündeln; sichere Build-/Paket-Caches und vorbereitete Umgebungen nutzen. Veränderliche Worker-Arbeitsstände getrennt halten.
+11. Später direkte Modellaufrufe für eng begrenzte Klassifikation/Umformung erwägen, wenn CLI-Start unverhältnismäßig ist. Separate API-Abrechnung berücksichtigen.
+12. Vollständige Telemetrie für alle Rollen; unbekannte Nutzung niemals als gemessene Null darstellen.
+
+Reihenfolge vorgeschlagen: Messung, deterministische Aktionen/Router, Kontextpakete, Eskalation, besserer Scheduler, inkrementelle Prüfungen und Cache-Optimierung.
+
+## Zeitschätzungen: neuer Schwerpunkt
+
+### Heutiger Codebefund
+
+src/loop/reporter.ts speichert bis zu 50 Story-Laufzeiten in .yoke/story-durations.json. Die ETA ist der arithmetische Durchschnitt abgeschlossener Stories multipliziert mit der Anzahl verbleibender Stories. Aktuelle Run-Dauern ersetzen die ältere Historie bereits nach dem ersten Abschluss. Gespeicherte StoryDuration enthält nur storyId und ms. Diese Formel berücksichtigt weder individuelle Aufgabengröße noch Modell, Ressourcen oder parallelen kritischen Pfad. Die Aussage bezieht sich auf diese ETA-Implementierung; nicht jede Parallelansicht wurde gesondert vermessen.
+
+### Vorgeschlagene Verbesserung
+
+- Exakte vergangene Dauer messen; zukünftige Dauer als Schätzung mit Unsicherheit anzeigen. Keine sekundengenaue Vorhersage versprechen.
+- Phasen getrennt erfassen: Warteschlange, Kontext/Setup, Implementierung, Tests, Review, Reparatur, Integration. Aktive Ausführungszeit, Wartezeit und menschliche Blockade auseinanderhalten.
+- Alle Versuche inklusive Fehlern und Abbrüchen erfassen; nur erfolgreiche Story-Dauern würden Wiederholungsaufwand unterschätzen.
+- Vergleichbare Aufgaben nach Typ, Scope, Testumfang, Provider, tatsächlichem Modell, Effort, Umgebung und Parallelitätsgrad gruppieren. Mit wenigen Daten robuste gemeinsame Basis verwenden statt überfeine Gruppen.
+- Historie und neue Beobachtungen gewichten; ein einzelner schneller Abschluss darf nicht die ganze Prognose dominieren.
+- Zunächst Median und empirische Zeitspannen mit Stichprobenzahl; später kalibrierte Quantile, etwa P50/P80, wenn genug Daten vorliegen. Zielabdeckung und Prognosefehler messen.
+- Projekt-ETA aus verbleibenden Aufgaben, Abhängigkeiten, freien Slots, Integrationsengpass und Ressourcen berechnen; weder einfach aufsummieren noch blind durch Workeranzahl teilen.
+- Laufende Aufgaben anhand ihrer aktuellen Phase und verstrichenen Zeit aktualisieren. Wiederholungs-/Reparaturwahrscheinlichkeit und Modellwechsel berücksichtigen.
+- Bei unbekannter Dauer einer Nutzerentscheidung: "wartet auf Entscheidung" und bedingte Restlaufzeit ab Wiederaufnahme; keine erfundene Fertigstellungsuhrzeit.
+- Bei neuer Aufgabe/Modell unbekannte oder schwach gestützte Schätzung sichtbar kennzeichnen; Prognose selbst benötigt nicht zwingend einen LLM-Aufruf.
+- Szenarien anbieten: Zeit/Kosten bei anderer Parallelität oder anderem Modell. Als Prognose ausweisen, nicht als zugesagte Einsparung.
+
+## Dashboard pro Projekt und projektübergreifend
+
+Status: Nutzerinteresse; folgende Ausgestaltung ist ein Vorschlag, noch keine freigegebene Implementierung.
+
+- Lokaler Einstieg, gleiche Datenbasis wie CLI. Zunächst registrierte Projektpfade und lesende Übersicht; kein Cloudkonto als Voraussetzung.
+- Projektübersicht: aktives Ziel, Zustand, abgenommene/offene Kriterien, laufende Worker, Blocker, Zeitspanne bis Abschluss, gemessener Verbrauch und Telemetrielücken.
+- Projektdetail: Task-Liste und Abhängigkeitsansicht, Phasen/Zeitleiste, kritischer Pfad, aktuelle Modelle, Reviews, Fehlerreproduktionen, Artefakte und Integrationsstand.
+- Aufmerksamkeit zuerst: Was braucht eine Entscheidung? Welcher Test blockiert? Welches Projekt ist seit wann still? Warum änderte sich die ETA?
+- Taskdetail: ursprüngliche/aktuelle Schätzung, tatsächliche Phasendauern, Versuchshistorie, Patch, Abnahmen, Kosten und Übergaben.
+- Spätere Steuerung: Pause/Wiederaufnahme, kritische Entscheidung beantworten, Anbieterwechsel am sicheren Übergang, Budget/Parallelität ändern. Existierende Locks und Sicherheitsgrenzen wiederverwenden; UI darf keine zweite Ausführungslogik besitzen.
+- Metriken: Zeit/Kosten pro abgenommener Änderung, Erstversuchserfolg, Eskalationsrate, Nacharbeit, Cache-Anteil, menschliche Eingriffe, Prognosefehler und Zeitspannen-Abdeckung.
+- Zuerst versionierte Ereignisse und vollständige Messung schaffen, dann Dashboard. Vorhandene loop-status.json, loop.log, Story-Dauern und Routing-Ereignisse sind Bausteine, aber noch keine vollständige projektübergreifende Ereignishistorie.
+- Telemetrie standardmäßig lokal; externe Team-/Cloudfunktion und Datenumfang später ausdrücklich entwerfen.
+
+## Empfohlene Produktabfolge
+
+1. Fehlerbehandlung und Provider-Parität stabilisieren; vollständige Ereignisse/Verbrauch/Dauern.
+2. Nützlichen yoke-check-Einstieg aus Review, Verify und Smoke entwickeln.
+3. Geschützte Abnahmen, kontrollierte Reparatur, Wiederaufnahme und Anbieterwechsel.
+4. Zeitprognosen und lesendes Projektdashboard auf derselben Ereignisbasis; anschließend gezielte Steuerung.
+5. Gemeinsames Zielmodell und Team-/CI-Berichte ausbauen; Optimierungen durch Vergleichsläufe validieren.
+
+Nicht bereits beschlossen: UI-Technologie, Cloudhosting, API-Providerpreise, konkrete Modellrangliste, genauer Releaseumfang, verbindlicher Zeitplan, bezahltes Produkt oder vollständige Umsetzung aller Vorschläge.
+
+## Quellen und Wiederaufnahme
+
+### Umsetzungsstand nach Freigabe
+
+Der Nutzer hat anschließend ausdrücklich „ok setze alles akribisch und sicher um“ beauftragt. Die lokale Umsetzung umfasst jetzt unabhängige Checks, geschützte ausführbare Abnahmen, dauerhafte Ziele mit Anbieterwechsel und Verbrauchsgrenzen, sichere serielle Worktree-Wiederaufnahme, Gemini-Adapterkorrekturen, Ereignisse und empirische Zeitspannen, feste Routingregeln mit Eskalation, modellfreie Werkzeugaufgaben, begrenzte kontextbezogene Prompts, deklarierte Schreibbereiche und ein lokales Projektdashboard. Bedienung und Grenzen: [VERIFIED-PROJECTS.md](VERIFIED-PROJECTS.md).
+
+Weiterhin offen sind externe Nutzer-/Wettbewerbsversuche, authentifizierte Modellvergleiche, belastbare Kalibrierung der Zeitprognosen und kommerzielle/Cloud-Entscheidungen. Selektive Testwiederverwendung und webbasierter Start/Resume sind bewusst keine behaupteten Fähigkeiten dieses lokalen Ausbaus. Qualitätskontrollen werden vollständig ausgeführt. Die ursprünglichen Produktthesen bleiben als solche dokumentiert.
+
+Lokale Anker: src/agents/providers.ts, src/agents/telemetry.ts, src/retrofit/planners/, src/loop/loop.ts, src/loop/git.ts, src/loop/runner.ts, src/loop/reporter.ts, src/loop/scheduler.ts, src/routing/router.ts, src/routing/registry.ts, src/context/context.ts, src/smoke/command.ts, src/scan/design.ts, bench/RESULTS.md.
+
+Am 2026-09-05 gelesene Primärquellen; vor konkreten Versions-/Preisentscheidungen erneut prüfen:
+
+- https://learn.chatgpt.com/use-cases/follow-goals
+- https://learn.chatgpt.com/docs/agent-configuration/subagents
+- https://developers.openai.com/api/docs/guides/latency-optimization
+- https://developers.openai.com/api/docs/guides/prompt-caching
+- https://code.claude.com/docs/en/cli-reference
+- https://code.claude.com/docs/en/agent-teams
+- https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
+- https://geminicli.com/docs/cli/headless/
+- https://geminicli.com/docs/hooks/reference/
+- https://ai.google.dev/gemini-api/docs/caching
+- https://github.com/obra/superpowers
+- https://github.com/garrytan/gstack
+- https://github.com/open-gsd/gsd-core
+
+Provenienz der ursprünglichen README-Prüfung: kein C2PA gefunden, unterstützter Scan vollständig, Verifikation/Vertrauen/Metadatenprivatsphäre unbekannt. Unicode-Befund: Emoji-Variationszeichen, kein Nachweis eines KI-Wasserzeichens. Proprietäre Wasserzeichen nicht überprüfbar. Dieses Gesprächsdokument wurde vom KI-Assistenten aus der Sitzung zusammengefasst; es enthält keine unabhängige Bestätigung der Produktthesen.

package/docs/PUBLISHING.md

@@ -6,7 +6,7 @@ Where Yoke is published, and how each channel gets updated. (Reviewed 2026-08-20
 
 | Channel | How | Update path |
 |---|---|---|
-| **npm** — [`@hecer/yoke`](https://www.npmjs.com/package/@hecer/yoke) | `npm publish` (2FA) | every release |
+| **npm** — [`@hecer/yoke`](https://www.npmjs.com/package/@hecer/yoke) | GitHub OIDC trusted publishing | every release |
 | **GitHub** — [HECer/yoke](https://github.com/HECer/yoke) | push + tag + GitHub Release | every release |
 | **Claude Code plugin (self-marketplace)** | `.claude-plugin/plugin.json` + `marketplace.json` in this repo; users: `/plugin marketplace add HECer/yoke` → `/plugin install yoke@yoke` | bump `version` in `plugin.json` |
 | **Gemini CLI extension** | `gemini-extension.json` + `GEMINI-EXTENSION.md` at repo root; users: `gemini extensions install https://github.com/HECer/yoke` | bump `version` in the manifest |
@@ -33,7 +33,7 @@ release object is created. Use this idempotent check after the version commit re
 
 ```bash
 set -euo pipefail
-VERSION=1.6.1
+VERSION=1.6.2
 TARGET=$(git rev-parse HEAD)
 git fetch --tags origin
 
@@ -62,6 +62,29 @@ gh release view "v$VERSION" >/dev/null 2>&1 || \
 Verify both surfaces before publishing npm: `gh release view "v$VERSION"` and
 `npm view @hecer/yoke version`.
 
+## npm trusted publishing
+
+The `publish-npm.yml` workflow publishes a stable package automatically when a GitHub Release is
+published. It checks out that exact tag, requires the tag to match the version in `package.json`,
+reruns `prepublishOnly` through `npm publish`, and skips a version that already exists. GitHub OIDC
+provides a short-lived publishing identity; no `NPM_TOKEN` repository secret is used. npm adds
+provenance automatically for this public repository.
+
+One package-owner setup step is required on npmjs.com under the `@hecer/yoke` package settings:
+
+- Publisher: GitHub Actions
+- Organization or user: `HECer`
+- Repository: `yoke`
+- Workflow filename: `publish-npm.yml`
+- Environment: leave empty
+- Allowed action: `npm publish`
+
+After the trusted publisher exists, the next GitHub Release publishes automatically. To publish an
+already-created release such as `v1.6.1`, run the **Publish npm** workflow manually and provide that
+existing tag. The workflow refuses tags without a published GitHub Release and refuses tag/version
+mismatches. After the first successful OIDC publish, disable traditional token publishing and revoke
+obsolete automation tokens in npm package settings.
+
 ## Submitted / pending
 
 | Channel | How | Status |

package/docs/VERIFIED-PROJECTS-VALIDATION.md

@@ -0,0 +1,29 @@
+# Local implementation validation
+
+This record covers the September 5, 2026 source implementation, not a published release or a competitive benchmark.
+
+## Review and behavioral checks
+
+Independent specification and code-quality reviews identified and drove fixes for mutable acceptance, stale goal success, lost interrupted-attempt accounting, orphaned processes, incomplete workspace identity, missing final protection gates, restart-lost routing escalation, unnecessary provider installation requirements, mixed time accounting, partial cost reporting and linked pause files.
+
+Behavioral regressions cover protected checks, source mutation during verification, truthful unmapped requirements, goal completion from real application changes, tampered tests, bounded retries, interruption recovery, source-bound worktree continuation, routing without controller calls, persisted escalation, deterministic actions, context budgets, dependency/write-scope scheduling, unknown estimates, phase/attempt evidence, local registry and HTTP security boundaries.
+
+Final full suite: **122 test files passed; 1,098 tests passed, 2 skipped (1,100 total)** with a 20-second test timeout on Windows. This timeout accommodates the real-Git integration tests; the earlier baseline already had a 5-second timeout that passed in isolation. TypeScript build/lint, canon validation, release-metadata check and package dry run passed. The package check explicitly confirmed the compiled CLI, check/goal/dashboard modules and Gemini RTK hook are included.
+
+## Browser and provider limits
+
+The local dashboard was rendered and inspected in Chrome on desktop and at 390px mobile width. HTTP tests exercise registered project reads, corrupt/missing/oversized data, hostile Host/Origin headers, token rejection and authorized pause. Browser extension click automation timed out, so a complete interactive click walkthrough is not claimed.
+
+Provider invocation/stream/parser/hook tests are local automated tests. No authenticated cross-provider development benchmark was run. Model quality parity, price superiority, exact deadline prediction and achieved real-project token savings remain unmeasured. Native structured-output adapter support does not imply a provider-native goal API.
+
+## Provenance
+
+Read-only `audit-provenance` scans covered README, the new usage guide and dashboard page source. No supported C2PA structure was found; supported scans completed. README Unicode findings were emoji variation selectors, not evidence of a model watermark. No content or marks were removed.
+
+The audit's unanswered questions remain explicit:
+
+- Verification/trust: “No conforming verifier was supplied.” Cryptographic verification and a named signer trust chain are unknown.
+- Metadata privacy: the text format has no supported metadata parser in this analyzer; no privacy conclusion was produced.
+- Proprietary watermark detection: “Keyed model-level watermarks cannot be checked without the provider's key.” No authorship inference follows from absence of detected marks.
+
+The documentation and implementation were prepared with AI assistance and reviewed/tested as described above.

package/docs/VERIFIED-PROJECTS.md

@@ -0,0 +1,147 @@
+# Verified projects, goals and measured execution
+
+Available in Yoke 1.7.0. These additions do not require a cloud account or replace your provider CLI. Model availability, reasoning controls, structured output and telemetry depend on the selected provider; unknown usage is never a measured zero. Live authenticated provider comparison and calibrated time/cost benchmarks remain separate validation work.
+
+## Check an existing project
+
+```sh
+yoke check .
+yoke check . --json
+yoke check . --requirement="Guest checkout completes"
+```
+
+Checks run without retrofit. Exit codes: `0` passed, `1` failed, `2` unverified or unavailable. A free-text requirement stays unverified until you map its behavior to an executable acceptance contract. Passing a project suite does not establish arbitrary product correctness.
+
+Create `.yoke/acceptance.yaml` with tests that inspect application behavior:
+
+```yaml
+version: 1
+protected:
+  - tests/acceptance/checkout.test.mjs
+  - tests/acceptance/helpers.mjs
+criteria:
+  - id: guest-checkout
+    text: A guest can complete checkout and receives one order confirmation.
+    commands:
+      - node --test tests/acceptance/checkout.test.mjs
+```
+
+List every local test helper, fixture and configuration file whose modification could weaken this contract. Paths must resolve inside the project. `yoke check . --protect` pins the manifest, listed files and existing package manifests/lockfiles outside the worker checkout. Autonomous goals require explicit protected test infrastructure and establish this pin automatically. Protection is change detection within the local execution model, not an OS security boundary against a hostile process using your account. Review the contract before running a goal.
+
+After intentionally editing protected tests, use `yoke check . --protect --refresh` to approve the new baseline. Ordinary checks and retries never refresh it. Source, acceptance and configuration identity are checked before and after verification; changed inputs invalidate evidence. Gitlinks/submodule directories currently fail closed because recursive identity is not implemented. Evidence is stored in `.yoke/checks/<id>.json`; it describes that checked snapshot and is not a permanent success certificate.
+
+## Durable goals across providers
+
+```sh
+yoke goal set . --objective="Finish guest checkout" --attempts=3 --minutes=30
+yoke goal run . --runner=codex
+yoke goal resume . --runner=claude --model=<installed-model-id>
+yoke goal resume . --runner=gemini --model=<installed-model-id>
+yoke goal status .
+yoke goal handoff .
+yoke goal pause .
+```
+
+Goals keep objective, attempts, failure context and check IDs in `.yoke/goal.json`. They share the story-loop lock. Each implementation attempt is followed by independent executable acceptance. A completed goal is checked again on a later run. Failed work stays in the project; goal execution itself does not commit or publish it. Goal handoff is readable context for native agent goal facilities; Yoke does not invent or call an undocumented native goal API.
+
+`--minutes` limits cumulative agent execution time. Verification is measured separately and commands retain their verification timeout. `--tokens=N` is a checkpoint budget: it prevents another attempt when measured consumption is exhausted or unknown, but cannot promise a hard token cap within a single provider call. An interrupted attempt is persisted before dispatch; recovery accounts for it conservatively and reconciles recorded provider processes before continuing. Unknown process ownership blocks execution. Pause takes effect at an attempt boundary; it does not instantly kill an in-flight agent.
+
+Explicitly extend total budgets without deleting history:
+
+```sh
+yoke goal budget . --attempts=5 --minutes=60
+yoke goal budget . --tokens=200000
+# Only if you deliberately want to remove the checkpoint token limit:
+yoke goal budget . --clear-token-budget
+```
+
+Unknown historical token usage cannot be made known by increasing its limit. Inspect interrupted work and keep that limitation visible.
+
+## Recover an isolated story
+
+Failed or paused isolated story worktrees are retained. Resume the same story with:
+
+```sh
+yoke loop run . --isolate --resume-worktree --parallel=1 --candidates=1
+```
+
+Yoke validates the registered worktree, repository, original target commit and PRD digest. Changed target/PRD state is refused; inspect retained edits and reconcile deliberately. This flag is for serial isolated recovery; parallel workers retain their existing coordinator lifecycle. `yoke loop cleanup` remains an explicit cleanup operation; inspect its removal flags before discarding unfinished work. Existing projects should rerun retrofit to add ignore entries for checks, events and goals.
+
+## Spend fewer model calls
+
+Add explicit project rules to `.yoke/config.yaml`:
+
+```yaml
+routing:
+  enabled: true
+  strategy: cost
+  maxCandidates: 2
+  workers:
+    - id: fast
+      agent: claude
+      model: <your-fast-model-id>
+      costTier: low
+      capabilities: [docs, tests]
+    - id: strong
+      agent: codex
+      model: <your-strong-model-id>
+      costTier: high
+      capabilities: [implementation]
+  rules:
+    - area: docs
+      worker: fast
+      escalateTo: strong
+```
+
+The first matching rule bypasses the routing controller. Its optional area and story ID selectors both have to match when supplied. Independent gate failure escalates the next attempt, including after loop restart; an unavailable or unknown worker falls back to the parent. Without an explicit escalation target the parent handles the failed rule. Other stories retain adaptive routing. Gate-driven routing observations are local and bounded when read. These are measured outcomes, not guarantees that a named inexpensive model can handle every task.
+
+For deterministic operations, configure exact executable arguments:
+
+```yaml
+actions:
+  - storyId: regenerate-types
+    file: node
+    args: [scripts/generate-types.mjs]
+    timeoutMs: 60000
+```
+
+Actions use no model, run without a shell, have bounded output/time and still pass the ordinary story gates before commit. They currently require serial execution with one candidate. On Windows use an executable such as `node` and its script path; shell-only `.cmd` wrappers are not automatically enabled. Commands are project-authored configuration, never free-form model-generated commands. Projects consisting entirely of configured actions do not need a model CLI unless they enable a model-based review or planning workflow.
+
+Implementation/review prompts now select task-relevant project context deterministically within a 6,000-character budget. A stable project/glossary prefix precedes ranked historical references with source paths and content hashes. Excerpts point back to complete files. This does not claim a fixed token count or guaranteed provider cache hit. Mandatory verification always reruns; no broad result cache or selective-test bypass was introduced.
+
+## Parallelism and time estimates
+
+Stories can declare relative file/directory scopes:
+
+```yaml
+- id: api-types
+  title: Update API types
+  priority: 1
+  area: api
+  writes: [src/api, tests/api]
+  needs: []
+  acceptance: ["Replace with executable structured criteria in strict projects"]
+  passes: false
+```
+
+Overlapping declared scopes cannot run simultaneously, including while integration is pending. Dependencies, areas, explicit priorities and concurrency limits also apply. Equal-priority work that unlocks a longer dependency chain is scheduled first. Declarations are advisory scheduling input, not filesystem write enforcement; absent declarations preserve previous behavior. Final integrated gates remain mandatory.
+
+Versioned local events record status, phase duration, attempts and available usage. Retention is bounded to 1,000 events. Estimates combine historical and current durations, preserve failed-attempt cost and expose sample counts and empirical ranges. Schedule estimates simulate dependency, scope and concurrency constraints. Predictions and later errors are attached to completed attempt events so accuracy can be evaluated. Ranges describe observed data; they are not calibrated probabilities or exact deadlines. No history means no justified time estimate.
+
+## Local project dashboard
+
+```sh
+yoke projects add /path/to/project
+yoke projects list
+yoke dashboard .
+yoke dashboard --no-register --port=4100
+yoke projects remove <opaque-project-id>
+```
+
+Open the printed loopback URL. The dashboard displays project goals, backlog, worker/status data, evidence, blockers, events, usage availability and schedule ranges. It can request a goal pause through the same service as the CLI. Start, resume and budget changes remain explicit CLI operations. Removing registration only removes the registry reference.
+
+The HTTP service binds to `127.0.0.1`, validates Host/Origin, requires a per-session token for pause, sends a restrictive CSP and renders project strings as text. It does not serve arbitrary local files or allow remote registration. Missing/corrupt/oversized project data is shown as unavailable. Shared project registration and protected acceptance live under `YOKE_STATE_DIR` or `~/.yoke/state`; existing routing history retains its `YOKE_REGISTRY_DIR` location. The dashboard is local, not a hosted multi-user service.
+
+## Remaining validation and product work
+
+Live Codex/Claude/Gemini comparisons, measured competitive development-time/cost studies and estimate calibration require representative real projects and authenticated runs. Equal adapter contracts do not imply equal model capability. Cloud/team access, automatic selective test reuse, web-based start/resume controls and commercial rollout are not included in this local foundation. The complete saved direction is in [PRODUCT-DIRECTION-2026-09-05.md](PRODUCT-DIRECTION-2026-09-05.md).

package/docs/superpowers/plans/2026-09-05-verified-projects.md

@@ -0,0 +1,83 @@
+# Verified projects implementation plan
+
+> **For agentic workers:** Use superpowers:subagent-driven-development for bounded implementation and independent spec and quality reviews. User authorized implementation on 2026-09-05; no additional planning approval is required.
+
+**Goal:** Deliver reliable cross-provider acceptance and continuation, measured execution with useful time estimates, efficient routing, and a local dashboard over a shared project state.
+
+**Architecture:** Preserve existing CLI behavior unless a safety defect requires correction. Add small services for checks, goals, events, estimates, project registration and dashboard presentation. Provider capabilities stay in adapters; dashboard calls the same services as the CLI. Unknown measurements remain unknown.
+
+**Tech Stack:** Existing TypeScript, Node built-ins, Zod, YAML and Vitest. Local HTTP dashboard with no runtime UI dependency. Existing CLI processes remain the coding executors.
+
+## Scope and acceptance
+
+The user approved the saved product direction. Implementation includes the concrete developer-tool capabilities; market validation with ten external users, commercial pricing, cloud hosting, promises of model equivalence and guaranteed time/cost savings are not software deliverables. Provider-native features must use verified supported interfaces; no invented goal protocol or provider prices.
+
+## Task 1: Provider contracts and hooks
+
+Files: src/agents/providers.ts, contracts/types/telemetry as necessary, src/retrofit/planners/gemini.ts, canon/tools/gemini-rtk-hook.mjs, focused provider/retrofit tests.
+
+- [x] Write failing tests for Gemini streaming and model telemetry, unsupported selection handling, and BeforeTool command rewriting.
+- [x] Run the focused tests and inspect the expected failures.
+- [x] Add capability-aware invocation, reliable Gemini stream output and hook wiring. Retain safe/read-only profiles, validate native structured-output options where supported.
+- [x] Run provider, process and retrofit tests plus TypeScript checks.
+- [x] Independent spec review, then quality review; address findings.
+
+## Task 2: Durable recovery and acceptance
+
+Files: src/loop/loop.ts, src/loop/runner.ts, new src/check/ and src/goals/ modules, src/cli.ts, focused tests.
+
+- [x] Reproduce lost failed worktrees and untracked reviewer mutations before changing production code.
+- [x] Retain failed isolated work; allow intentional resume with branch/PRD identity validation. Fingerprint file content and fail closed on read failures.
+- [x] Add yoke check that runs configured or detected verification without retrofit, reports passed/failed/unverified criteria and binds evidence to checked content.
+- [x] Add protected-file verification and bounded repair/continuation with explicit provider selection; never silently accept changed acceptance infrastructure.
+- [x] Add durable goals and handoff state, exposing native-agent-readable instructions instead of assuming unsupported APIs.
+- [x] Test dirty trees, failed commands, stale evidence, missing configuration, changed protected files and recovery.
+
+## Task 3: Measurement and estimates
+
+Files: new src/observability/events.ts, src/estimation/, src/loop/reporter.ts, focused tests.
+
+- [x] Test event validation, partial history, failed attempts, phase accounting and low-sample estimates.
+- [x] Persist bounded versioned local events and preserve explicit measurement availability.
+- [x] Combine historical and current durations robustly; expose empirical bounds and sample count.
+- [x] Estimate dependency-constrained schedules and active work without naive division by concurrency.
+- [x] Connect serial/parallel status to a common read model and expose estimate accuracy records.
+
+## Task 4: Efficient execution
+
+Files: src/routing/, src/context/, src/loop/scheduler.ts, configuration/schema and focused tests.
+
+- [x] Test explicit deterministic routes, safe fallback and gate-driven escalation.
+- [x] Add explicit rule-based routing to bypass unnecessary controller calls; support bounded configured tool actions and worker escalation.
+- [x] Select relevant context within a stable prefix and content budget with source references.
+- [x] Respect task write scopes, dependency priority and configured concurrency constraints.
+- [x] Keep mandatory final checks; reuse only evidence with matching inputs and surface cache/usage gaps.
+
+## Task 5: Project dashboard and shared commands
+
+Files: new src/projects/, src/dashboard/, src/cli.ts, tests/projects/, tests/dashboard/.
+
+- [x] Test project registration, corrupt/missing projects, task views and HTTP boundaries.
+- [x] Add local project register/list/remove and shared state snapshots for goals, criteria, workers, events, estimates and consumption.
+- [x] Serve a responsive dashboard on loopback only with escaped text, restrictive CSP, validated Host/Origin and opaque project IDs. Never expose arbitrary file paths as HTTP reads.
+- [x] Provide overview, project and task details, blockers, evidence and time/cost uncertainty. Mutating controls reuse existing command boundaries and require local-session protection.
+- [x] Verify actual HTTP responses and browser rendering, empty/error states and navigation.
+
+## Task 6: Integration and documentation
+
+- [x] Reconcile README claims with activation and evidence requirements; document migration and all new commands.
+- [x] Update release metadata through the repository script.
+- [x] Run lint, build, full tests, canon validation, docs checks and package dry run.
+- [x] Perform independent spec and code-quality review and fix material findings.
+- [x] Preserve original working-tree changes; provide concrete commands and remaining external verification limits.
+
+## Verification commands
+
+All shell calls use RTK per user instruction. Focused checks use `rtk proxy npx vitest run <test files>`. Final checks use npm scripts from package.json and `rtk proxy npx tsx src/cli.ts validate canon`. Behavioral tests must fail for the intended missing behavior before implementation. Do not call live models across user repositories for a synthetic dashboard demo.
+
+## Execution record
+
+- Baseline was audited earlier in this session: 1018 passed, 2 skipped, one 5-second integration-test timeout; isolated rerun passed. TypeScript and docs check passed. Work continues under the user's explicit instruction to implement and fix the recorded issues.
+- Worktree: .worktrees/yoke-next, branch feature/verified-projects. Existing dependencies reused via junction; original user changes remain outside this worktree.
+- Final verification: 122 files passed, 1098 tests passed and 2 platform skips. Build, typecheck, canon, docs metadata and package contents passed. Independent reviews and desktop/mobile browser inspection completed within the limits recorded in docs/VERIFIED-PROJECTS-VALIDATION.md.
+- Scope clarification: mandatory final checks always rerun; no selective-result cache was added. Dashboard mutations are limited to shared-service pause; run/resume/budget stay CLI actions. Native provider goal integration is a supported handoff, not an invented API. Empirical prediction errors are recorded; live model/competition benchmarks and calibrated deadlines remain external validation.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "yoke",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Cross-agent coding harness: 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.6.1",
+  "version": "1.7.0",
   "description": "One harness, three agents, zero trust in \"done\" — cross-agent coding harness for Claude Code, Codex CLI, and Gemini CLI: one skill canon, mechanical safety gates, an autonomous loop with screenshot/video proofs.",
   "type": "module",
   "bin": {