@hecer/yoke 1.20.0 → 1.22.0

package/docs/DELIVERY-JOURNEYS.md

@@ -0,0 +1,199 @@
+# Delivery artifacts and executable user journeys
+
+Use executable acceptance criteria to decide whether a release is ready. A build command shows that an artifact can be produced; a journey checks a specific user interaction. Yoke can now record the relationship between those criteria, named journeys and the exact artifact files present during a check.
+
+The delivery declaration belongs in `.yoke/acceptance.yaml`. Browser smoke steps belong in `.yoke/config.yaml`. Existing smoke flows containing only `name`, `path` and an optional `landmark` continue to work.
+
+## Optional browser steps
+
+`yoke flow-smoke` uses the target project's Playwright installation and its Chromium browser. Start the application or preview server before running the command. Yoke does not start a development server or install a browser automatically.
+
+For example, add this section to the project's existing `.yoke/config.yaml`:
+
+```yaml
+smoke:
+  baseUrl: http://localhost:3000
+  flows:
+    - name: profile-survives-reload
+      path: /login
+      landmark: main
+      timeoutMs: 60000
+      steps:
+        - action: fill
+          selector: '[data-testid="email"]'
+          value: smoke-user@example.invalid
+        - action: fill
+          selector: '[data-testid="password"]'
+          valueEnv: SMOKE_TEST_PASSWORD
+        - action: click
+          selector: '[data-testid="sign-in"]'
+        - action: expect-url
+          url: /profile
+        - action: fill
+          selector: '[data-testid="display-name"]'
+          value: Smoke User
+        - action: press
+          selector: '[data-testid="display-name"]'
+          key: Tab
+        - action: click
+          selector: '[data-testid="save-profile"]'
+        - action: expect-visible
+          selector: '[data-testid="save-confirmation"]'
+        - action: expect-text
+          selector: '[data-testid="save-confirmation"]'
+          text: Profile saved
+          exact: true
+          timeoutMs: 10000
+        - action: reload
+        - action: expect-text
+          selector: '[data-testid="profile-name"]'
+          text: Smoke User
+          exact: true
+```
+
+Supply `SMOKE_TEST_PASSWORD` through the environment using credentials for a dedicated test account, then run:
+
+```sh
+yoke flow-smoke . --label=profile-release
+```
+
+`--url=http://localhost:4173` overrides `smoke.baseUrl`. Flow navigation keeps the existing `baseUrl + path` behavior, so configure their slashes consistently. Each flow gets a fresh browser context with a 1280 × 720 viewport. Steps within one flow share that context; different flows do not share their browser session.
+
+### Supported steps
+
+| Action | Fields | Behavior |
+| --- | --- | --- |
+| `click` | `selector` | Click the matching element using Playwright's action waiting. |
+| `fill` | `selector`, exactly one of `value` or `valueEnv` | Fill a form control with a literal value or a captured environment value. Missing environment values fail the step. |
+| `press` | `selector`, `key` | Press a key, such as `Enter` or `Tab`, on the matching element. |
+| `expect-visible` | `selector` | Wait for the matching element to be visible. |
+| `expect-text` | `selector`, `text`, optional `exact` | Wait for visible text. Whitespace is normalized. Matching is case sensitive and uses a literal substring by default; `exact: true` compares the complete normalized text. |
+| `expect-url` | `url` | Wait for the exact resolved URL. A relative URL resolves against the effective base URL. This is not a glob or regular expression. |
+| `reload` | No additional action fields | Reload the page, wait for its load event and reject a non-successful HTTP response. |
+
+Each step may specify `timeoutMs`. Unknown actions and extra action fields are rejected before browser launch. There is no arbitrary JavaScript action, general scripting language, branch or loop. Use a project E2E test command for more complex behavior, multiple pages, downloads, native applications or specialized fixtures.
+
+### Limits and failure behavior
+
+A flow may contain **1–50 steps**. Its default total timeout is **60,000 ms**, with a configurable maximum of **120,000 ms**. This budget includes browser-context preparation, navigation, the optional landmark and all steps. Navigation has its own maximum of 30,000 ms. A landmark has a maximum of 10,000 ms.
+
+A step defaults to **10,000 ms** and may request at most **30,000 ms**. Its actual allowance is capped by the remaining flow budget. Text waiting has both an attempt limit and a deadline. Screenshot capture, context closing and video finalization each have a separate 5,000 ms allowance after interaction ends; browser startup and shutdown also have bounded waits. The flow timeout is therefore not a promise that the whole multi-flow command, including evidence capture and cleanup, ends within that duration.
+
+The first failed step stops the remaining steps of that flow. The report marks them `skipped`. Later flows still run. Non-successful navigation, page errors and error-level console events also fail a flow. A screenshot is required for a passing result. Failure video remains best-effort evidence and does not replace a missing screenshot.
+
+Fill values are limited to 8,192 characters, including values read from the environment. Environment-backed fill values are captured once when the run begins.
+
+## Evidence from a smoke run
+
+Evidence is written to `.yoke/proof/<label>/`:
+
+- A screenshot for each flow where screenshot capture succeeds.
+- A `.webm` video for a failed flow when Playwright can finalize it.
+- `report.json`, a versioned machine-readable report.
+
+The default label is `YOKE_STORY` when present, otherwise `latest`; `--label` takes priority. Labels and filenames are sanitized, and colliding sanitized flow names receive distinct filenames. Running the same label replaces its previous evidence. A run that cannot start because its configuration, browser, source identity or proof location is unavailable does not erase the prior evidence during that preflight.
+
+The report contains:
+
+- Per-flow status, navigation status, optional landmark status and duration.
+- Each configured step's index, action, status, duration and a bounded failure category.
+- Relative screenshot and failure-video filenames.
+- Source fingerprints before and after the run, and whether they match.
+- A digest of the effective smoke configuration, URL override and captured fill inputs.
+- Node version, operating-system platform, architecture, configured viewport, browser version when available and the effective URL's origin.
+
+Raw configuration, selectors, expected text, fill values, environment-variable names and browser exception call logs are not serialized into the report. URL credentials, query strings and fragments are not included in its recorded origin. Driver errors are represented by categories such as `timeout`, `step-failed` or `navigation-failed`, because their original messages can contain form values. Screenshots and video still show what the application visibly displays; use test data appropriate for those visual artifacts.
+
+Exit code `0` means all flows passed, their screenshots were captured, the source fingerprints before and after the run matched and no browser-cleanup failure was reported. Exit code `1` represents a failed run or invalidated evidence. Exit code `2` covers unavailable prerequisites or evidence storage. Invalid step configuration is rejected before browser launch.
+
+The local source fingerprint does **not** prove that a remote server is running that source revision. Arrange the project's preview or deployment checks so the browser exercises the intended build. Record a separate deployment verification criterion when that relationship matters.
+
+## Bind release artifacts and journeys to acceptance criteria
+
+Add an optional `delivery` section to `.yoke/acceptance.yaml`:
+
+```yaml
+version: 1
+protected:
+  - .yoke/config.yaml
+  - playwright.config.ts
+  - tests/e2e/profile.spec.ts
+criteria:
+  - id: profile-e2e
+    text: A signed-in user can save a profile and recover it after reloading.
+    commands:
+      - npm run test:e2e -- tests/e2e/profile.spec.ts
+  - id: profile-smoke
+    text: The release preview completes the configured profile journey.
+    commands:
+      - yoke flow-smoke . --label=profile-release
+delivery:
+  version: 1
+  artifacts:
+    - path: dist/release.zip
+      criteria: [profile-e2e, profile-smoke]
+  journeys:
+    - id: profile-update
+      text: Sign in, change a profile field, save it, reload and observe the saved value.
+      criteria: [profile-e2e, profile-smoke]
+  environment:
+    name: Local release preview with Chromium
+    url: http://localhost:3000
+```
+
+The script names, test files and artifact path in this example must exist in the application project. `delivery.journeys` names the intended user experience and references executable criteria; it does not execute browser steps by itself. The example executes smoke steps through the `profile-smoke` criterion's command.
+
+**Build declared artifacts before starting `yoke check`:**
+
+```sh
+npm run build:release
+# Start the project's preview server for that release in another terminal.
+yoke check . --json
+```
+
+`build:release` here denotes the project's build script that creates `dist/release.zip`. A criterion that creates the declared artifact during `yoke check` is too late: the artifact must already exist for its initial snapshot.
+
+The check report records artifact SHA-256 hashes and sizes before and after the commands. An artifact missing at either snapshot, differing between snapshots or using an unsafe path fails artifact binding. Declared artifacts must be regular project-relative files without symbolic links or path escapes. Explicit artifact hashing also covers ordinary ignored build outputs.
+
+Artifact hashing accepts at most **512 MiB per file**. Each snapshot, before or after verification, has a combined **1 GiB byte budget** and a **10-second deadline**; an earlier enclosing check deadline also applies. Exceeding a limit or cancelling the check prevents a passing binding. Data is streamed in bounded chunks, with deadline and cancellation checks between synchronous reads. An individual blocked filesystem read is not preempted by that deadline. The declaration accepts at most 32 artifacts and 100 named journeys.
+
+Artifact and journey status comes from their referenced criteria. All referenced criteria must pass for a passing status; a failed criterion fails the binding, while an unexecuted criterion remains unverified. Source-integrity, cancellation or artifact-binding problems also prevent a passing delivery result. Unknown criterion IDs and duplicate artifact paths or journey IDs are rejected.
+
+The report labels this relationship **`binding: declared-criteria`**. Matching artifact hashes plus green criteria establish the declared relationship and the same artifact content at both snapshots. This is not continuous monitoring of the file between snapshots. The project command must actually exercise the intended artifact; Yoke cannot infer that a test which ignores its APK, ZIP or binary argument has verified that file.
+
+Protect the acceptance manifest and the test infrastructure with the existing `yoke check . --protect` workflow after reviewing the contract. See [Verified projects](VERIFIED-PROJECTS.md) for protection and intentional-baseline-refresh behavior.
+
+## Android example: verify the built APK on a specified device
+
+A browser journey does not install an APK or validate Android permission handling. Use an application-owned executable test for that task and reference it from acceptance:
+
+```yaml
+version: 1
+protected:
+  - tools/check-apk-install.mjs
+  - tests/android/tracking-fixture.json
+criteria:
+  - id: tracking-installed-apk
+    text: The declared APK installs and completes the tracking fixture on the selected emulator.
+    commands:
+      - node tools/check-apk-install.mjs --apk=android/app/build/outputs/apk/debug/app-debug.apk --serial=emulator-5554
+delivery:
+  version: 1
+  artifacts:
+    - path: android/app/build/outputs/apk/debug/app-debug.apk
+      criteria: [tracking-installed-apk]
+  journeys:
+    - id: record-and-reopen
+      text: Grant the required permission, start tracking, receive fixture GPS points, stop, save and reopen the route after restarting the app.
+      criteria: [tracking-installed-apk]
+  environment:
+    name: Android emulator emulator-5554 with the project's configured system image
+```
+
+`check-apk-install.mjs` and the fixture are **project-supplied tests**, not bundled Yoke commands. The script must install that exact APK, select and verify its device, perform the required permission and tracking actions, inspect the resulting route and process logs, and exit nonzero when an assertion fails. Build the APK first, prepare the emulator, then run `yoke check`.
+
+The declared environment name is metadata. It does not detect the actual emulator image, phone model or OS version. Have the project test verify those properties when they are acceptance requirements. Passing on one emulator does not establish correct background tracking on a particular Vivo phone, and passing against one deployment does not certify every deployment.
+
+## Validation scope
+
+The smoke engine's repository tests use filesystem-backed browser doubles to verify step order, failure handling, timeout budgets, redaction, source/configuration binding and evidence persistence. They do not install browsers or certify an application. Application-level evidence comes from successfully running the configured commands with the project's actual browser, build, server or device.

