@hecer/yoke 1.21.1 → 1.23.0

package/docs/CODE-INTELLIGENCE.md

@@ -28,9 +28,51 @@ Install and pin these tools in the project or developer environment before enabl
 
 - Every request is tied to a workspace and a content-addressed snapshot of committed and uncommitted, non-sensitive files.
 - Paths are workspace-relative; traversal, symlinks, `.env`/key material and policy-excluded paths are rejected.
-- Read calls are bounded by timeout and output budgets. Results carry backend, version, source path, content hash, resolution and freshness.
+- Read calls share a request deadline and a complete-response output budget. Results distinguish backend identity, source location, semantic resolution and unverified index freshness. See the limits and evidence contracts below.
 - Edits run in a disposable Yoke sandbox. Preview writes a durable plan and diff but requires an approval record created by the Yoke control layer.
 - Apply rechecks the snapshot, plan expiry, plan hash, an exclusive transaction lock and idempotency. It produces a managed worktree and does not commit or merge; the existing Yoke loop and gates remain authoritative for integration.
 - Network access is not needed by the facade. Backend installation and any backend-specific network behavior remain an explicit environment concern.
 
 For a host that has no native MCP support (currently Pi), use the normal Yoke loop and bounded CLI/skill adapter. Yoke does not invent a second MCP transport for that host.
+
+## Evidence and trace contracts
+
+`code_trace` treats Serena's incoming reference list as references to the requested symbol. Each validated referencing symbol has an edge **to the requested target**. Two adjacent results never imply an edge between those results. Incoming implementation lists similarly use the `implements` relation. A bare symbol name is resolved to a unique path-bound Serena identity before requesting these relations; ambiguous targets remain unresolved.
+
+The pinned Graft trace interface returns text. Until an explicit edge format is validated, its output is retained as structural candidates, without invented call edges. Incoming references cannot establish outgoing calls, imports or inheritance: unsupported direction/relation combinations return partial results and explain the missing contract. `require_resolved` excludes unresolved structural candidates; it does not turn an unsupported query into a resolved graph. Semantic trace results currently cover one hop. Requests for greater depth are marked unverified instead of pretending traversal was completed.
+
+`frontier_remaining` counts known entries omitted by result limits, and `traversal_complete` is false when exhaustive traversal is unverified. Zero known omissions does not prove that no other references exist. Node limits preserve graph endpoints: returned edges never point at removed nodes.
+
+The workspace snapshot is content-addressed and an explicitly supplied snapshot is checked against the current workspace before processing. This check does **not** prove that Graft's index, Graphify's graph or the language server has processed those exact file contents. The supported wire contracts do not provide an independently validated index-to-snapshot binding. Consequently backend evidence uses `freshness: "unknown"` and `content_hash: null`; an untrusted backend field claiming `current` is not accepted as proof. The facade no longer stamps a current workspace file hash onto potentially older evidence.
+
+Recognized, path-bound Serena symbol records can have `resolution: "resolved"` while freshness remains unknown. Unrecognized records remain unresolved and cannot create symbols or edges. Read responses use `status: "partial"` and partial coverage for available backends because index freshness and exhaustive coverage are not established. A successful process call alone does not imply complete coverage. Missing backends remain separately identified in `backends_missing`.
+
+Each retained evidence link has a matching `provenance.evidence_id`. This additive field allows callers to resolve evidence IDs and lets output reduction remove unused provenance without breaking retained links. No response cache is used; no stale evidence is reused under a new snapshot or query.
+
+## Output and time limits
+
+The facade forwards all four configured limits:
+
+```yaml
+codeIntelligence:
+  mode: shadow
+  limits:
+    tokenBudget: 2400
+    timeoutMs: 10000
+    maxBytes: 2000000
+    maxBackends: 3
+```
+
+The effective output cap is the smaller of `maxBytes` and the effective token budget. A request's `token_budget`, where supported, can lower the configured cap, but cannot raise it. The default configured token budget is 2400. The budget covers the entire serialized JSON response in MCP `structuredContent`: result data, provenance, warnings, identifiers, coverage, errors and the metrics themselves. The outer JSON-RPC framing and the short MCP text summary are outside that response.
+
+**Token accounting is deliberately conservative:** one UTF-8 byte consumes one budget unit. `metrics.result_tokens` is therefore an estimate with `token_count_kind: "estimated"` and `token_count_method: "utf8_bytes_conservative"`. It is not provider-measured usage, a tokenizer-specific exact count or a billing estimate. `metrics.returned_bytes` is the actual UTF-8 size of the serialized structured response, including the metrics. This replaces the earlier four-bytes-per-token approximation and makes the same numeric budget stricter; increase the configured budget explicitly if a workflow requires larger context, rather than treating the old number as an exact token allowance.
+
+When an answer does not fit, text is shortened at Unicode-safe boundaries and lower-ranked entries are removed. Arrays and operation receipt fields keep their schema, retained graph edges have valid endpoints, and unused provenance is removed. The answer reports `partial`, adds a truncation warning and never claims complete coverage. Narrow the query or raise the configured budget to obtain omitted content; `next_cursor: null` does not imply a complete search.
+
+A budget can be smaller than the mandatory response envelope. For example, 128 budget units cannot encode all required identifiers and error fields. Such requests fail with `BUDGET_EXCEEDED` **before a backend is invoked**. The small, fixed-shape error envelope is the only output-cap exception; its size is reported accurately, and it contains no backend payload or unbounded error text. Apply additionally reserves space for its entire concrete receipt, including all changed paths and a possible deadline warning, before starting a transaction. An insufficient receipt budget rejects the apply without mutating. A completed apply keeps its transaction receipt even if synchronous work crossed the deadline.
+
+The effective deadline is the smaller of configured `timeoutMs` (10000 ms by default) and the request's `timeout_ms`/tool default. All backend calls, semantic target resolution and preview operations consume the same remaining time. MCP initialization and its subsequent tool call also share that allowance. A backend which ignores its timeout is closed, late results are discarded, and no subsequent backend starts after expiry. Backend shutdown has a separate bounded cleanup grace; synchronous filesystem snapshot/transaction operations cannot be preempted mid-operation, so the deadline is not an exact end-to-end wall-clock promise. A final deadline check after normalization and output reduction marks delayed results partial and keeps any completed operation's receipt. A preview needing the former 120000 ms tool default must also have a configured timeout of at least that size.
+
+## Validation scope
+
+The regression suite uses model-free adapters and local synthetic MCP processes. It verifies reference direction and endpoints, unknown payload handling, honest freshness and coverage, aggregate output limits, Unicode boundaries, evidence link preservation, tiny-budget failures, limit propagation, and shared deadlines including initialization. It does not assert a successful run against installed authenticated backends or an exact provider-token saving.