package/docs/ECONOMIC-ROUTING.md

@@ -0,0 +1,180 @@
+# Measured capability routing
+
+Yoke 1.22 adds optional economic selection to capability routing. It compares
+observed, independently verified execution sequences. It does not assign an
+estimated success probability to a model or assume that a profile labelled
+`low` has the lowest cost of completing a task.
+
+## Configuration and compatibility
+
+```yaml
+routing:
+  enabled: true
+  strategy: capability
+  optimization:
+    version: 1
+    objective: balanced
+    minSamples: 20
+```
+
+This fragment supplements the project's existing routing profiles and limits.
+`minSamples` defaults to 20 and has a minimum of 10. Existing configurations
+without `routing.optimization` retain their previous capability ordering. New
+setup-generated capability configurations enable the conservative `balanced`
+policy; this does not change selection until sufficient comparable measurements
+exist.
+
+The planner's task/risk assessment still determines the minimum capability tier.
+Configured provider constraints, allowed roles, `maxTier`, parent-fallback policy,
+and the existing gate-failure reliability filter remain in force. Economic
+selection only compares profiles that survive those checks. Explicit project
+routing rules retain their precedence.
+
+## What a sample measures
+
+The comparison unit is a bounded **execution sequence for one task contract**,
+attributed to the profile that started it. If a small model needs a targeted
+repair and then escalation to a stronger model, all those measured attempts
+belong to the initial profile's sequence. Charging only the final successful
+model would hide the cost of the failed attempts.
+
+Within a fully accounted execution attempt, the durable call ledger includes:
+
+- The routing/planning call made inside that execution, when one was needed.
+- The implementation call, including reported usage from interrupted calls.
+- Additional reviewer, critic, repair and model-driven quality calls joined by
+  the loop reporter before its final outcome.
+
+Stable call IDs prevent a worker's usage from being counted again when its
+aggregate reaches the reporter. An explicit attempt ID can join a call directly.
+Without one, a role call is joined only if that story has exactly one open
+attempt. Competing candidates make the attribution ambiguous; all affected
+samples become incomplete instead of assigning the bill by guesswork.
+
+The measured scope is `execution-attempt`. It is not the total cost of producing
+or shipping a product. Separately prepared PRD drafts, batch assessments, change
+planning, human work and later operational costs are not amortized into these
+samples. Their separately emitted telemetry remains useful for project-level
+analysis. The duration covers each admitted attempt through its recorded gate
+outcome, summed across the sequence; it does not include idle time between
+separate attempts or a developer's review time.
+
+Only native loop paths with the complete role-accounting contract enable this
+scope. Injected runners/gates and ambiguous candidate races remain `worker`
+scope. Their measurements are still available diagnostically, but cannot supply
+the complete evidence required for economic selection.
+
+## Evidence and missing data
+
+For each eligible starting profile, the router examines its most recent
+`minSamples` comparable sequences. They must share the project, implementation
+role, task-assessment dimensions, effective execution-policy key, requested
+provider/model/effort/variant, and the current reported concrete starting model.
+The policy key binds the effective gate and review configuration, including
+commands and retries. A change to the concrete model starts a new evidence
+window even when its requested alias remains the same.
+
+A sequence is complete only when every reserved attempt has an outcome and the
+sequence has either passed independent gates or exhausted its bounded attempt
+allowance. Every attempt must have known token coverage, complete reported cost,
+the full execution scope, and the same policy key. Infrastructure failures are
+not treated as evidence of model reasoning quality and do not qualify for the
+economic comparison.
+
+One recent unknown or partial sequence keeps its window ineligible. The router
+does not discard that row and search for an older successful subset. Open
+sequence records are replaced by their later completion record, and retries do
+not turn into additional independent samples. The optional observation registry
+uses a 30-day evidence window and reads at most its latest 1,000 events; losing
+economic history leads back to conservative selection.
+
+Unknown usage is distinct from measured zero. Known partial token or dollar
+amounts are retained with incomplete-coverage flags. For example, a fully
+measured worker remains visible when its planner supplied no usage. OpenCode
+and Kilo step summaries require coverage of every completed step before they
+claim complete token totals; absent optional cache or cost fields are not
+converted into measured zeros.
+
+No reported dollars means no cost ranking. Yoke does not invent a bill from
+declared cost tiers, token counts or a presumed provider price table. This can
+leave economic routing at its conservative baseline for providers that do not
+report sufficient telemetry.
+
+## The three objectives
+
+The baseline is the first eligible profile under the existing tier, declared
+cost-tier and profile-ID ordering. Both the baseline and an alternative require
+a complete evidence window. An alternative must have at least as many accepted
+sequences in that equally sized window as the baseline.
+
+The router computes two observed ratios:
+
+```text
+cost per accepted sequence = total measured sequence dollars / accepted sequences
+time per accepted sequence = total measured sequence duration / accepted sequences
+```
+
+The numerators include completed failed sequences and every measured repair or
+escalation in the window. A profile with zero accepted sequences is ineligible.
+
+| Objective | Condition for choosing an alternative |
+| --- | --- |
+| `cost` | Lower observed dollars per accepted sequence, with no lower observed acceptance count. |
+| `speed` | Lower observed duration per accepted sequence, with no lower observed acceptance count. |
+| `balanced` | No higher cost or duration, and at least one strictly lower, with no lower observed acceptance count. |
+
+`balanced` uses this conservative comparison instead of inventing a dollar
+value for a second of runtime. Cost and speed can disagree; use the corresponding
+explicit objective if that tradeoff is intentional. Equal scores preserve the
+existing ordering.
+
+Decision reasons identify the objective, sample count, observed acceptance
+count, and measured ratios. When the baseline lacks enough data, they explain
+the missing evidence and retain its existing ordering. These are observational
+measurements, not calibrated forecasts or statistical confidence guarantees.
+Task mix, repeated correlated failures and changing model behavior can still
+affect the comparison. The minimum window is a conservative product policy,
+not a claim that twenty examples prove superiority.
+
+Reviewer and critic approval frequency is not independent evidence that their
+reviews were good. Economic reordering of those roles therefore remains disabled
+until an independent role-quality measure is available; their risk-based floors
+and explicit model selections continue to apply.
+
+## Persistent attempt admission
+
+Capability routing reserves an attempt before invoking its implementation
+provider. Configured bounded legacy routes use the same account. The account
+is stored under the stable project root, keyed by story and bound task/plan
+contract, and is independent of the optional global observation registry.
+Exclusive immutable reservation files prevent two processes from replacing the
+same slot. An unreadable or unwritable authoritative account blocks admission.
+
+The capability allowance is the smaller of `maxAttempts` and the existing
+tier-dependent bound: five attempts from `light`, four from `standard`, three
+from `strong`, and two from `frontier`. Independent outer loop, goal and local
+retry limits can stop execution sooner. Infrastructure or interrupted attempts
+still occupy their reserved slots, but do not become verified reasoning failures
+that automatically demand a stronger model.
+
+Deleting or filling the optional registry, restarting a runner, or executing in
+another disposable worktree does not restore those slots. Repeated preparation
+or budget refusals before an implementation is admitted do not consume an
+implementation attempt. A planner may itself incur cost before a later worker
+is refused; that paid call is still reported. Goal callers recheck their durable
+budget after planning and before implementation reservation.
+
+A changed task/plan contract has a new account. Resume an unchanged blocked task
+only after inspecting its reason and performing the required replan or explicit
+configuration change. Do not delete authoritative attempt state to disguise
+retries as a new run.
+
+## Validation limits
+
+The release tests use deterministic fake calls and synthetic observations. They
+cover registry write failure and history eviction, restart-safe reservations,
+known partial usage, synchronous/asynchronous provider telemetry, paid early
+blocks, callback/write failures, complete escalation accounting, cold starts,
+model/policy changes and objective selection. They are regression tests for the
+accounting and decision rules, not provider performance benchmarks. No claimed
+cost or speed improvement follows from those test fixtures.