package/docs/CODEX-COMPARISON-2026-09-29.md

@@ -25,3 +25,18 @@ See the [Goals/resource audit](GOALS-RESOURCE-AUDIT-2026-09-29.md) for implement
 Reproduce with `bench/compare-codex.mjs`, then `bench/analyze-codex-comparison.mjs`. Use fresh, short output roots on Windows. The new summary tests verify median arithmetic, cache subtraction, unknown usage, incompatible policies and invalid measurements.
 
 Provenance: this report is disclosed as AI-assisted. Read-only text scans cannot establish human authorship or verify proprietary keyed watermarks; cryptographic verification and signer trust remain unknown without the corresponding verifier and trust policy.
+
+## Later tooling update — 1.22.0
+
+The measurements above remain the historical 1.19.0 results. The current analyzer
+reads their aggregate JSON as legacy/unverified because those runs did not record
+the new complete comparison manifest. It preserves the reported values and does
+not manufacture missing provenance or reinterpret them as 1.22.0 measurements.
+
+New runs record source/build, fixture, acceptance and submitted-input digests,
+requested and reported model identities, and explicit startup conditions.
+The historical direct-arm ignore-rules difference is now an expressly declared
+workflow variable. Undeclared cross-arm differences, missing provenance and
+failed acceptance do not produce performance comparison groups.
+See [benchmark manifests](BENCHMARK-MANIFEST.md) for the contract and limitations.
+This is a tooling change; no new authenticated comparison was performed for it.

package/docs/DELIVERY-JOURNEYS.md

@@ -0,0 +1,206 @@
+# 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 flow definitions containing only `name`, `path` and an optional `landmark` remain valid, but production browser runs now also require `smoke.sourceIdentity`.
+
+## 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
+  sourceIdentity:
+    path: /assets/app-specific-static-source.js
+    sha256: "<replace with SHA-256 of the served bytes>"
+  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
+```
+
+Replace the source resource path and hash placeholder before running this example. Confirm the intended server's checkout/build and port, then fetch a stable, app-specific source resource from the effective `baseUrl` origin and calculate the SHA-256 of the exact served body bytes. Dev servers may transform local source, so hashing a local file alone is insufficient. Set `sha256` to the resulting 64-character lowercase hexadecimal digest. The resource must return a successful HTTP response without redirects, finish within five seconds and contain at most 1 MiB. It must remain stable through the run. Production smoke checks the pin before browser launch and again after the flows; a missing or mismatching pin prevents valid smoke evidence.
+
+After an intentional source/build change, verify the server serves that change and explicitly refresh the pin. Do not update it automatically on a mismatch or accept a foreign process occupying the expected port. Choose a resource that changes with the relevant app source, rather than a shared health response or an unchanged marker. The static pin checks only that resource's bytes before and after the run; it does not independently prove the identity of every module, backend or dynamic response. Source fingerprints and other acceptance checks remain necessary.
+
+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.