package/docs/GOALS.md

@@ -29,11 +29,44 @@ IDs and executable commands and binds the objective to a digest of the acceptanc
 manifest. It cannot determine whether your tests fully express a free-text request.
 All project acceptance and configured regression checks must still pass.
 
+Each independent check writes its full report, including declared artifact and
+journey evidence. Goal state keeps the check ID in `lastCheck` and its report path
+in `lastCheckEvidencePath`; `goal handoff` includes both. The report binds its
+findings to the checked workspace. Declaring an artifact or journey is not itself
+proof that a criterion passed.
+
 Existing goals without a binding now stop before any model call. Review their tests,
 then explicitly bind them with `yoke goal bind . --criteria=checkout`. Attempts and
 measured consumption remain intact. Changed acceptance infrastructure still requires
 an explicit protection refresh after review; binding never refreshes protected tests.
 
+## Prepare routing explicitly
+
+Capability routing uses the same goal ID, objective and structured executable
+criteria as goal acceptance. It follows the project's `routing.assessmentPolicy`,
+explicit `routing.rules`, profile limits and optional optimization settings.
+
+With `routing.assessmentPolicy: prepared`, first prepare the bound goal:
+
+```sh
+yoke goal assess . --runner=codex
+yoke goal run . --runner=codex
+```
+
+`goal assess` makes at most one read-only planning call and saves its assessment.
+It reuses an existing assessment for the current contract. It does not implement
+the objective or create an implementation attempt. Preparation consumes the same
+durable token and provider-time budgets as execution. The planning provider and
+model follow the project's planning configuration.
+
+The following run reuses that assessment. A missing or stale prepared assessment
+blocks execution before any model call, including when an explicit routing rule
+exists. Changes to the objective, executable criteria, selected runner or approved
+`.yoke/plan.md` invalidate the contract key. Run `goal assess` again after reviewing
+those changes; acceptance changes still require explicit binding and protection
+review. The `on-demand` policy may assess during execution; explicit rules avoid
+the selection-planner call under that policy.
+
 ## Resource and budget controls
 
 Goals and story loops share the project lock and the user-level worker pool. Routing
@@ -41,24 +74,45 @@ planner and implementation calls each acquire a permit; native model delegation
 disabled. Explicit runner/model/effort/bare options override project runner defaults.
 Execution uses Yoke's safe permission profile.
 
+Runner defaults apply only to the provider that owns them. For example,
+`--runner=claude` does not inherit a Codex model, effort, provider, variant or bare
+setting from `runner`. Explicit command options still apply; when keeping the same
+runner, omitted options retain its configured defaults.
+
 | Setting | Meaning |
 | --- | --- |
 | `--attempts=N` on `set` or `budget` | Maximum cumulative attempts, default 3 |
 | `--minutes=N` | Cumulative admitted provider work, default 30 minutes; excludes capacity waits and independent checks |
 | `--wall-minutes=N` | Optional cumulative run time including admission, checks and state synchronization |
-| `--tokens=N` | Cumulative measured input + output tokens; unknown consumption stops further budgeted work |
+| `--tokens=N` | Cumulative measured input + output tokens, checked before every planning and implementation call; unknown consumption stops further budgeted work |
 | `YOKE_MAX_PARALLEL_WORKERS=1..8` | Shared model/integration permit ceiling, default 3 |
 | `YOKE_MAX_PARALLEL_CHECKS=1..8` | Separate shared asynchronous goal verification ceiling, default 1 |
 
+Planner consumption is persisted before admitting its implementation worker. If
+planning reaches the ceiling, overruns it, or leaves usage unknown, no next model
+call is admitted. A completed objective exactly at its measured ceiling may finish;
+the same balance cannot authorize another model call. Native Codex receives only
+the remaining token allowance after earlier planning and implementation calls.
+
 After a measured token overrun, Yoke retains evidence and work and reports `blocked`
 even if acceptance passed. Update the budget explicitly with `yoke goal budget .
 --tokens=50000`; `--clear-token-budget` explicitly removes that ceiling. Providers
-reporting usage only after a call cannot provide a hard mid-call token cap. Native
+reporting usage only after a call cannot provide a hard mid-call token cap. This is
+a call-admission limit plus cancellation where telemetry permits it. Native
 Codex usage units and Yoke's token accounting are recorded separately. Native
 stream updates use cumulative turn deltas and request cancellation when measured
 consumption exceeds the goal ceiling. Notifications arrive after model requests,
 so this can still overshoot within a request; progress updates are never added
-twice to persisted final usage.
+twice to persisted final usage. Partial counts remain a known lower bound, with
+incomplete measurement explicitly recorded. Raising a token ceiling does not make
+unknown consumption known; explicitly removing the ceiling is a separate decision.
+
+The goal's `usageLedger` records each call before dispatch, then records its final
+usage and duration. Recovery retains finished planner calls and marks unfinished
+calls as interrupted with unknown final usage. Each call has a stable ID and its
+own usage event; attempt summaries are not emitted again as additional token usage.
+Earlier goal files retain their existing attempt totals once, and new calls are
+charged separately. Preparation and resume never reset the previous consumption.
 
 The asynchronous goal checker can interrupt its own command tree at a deadline or
 pause. Synchronous `yoke check` and story gates retain their existing execution
@@ -78,7 +132,10 @@ Or set `goals.nativeCodex: true` in `.yoke/config.yaml`. The default is off;
 Yoke negotiates the local Codex app-server goal capability, stores the thread binding,
 pauses native automatic continuation, and explicitly starts one bounded development
 turn. The same thread resumes on later attempts. Only Yoke's independent acceptance
-can synchronize it to `complete`. Provider/model changes create a new binding.
+can synchronize it to `complete`. Provider/model changes detach the previous binding
+and retain it in `detachedNativeBindings`. A later Codex execution creates a binding
+for the selected model; a goal finished by another provider does not need the old
+Codex runtime to synchronize a historical thread.
 An unsupported native goal method falls back to ordinary Codex execution; authentication,
 transport and execution failures remain visible. No global Codex configuration changes
 are needed. Support depends on the installed CLI, not on the model name alone.

package/docs/RELEASE-VALIDATION-1.22.0.md

@@ -0,0 +1,115 @@
+# Yoke 1.22.0 validation — 2026-10-03
+
+Implementation was based on `f2d9180f4e72afe79c9930c62625874d734db3c6`
+(1.21.1). Parallel implementation and independent reviews covered routing and
+telemetry, goals, worker recovery, Code Intelligence, benchmark provenance and
+delivery evidence. This record separates deterministic regression evidence from
+provider performance or publication claims.
+
+## Local release gates
+
+Environment: Linux, Node.js **24.19.0**, npm **11.9.0**.
+
+| Gate | Result |
+| --- | --- |
+| Baseline before changes | 1,426 tests in 156 files passed. |
+| `npm run prepublishOnly` | Passed: lint, build, complete test suite, README metadata and package dry-run. |
+| Complete corrected suite | **1,610 tests in 177 files passed**, no skipped tests; 63.75 seconds in this run. |
+| Canon validation | Passed with `node --import tsx src/cli.ts validate canon`. |
+| Dependency audit | `npm audit --audit-level=high`: **0 vulnerabilities**. |
+| Whitespace validation | `git diff --check` passed. |
+| Tarball installation | Passed in a fresh prefix with lifecycle scripts disabled: installed binary starts and validates its packaged Canon. |
+| Package contents | 376 files; all five packaged version manifests report 1.22.0; new runtime modules are included, with no root test suite, dependency tree or `.yoke` runtime state. |
+
+The usual `npm run yoke -- validate canon` wrapper was blocked by this host's
+restriction on the tsx CLI's local IPC socket (`EPERM`). Loading the same source
+CLI through Node's tsx import hook passed. No project permission or verification
+policy was weakened to accommodate that environment restriction.
+
+The first integrated runs exposed issues added during concurrent implementation;
+the corrected final suite above passed. A registry-eviction test additionally
+needed an explicit clock advance: equal-millisecond event filenames have UUID
+tie ordering, so wall-clock timing could leave an older observation in its
+fixture. The test now establishes eviction deterministically and still verifies
+that the independent durable attempt account remains exhausted.
+
+The first GitHub matrix passed both Linux jobs and exposed a Windows-only fixture
+issue in the new recovery tests. Windows TEMP can use a DOS short-name alias while
+recovery intentionally persists canonical paths. The JavaScript `realpathSync`
+implementation can retain that alias, so an initial fixture correction was
+insufficient. Both fixtures now use `realpathSync.native`, matching recovery's
+handle-based resolution, before asserting exact ownership paths. Production
+recovery validation remains unchanged. The full matrix is rerun on that correction.
+
+## Regressions covered
+
+- Durable implementation admission across restarts, registry write failures and
+  eviction of more than 1,000 optional observations; concurrent reservations and
+  interrupted attempts retain their spent slots.
+- Per-call goal budget checks before dispatch, planning consumption before worker
+  admission, native/ordinary provider selection and complete or partial usage
+  through failure paths.
+- Stable usage IDs, reviewer/critic/repair joins, partial provider telemetry and
+  dashboard aggregates that preserve known child calls.
+- Economic selection of comparable complete execution sequences, including
+  failed attempts and escalation, model/policy changes, cold starts, missing
+  costs and all three objectives. Synthetic observations test the decision
+  rules; they do not measure model superiority.
+- Real temporary Git repositories for incomplete-worker recovery and candidate
+  retention. Pause, cancellation, failed gates and selection errors preserve
+  work; ownership, contract, base and repository validation guard reuse.
+- Unchanged gate reuse, invalidation after relevant changes, typed completion
+  repair, persistent no-progress blocking and separate candidate scopes.
+- Code Intelligence reference direction, unknown freshness, incomplete traversal,
+  total response budgets, shared deadlines and pre-mutation receipt admission.
+- Delivery artifact/source/acceptance binding, bounded hashing, unsafe paths,
+  command outcomes and secret-safe multi-step browser proof reports.
+- Benchmark manifests binding actual source/build identity, fixture, acceptance,
+  model and startup policy; incompatible and legacy rows stay out of verified
+  comparison groups.
+
+## Limits and operational behavior
+
+No paid LLM calls, authenticated provider benchmarks, production deployments or
+real-browser end-to-end application runs were performed for this release. Browser
+journey tests use deterministic browser seams. Model cost/latency observations
+are fixtures, and there is no claimed percentage saving or general speedup.
+
+Old routing configurations retain their ranking unless optimization is enabled.
+New setup configurations choose `balanced`, requiring 20 comparable complete
+samples for baseline and alternative; the supported minimum is 10. Cost tiers
+and versioned setup profiles are configuration priors. Missing actual costs,
+partial usage or ambiguous role attribution prevent economic promotion.
+
+Provider counters reported only at call completion cannot impose an in-flight
+hard token cap. Known overruns are retained and block further dispatch; unknown
+interrupted usage needs an explicit budget decision. Separately prepared project
+planning and human time are not amortized into execution-sequence comparisons.
+
+Recovery preserves code and evidence, not a previous process's callback closures.
+A recovered integration cannot manufacture a missing economic success outcome.
+Candidate races resume the first retained alternative through ordinary recovery;
+additional alternatives remain available for inspection and explicit cleanup.
+Custom lifecycles without `retain` preserve their prior cleanup contract.
+
+Artifact hashes compare pre-check and post-check contents. They do not detect a
+change reverted between snapshots, establish reproducible builds or prove that a
+particular deployed binary or device was exercised. Hashing is bounded to 512 MiB
+per artifact, 1 GiB and 10 seconds per snapshot; checks run between synchronous
+reads and cannot preempt an individual blocked filesystem read. Delivery commands
+and declared environment labels remain project-authored evidence.
+
+Code Intelligence uses a conservative UTF-8 byte-based token estimate, not
+provider token accounting. Tiny budgets may only return the documented bounded
+error envelope. Backend freshness remains unknown without independent evidence.
+
+## Remote verification and publication
+
+The repository CI matrix runs Linux and Windows with Node 20 and 24. Its status
+is attached to the pushed release commit and pull request in GitHub Actions;
+local success alone does not establish cross-platform success.
+
+The dated [changelog](../CHANGELOG.md#1220--2026-10-03) is the source of release
+notes. A Git commit, push or tag does not imply npm publication. Publishing a
+GitHub Release triggers the separate trusted npm workflow; publication must be
+verified independently before reporting this version as available from npm.

package/docs/parallel-execution.md

@@ -80,15 +80,43 @@ one serial integration lane when integration measurements exist. Older runs with
 remain visible as missing integration history; forecasts are empirical ranges, not deadlines, and do
 not predict future contention from other projects.
 
-### Rejected integration recovery
-
-Worker and integrated-tree gates receive the same `YOKE_STORY` context. A rejected
-candidate is retained with its reason and an `integration-recovery.json` proof record;
-it is not silently discarded and regenerated. The next parallel run can reuse it
-without a new implementation model call when canonical project/worktree ownership,
-Git registration, target base and PRD digest still match. Integration gates run again.
-Changed target or PRD state blocks recovery and requires explicit reconciliation.
-Generated worktree names are shorter and Windows path limits are checked before setup.
+### Interrupted work and rejected integration recovery
+
+Worker and integrated-tree gates receive the same `YOKE_STORY` context. Production
+parallel execution retains useful work after failed gates, pause, cancellation and
+decision boundaries. Versioned records under `.yoke/integration-recovery/` bind the
+worktree, original owner, Git base, PRD contract and failure reason to a recovery phase:
+
+- `implementation` resumes the retained implementation with the previous failure as
+  feedback. An unchanged or descendant target is allowed after ownership and history
+  validation; integration still rebases and runs its gates.
+- `integration` resumes an already prepared candidate without another implementation
+  call. It requires the unchanged target base and reruns integration gates.
+
+Both phases require a valid registered worktree in the same repository and the same
+PRD contract. Untrusted or stale state requires explicit reconciliation. Generated
+worktree names are shorter and Windows path limits are checked before setup.
+
+Optional candidate races defer destructive loser cleanup until successful selection.
+If every candidate fails, the race pauses or is cancelled, or selection cannot finish,
+materialized candidates are retained after process cleanup. The first retained
+candidate occupies the ordinary story recovery record and resumes on the next run.
+Additional alternatives have separate records and remain available for inspection
+and explicit worktree cleanup; Yoke does not automatically schedule another race to
+compare those retained alternatives. Successful selection still removes unselected
+alternatives. A failed retention write reports recovery information and leaves the
+files in place. Custom or injected lifecycles without the optional `retain` hook keep
+their own existing cleanup contract.
+
+Retention preserves implementation and evidence, but consumes disk until integration
+or intentional cleanup. It does not reconstruct a previous process's routing callback:
+a recovered integration cannot manufacture a missing economic success observation.
+
+Repeated failures are tracked persistently against source, failure and approved
+contract identity. The first unchanged failure permits retry, the second requests a
+focused diagnosis, and the third blocks as `no-progress`. A real source, assertion,
+failure or approved-plan change resets the sequence. Volatile test durations and
+reporter timestamps do not reset it; concurrent candidates have separate scopes.
 
 Goals also use the worker pool. Their asynchronous checks use a separate default-one
 check pool; see [goal resources](GOALS.md). These are concurrency permits, not hard CPU