@ckanner/flywheel 0.31.0 → 0.32.0

package/docs/en/investigation.md

@@ -0,0 +1,263 @@
+# Bounded investigation and feedback-driven workflows
+
+[Documentation](../README.md) · English · [简体中文](../zh-CN/investigation.md) · [Workflow](workflow.md)
+
+Task is the recommended goal entry. It identifies the requested deliverable and
+prepares the appropriate contract. Auto chooses Quick or Full only after a valid
+implementation contract exists. An investigation can deliver a report on its own;
+it is not a third implementation completion mode.
+
+| Daily request | Entry | Engine behavior and endpoint |
+| --- | --- | --- |
+| Diagnose and explain | `/flywheel-task` | Managed evidence collection, approved diagnostic experiments and a report; no implementation |
+| Diagnose and repair within scope | `/flywheel-task` | Supported report, then Spec and Auto; retain provenance, usage and scope |
+| Repair an identified issue | Task Auto or explicit Quick | Qualification, mandatory checks, independent final Review and Git delivery |
+| Propose a complex change for review | `/flywheel-new` | Stop after preparation; Run Full after implementation authorization |
+| Continue an existing task | `/flywheel-run` | Resume its original preparation or implementation ledger |
+| Run a particular stage | Plan / Exec / Verify / Review | Direct controls remain; stage success is not whole-task completion |
+
+Kimi uses `/skill:flywheel-*`. Status and Stop work for investigations and
+implementation. Existing repair authorization is retained; new scope or an
+unresolved product decision needs a separate decision.
+
+## Preparation contract
+
+The host prepares an input from the user's goal and repository facts. Go validates
+it and owns `preparation.json`. Users do not need to fill another large form, and
+the host never edits preparation state or `state.json` directly. The installed CLI
+exposes `preparation.schema.json`, `preparation-state.schema.json` and
+`preparation.example.json` through `flywheel template`.
+
+Version 1 records the goal, expected result, environment, time window, known
+evidence, falsifiable hypotheses, exact read paths, concrete actions and budgets.
+`intent` is `investigate` or `investigate-and-fix`. Repair intent requires a nonempty
+`implementation-scope`; report-only intent grants no implementation scope. A Spec
+is not required while only preparation exists.
+
+Go executes the evidence actions. Models choose only among candidates already
+approved in the contract:
+
+| kind | Capability | Boundaries |
+| --- | --- | --- |
+| `read_file` | Read one approved UTF-8 file | Reject symlinks, special files and excessive input |
+| `search_text` | Literal search in one approved file, with line numbers | No regular expressions or command interpolation |
+| `list_files` | List names in one approved directory | No recursive content grant; at most 4096 names |
+| `run_command` | Run exact argv against a temporary copy of approved inputs for reproduction or diagnosis | Explicit `host-process` authority, action timeout, controlled environment, process-group cancellation and cleanup |
+| `http_read` | GET or HEAD against an exact approved URL | HTTPS (loopback HTTP for tests), no redirects/environment proxy, bounded response and output |
+
+File paths must be clean repository-relative paths, and file actions reference an
+approved path. Every action references existing hypotheses. The opened inode must
+match the inspected inode; `os.Root` confines traversal. A directory grant permits
+names only, not its descendants' contents. Command and HTTP arguments belong to the
+frozen contract. JEV cannot generate another command, URL or credential variable.
+
+`limits` freezes action count, overall deadline, per-file bytes and total output
+bytes. Resume does not reset them. The deadline starts at preparation, including
+paused time. Bounded UTF-8 excerpts retain a content digest; `truncated` means the
+display is incomplete, not that an entire log or test inventory was observed.
+
+### Reproduction tests and diagnostic commands
+
+`run_command` uses `command.argv` without an implicit shell. `command.inputs`
+lists exact approved regular files from the contract's `read-paths`. Each invocation
+copies these inputs with their relative directory structure and runs in that copy;
+ordinary writes to the copy are not transferred back to the source workspace. This
+is a bounded reproduction input set: at most 32 UTF-8 files, subject to the contract's
+file and output limits, with executable bits preserved. A directory entry does not
+copy its descendants automatically. The following
+action fragment illustrates the fields. Replace paths and the hypothesis ID with
+those actually approved in the current contract:
+
+```json
+{
+  "id": "reproduce-timeout",
+  "kind": "run_command",
+  "purpose": "Reproduce the observed timeout with isolated inputs",
+  "hypotheses": ["timeout"],
+  "command": {
+    "argv": ["/usr/bin/python3", "tests/reproduce.py"],
+    "inputs": ["tests/reproduce.py", "src/settings.py"],
+    "env": [],
+    "timeout-ms": 30000,
+    "expect-exit": 1,
+    "execution-boundary": "host-process"
+  }
+}
+```
+
+`host-process` explicitly means execution with the current user's real host
+permissions. The copy keeps ordinary relative writes outside the original workspace;
+**it is not an operating-system sandbox or a network boundary**. Approve the concrete
+program and arguments within the task's existing authority. Full-access settings
+and the JEV switch do not grant that action authority on their own. `env` contains
+environment-variable names, never secret values. An expected nonzero exit can
+establish a reproduced failure. Timeout, cancellation, signals, output truncation
+and cleanup errors cannot stand in for a normal expected exit.
+An expected nonzero exit can be valid reproduction evidence, but does not by itself
+qualify the remaining collection for deferral or early finish.
+
+An observation's `execution` records physical exit/signal, timeout, cancellation,
+input digest and copy cleanup. `removed` means cleanup completed, `retained` keeps
+the experiment for reconciliation, and `not-created` means no copy was created.
+Unknown process or cleanup outcomes leave the original invocation pending and block
+further actions. Recovery reads its original receipt rather than executing again
+to guess the result.
+
+### Approved external queries
+
+The `http_read` action's `http` object contains `url`, `method` (GET/HEAD),
+`headers-env`, `timeout-ms`, `max-bytes` and `expect-status`. An approved health
+query might use `headers-env: {"Authorization": "INCIDENT_STATUS_AUTH"}`. The
+variable supplies the complete header value; the contract and receipt do not store
+that secret value. The URL is an exact authorization: no redirects, environment
+proxy or embedded credentials. Go bounds request time and bytes and records the
+actual HTTP status and output digest. A GET/HEAD grant does not authorize arbitrary
+services, production restarts, cache flushes or data repair.
+
+Structured command/HTTP outcomes, such as exit code, status and completeness, use
+`diagnostic-facts` and may participate under the default data policy. Raw output is
+included as a bounded excerpt only when `logs` is explicitly allowed. Otherwise
+the snapshot records that missing content, and JEV can still choose from structured
+facts. File evidence uses `source`. Action approval does not add raw-log sharing
+permission, and a permitted category does not remove the need to protect secrets.
+
+## CLI and desktop controls
+
+Create the actual task directory, then submit a complete preparation request:
+
+```bash
+flywheel control investigate --task-dir "$task_dir" --cwd "$repo_dir" < start-request.json
+```
+
+The outer request is `{ "action": "start", "contract": <complete-contract> }`;
+read the installed example and replace its paths, goals and permissions. `start`
+saves ready preparation without executing actions. To run, submit
+`{ "action": "run", "revision": <observed-revision> }` through the same command.
+
+Go starts a background owner under the existing task lifetime lease and token-bound
+stop protocol. In DSH, `flywheel_control` accepts `action: investigate` and the nested
+`investigation` request, associating the exact task with the conversation. The panel
+shows budgets, observations, excerpts, process exits/HTTP status, cancellation and
+copy cleanup, decisions and reports, with continue, reconcile, stop and refresh
+controls.
+
+```bash
+flywheel control status --task-dir "$task_dir" --cwd "$repo_dir"
+flywheel status "$task_dir"
+flywheel stop "$task_dir"
+```
+
+`ok:true` acknowledges a control request. `running` comes from the lifetime lease.
+An investigation-only response contains `preparation`, not a fabricated code-task
+`state`. Reconcile an uncertain result in the original directory before mutation.
+
+## Report and repair handoff
+
+`awaiting-report` means observations are available. The current host model submits
+one evidence-based report; Go checks fields, hypothesis coverage and references.
+Separate facts from inference, classify each hypothesis as supported, contradicted
+or unknown, and include counter-evidence, limitations, recommendation, regression
+checks and rollback conditions. References are real observation `invocation.id`
+values; missing or failed observations cannot be cited as successful evidence.
+
+Submit `action: report`, the observed `revision` and `report` through
+`control investigate`. Terminal report states are `supported`, `inconclusive` and
+`access-blocked`; cancellation produces `cancelled`. Supported means the analyst's
+conclusion has structurally valid evidence references. Go does not independently
+prove semantic causality. Uncertainty produces a report with limitations, not an
+automatic expansion of investigation or implementation authority.
+
+When the original request authorized repair and the investigation is supported
+with all receipts resolved, prepare Spec/packets in the same workspace and task
+directory, then launch normally. `preparation-source` records provenance, the report
+digest, authorized implementation scope, actions and elapsed time. Known JEV usage
+is imported once on its original dispatch day; missing usage and cost remain
+unknown. Resume never double-counts. Actual implementation changes are checked
+against the original scope, including after a Quick-to-Full or model upgrade.
+
+Preparation state, raw observations and the decision journal are private local
+runtime records excluded from automatic Git delivery. Do not publish credentials
+or source excerpts from logs automatically. Write a separately reviewed report when
+publication is part of the user's goal. Once admitted, deleting or changing the
+preparation source cannot bypass scope or accounting.
+
+## Feedback, progress and Plan
+
+Executor prompts recommend targeted checks first. Go still runs the complete frozen
+acceptance against the current candidate before independent Review. This removes a
+fixed requirement to run the full suite twice; it does not cache or remove the gate.
+Packets can declare up to eight approved short `feedback-checks` with the same
+`cmd`/`expect` shape as acceptance commands. They support targeted reproduction
+without changing final acceptance. With JEV enabled, the engine can choose one of
+these checks or recheck a failed L1 command after its prior result is confirmed.
+Short checks offered to JEV also require a nonblank `purpose` of 1–160 characters;
+entries without it remain available to Executor. JEV candidates send the description
+without appending `cmd`/`script`; the description itself must omit secrets and raw logs.
+
+Feedback carries stable check IDs, expected and actual physical outcomes,
+candidate/check-set/environment identities, a full failed-output digest and bounded
+head/tail excerpts. `observationComplete` describes command-outcome completeness,
+not a complete test inventory. A repeated identical failure is stalled only for
+comparable candidate, checks and environment. A changed candidate without a trusted
+oracle is unknown and retains the total attempt cap. File names alone do not prove
+stagnation, and free text cannot establish a trustworthy “10 failures to 1” metric.
+
+A Full Plan is reusable only after a confirmed terminal result, valid reloaded
+contracts, Git persistence and worktree synchronization. Normal repairs can retain
+that proof. Contract, verification or scheduling changes, an unknown external HEAD,
+legacy missing proof, explicit Plan or a verification gap require planning again.
+Speed changes the economics of feedback; it does not erase planning or quality gates.
+
+## JEV decisions
+
+Use the single `jev.enabled` setting described in the [JEV guide](jev.md). Start
+resolves configuration and freezes the policy automatically; Task, New and Run do
+not maintain separate decision modes. The default disabled path retains the
+original action order and collection limits. Enabled decisions may choose the
+next action, defer redundant evidence collection, or stop collection for a report
+when Go's evidence prerequisites are met.
+
+Deferred actions and early completion of collection are persisted with decision
+and observation references. They do not classify a hypothesis as proven or
+contradicted. The analyst still writes the evidence-grounded report, and repair
+still uses the original scope plus the ordinary verification and review flow.
+`awaiting-report` does not restart collection when Run is repeated.
+
+After handoff to implementation, the same switch also controls the next step after
+a failure: continue repair, collect an approved feedback check, request replanning,
+or select a model/effort from allowed execution bindings. These choices share the
+task decision allowance, including calls already used during investigation. Changing
+packet, replanning or resuming does not reset that allowance. Feedback checks collect
+facts and never replace complete final acceptance. See the [JEV guide](jev.md) for
+candidate and state semantics.
+
+The effective target, model, data categories, thresholds and budget are frozen at
+preparation time. Current OFF, incompatible target changes or tightened policy
+stop further optional decisions. In-flight results are rechecked before adoption;
+known/unknown receipts are reconciled without resending. A preparation initially
+created with JEV off keeps its baseline policy; a new preparation receives a newly
+enabled policy. The desktop labels its stored status as last observed.
+
+The [JEV guide](jev.md#replay-and-explicit-evaluation) documents local replay and
+explicit online evaluation. Replay stays available without JEV. Online evaluation
+requires the same enabled master and configured target; its data/call limits cannot
+loosen configuration. Neither tool executes actions or changes task state.
+
+## Measurement and remaining boundaries
+
+Alongside invocation records, `metrics.jsonl` now contains `phase-start` and
+`phase-end`. `control metrics` reports cumulative span duration separately from the
+union of completed intervals. Parallel spans cannot be summed as wall time. Missing
+ends, clock regressions and unmatched legacy calls remain explicit. Provider queue,
+model and internal tool breakdown remains unknown. Investigation actions/runs use
+the same phase API; unobserved host-preparation time is never filled with zero.
+
+Offline checks do not establish fewer tokens, lower cost or equal final quality.
+JEV remains off by default; enabling the master switch activates the supported
+decisions. Default models and concurrency are unchanged. The
+[ready queue and bounded DSH runtime preparation](configuration.md#ready-queues-and-runtime-preparation)
+are now available as explicit scheduler settings, with batch dispatch and no
+prewarming remaining the defaults. Real performance and any default change still
+need measurement. Long-lived workers and general external-patch import remain
+separate work; the existing managed Session claim/return path keeps its original
+recovery and acceptance requirements.

package/docs/en/jev-shadow.md

@@ -0,0 +1,5 @@
+# JEV guide moved
+
+[English](../en/jev-shadow.md) · [简体中文](../zh-CN/jev-shadow.md)
+
+The current [JEV decisions guide](jev.md) describes the single `jev.enabled` switch, actual diagnostic adoption, evidence-based collection controls and evaluation tools. The old automatic shadow observer and separate network client have been retired. Historical results remain in the [original validation record](../validation/2026-11-10-jev-shadow.md).

package/docs/en/jev.md

@@ -0,0 +1,240 @@
+# JEV decisions
+
+[Documentation](../README.md) · English · [简体中文](../zh-CN/jev.md)
+
+Flywheel has one JEV switch: **Enable JEV** (`jev.enabled`). It is off by default.
+Enabling it activates every supported JEV decision point automatically. There is
+no separate shadow, advice, adoption, or per-feature switch in the task workflow.
+
+## Enable once, use the usual task entries
+
+In the desktop, open **Flywheel → Settings → JEV** and choose the intended global
+or project scope. Turn on **Enable JEV** to reveal the connection fields, fill or
+confirm the System One endpoint, fixed model version and credential
+environment-variable name, then select **Save changes**. The switch edits a draft;
+activation takes effect when you save. Editing and saving do not test service
+connectivity. Tasks do not ask for the same approval again.
+
+The process running Flywheel must receive that environment variable. Configuration
+stores its name, never its value. Advanced fields bound timeout, call count,
+thresholds and shared data.
+
+`key-env` accepts 1–120 ASCII letters, digits and underscores, beginning with a
+letter or underscore. Uppercase, lowercase and mixed-case names retain their exact
+spelling when an investigation freezes its configuration and reloads its state.
+
+The equivalent configuration section is:
+
+```json
+{
+  "jev": {
+    "enabled": true,
+    "endpoint": "https://your-service.example/v1/systemone",
+    "model": "jev-1.14.0",
+    "key-env": "MEROUTER_API_KEY",
+    "timeout-ms": 5000,
+    "max-calls": 8,
+    "min-applicability": 0.8,
+    "min-choice": 0.6,
+    "allowed-data": ["task-summary", "diagnostic-facts", "source"]
+  }
+}
+```
+
+Replace the example endpoint with your service. The model must be a fixed
+`jev-x.y.z` version matching the response. The distributed template leaves the
+endpoint empty and JEV disabled. Enabled configurations with an invalid target
+fail validation. Missing credentials at execution keep the deterministic baseline.
+Existing decision/request records preserve their actual skip or failure reasons;
+an implementation task can fail a precondition before creating its first runtime
+decision ledger, so not every bypass has a receipt.
+
+Configuration selects **one complete file** in task → project → global → embedded
+order. A project configuration that leaves JEV off overrides a globally enabled
+configuration; fields are not merged across files. Use `config inspect --cwd
+<project> --task-dir <task> --json` to inspect the actual source. See
+[configuration](configuration.md) for discovery and editing.
+
+Use the normal entries after configuration:
+
+- **Task** prepares and runs authorized investigation or implementation from your goal. Go resolves
+  the JEV policy automatically; the host does not handwrite a decision mode.
+- **New** prepares an investigation contract or an implementation proposal and stops before execution.
+- **Run** starts or resumes the prepared investigation or implementation task in its original directory.
+- Auto, Quick and Full remain implementation workflow choices. Their eligibility,
+  acceptance and review requirements continue to be enforced by Go.
+
+## What the switch controls
+
+| Decision point | JEV enabled | JEV disabled |
+| --- | --- | --- |
+| Next evidence action | Choose among approved reads, searches, directory lists, diagnostic commands and HTTP queries when the choice is uncertain | Original deterministic action order |
+| Redundant evidence collection | May defer remaining actions for an already observed hypothesis through an evidence-bound control choice | Original action set remains |
+| Enough evidence for a report | May end collection early once the engine's evidence prerequisites are met | Collection ends at the original action, time or output limit |
+| Next step after a confirmed failure | Choose among legal local repair, feedback-check and replanning candidates | Existing bounded repair and escalation rules |
+| Model / effort selection | Choose a complete approved execution binding and record the actual switch | Existing fixed binding and deterministic quality/channel fallback |
+| Feedback-check priority | Select an approved check to collect facts before continuing bounded execution | Existing feedback and acceptance order |
+| Explicit online evaluation | Available under the same enabled setting, target and configured limits | Refused before a request or evaluation journal is created |
+| Recorded offline replay | Local parser/evaluation tool; no model call | Still readable; no model call |
+
+“All supported decision points” does not mean every task makes a JEV request.
+Single legal actions and deterministic choices execute directly. Missing data
+permission, hard budgets without an enforceable request ceiling, exhausted calls,
+low applicability, errors and invalid responses retain the baseline. Any decision
+or request records already created preserve their actual reasons; preconditions
+that fail before recording do not imply a new skip receipt.
+Auto still uses Go contract eligibility to choose Quick or Full. Entry routing does
+not gain a mandatory JEV classification request.
+
+Early finish and deferred actions are collection decisions, not proof of a root
+cause. Go records the exact decision, observation and action bindings. The analyst
+must still submit a report covering all hypotheses with actual observation
+references and any uncertainty. An inconclusive report remains inconclusive. A
+repair still needs its originally authorized scope and the ordinary implementation,
+review and verification flow. See [investigation](investigation.md).
+
+## Next steps after failure and model selection
+
+Before generating candidates, the engine confirms that the previous invocation has
+ended, its result has been consumed, candidate/failure evidence can be reconciled,
+and attempts and budget remain. JEV returns a concrete action ID. Go rechecks the
+identity and current switch and persists selection/effect atomically. Existing
+failure caps, one-way Quick → Full upgrades, full acceptance and independent Review
+remain effective. JEV cannot treat an unknown executor outcome as permission to retry.
+
+| Action | Effect | Prerequisite |
+| --- | --- | --- |
+| `repair` | Continue local repair within the same packet | Another execution attempt and budget remain legal |
+| `feedback-N` | Run one short check from the contract's `feedback-checks` and supply its physical result to the next attempt | The check is explicitly approved and has a `purpose`; models cannot create or change its command |
+| `recheck-N` | Rerun a failed L1 check with a complete prior observation to collect fresh feedback | The check belongs to frozen acceptance and its failure is confirmed |
+| `replan` | Use the existing bounded planning / workflow-upgrade path | Planning is legal, with original scope, revision limits and history retained |
+| `model-N` | Select a specific allowed execution configuration | `execution-policy` is configured and the complete binding and switch limits are valid |
+
+`N` indexes the frozen candidate set; it is not a model name or arbitrary command.
+A model candidate resolves to its actual binding ID, harness, Provider, account channel,
+model, effort, permission and session policy. Missing approved candidates do not
+authorize guessing a model name or adding a paid channel. Model/effort changes
+retain the existing cold-start rules and never pass Executor history to Reviewer.
+AUTH/QUOTA and other channel failures keep their corresponding fallback rules;
+they are not evidence of insufficient reasoning ability. See
+[configuration](configuration.md) for the allowed binding set.
+
+A short check's `purpose` is a nonblank description of 1–160 characters. The JEV
+candidate sends this description without appending the `cmd`/`script` text. Keep
+secrets, raw logs and commands out of the description itself.
+Entries without `purpose` remain available to Executor but do not become targeted
+JEV candidates. This field belongs only to `feedback-checks`; it does not extend
+acceptance fields or task authority.
+
+A feedback check supplies evidence for the next action. Even if it passes, the
+engine still runs every required acceptance check against the final candidate;
+the choice cannot remove checks. Task and node views show the request, adoption or
+baseline reason, feedback check and recorded effect. `applied` means the control
+decision was applied; subsequent repair, planning and model sessions remain in
+the node records. `completed` means this control action settled, not that the whole
+task was delivered. `feedback-completed` likewise means only that feedback settled.
+`pending` requires request reconciliation. `feedback-running` and `feedback-unknown`
+require the original action to be reconciled and must not be replayed automatically.
+`feedback-stale` blocks execution because feedback changed candidate or verification
+inputs. `replan-running` means replanning has not settled; recovery must reconcile
+the original Plan session rather than dispatching again to guess its outcome.
+Applied model changes show the actual before/after bindings, attempt,
+reason and time. The UI never guesses a model from `model-N` or treats a configuration
+change as proof that a new session ran successfully.
+
+## Data, budgets and recovery
+
+For an investigation, Go freezes the effective JEV target, data categories,
+thresholds and call budget when preparation is created. Task-provided historical `decision` modes cannot turn
+JEV on while the effective master setting is off. The default enabled data set
+allows the task summary, diagnostic hypotheses, structured command/HTTP outcomes,
+and bounded excerpts of approved file evidence. `allowed-data` can narrow this set.
+Raw command/HTTP output is included only with explicit `logs` permission; otherwise
+the snapshot records that missing content and uses structured facts. Permission is
+not automatic redaction: any remaining unauthorized category skips the complete
+request, and summarization cannot bypass the original data policy.
+
+Disabling the setting stops subsequent JEV dispatches and adoption in existing
+runs, including a result returned after the switch was disabled. Already dispatched
+requests are reconciled using their frozen identity, and their known or unknown
+usage is retained. Unknown requests are not retried. Unknown **action** outcomes
+still block execution until reconciled.
+
+An investigation preparation created while JEV was off stays on its baseline;
+enabling JEV does not rewrite that preparation. A newly created preparation can
+freeze the enabled policy.
+
+Implementation freezes its own runtime decision policy at the first eligible
+failure in an enabled run. If the current process started with JEV off and has no
+runtime decision ledger, saving an enabled setting does not activate that process
+immediately: start or resume the task so it reads the enabled configuration. Once a
+runtime decision ledger exists, turning JEV off and back on retains its frozen
+target, records and remaining allowance, including imported investigation calls.
+Changes that invalidate a frozen target or tighten its permissions/limits disable
+further optional decisions rather than silently rewriting the policy. Check the
+reported JEV status and reason; do not copy ledgers or reset budgets to bypass it.
+
+`max-calls` is a task allowance that includes unknown dispatched requests. Calls
+used during investigation are imported into implementation's allowance. Multiple
+packets, model switches, replanning and resume cannot reset it. This is a call cap,
+not a guaranteed token or currency ceiling. A configured hard budget skips JEV when
+the service cannot enforce a provable per-request bound. Requests record actual
+usage when available; missing usage remains unknown.
+
+Implementation's `runtime-decisions` record lives in `state.json` and retains the
+frozen policy, used/imported call counts, requests, selections and effects. It
+follows the existing state commit and delivery rules. The request journal under
+`.investigation/runtime-decisions` is private and excluded from automatic delivery;
+that exclusion does not apply to the copy of decision information in `state.json`.
+
+The desktop displays bounded summaries and omits raw snapshots and target
+configuration from its projection. This display projection does not redact Git
+delivery. As with existing failure feedback, approved goals, facts, bindings and
+feedback output must follow the existing rule against recording credentials.
+Pending requests/actions are reconciled in their original task, without a new
+journal or model switch bypassing an unknown outcome.
+
+## Replay and explicit evaluation
+
+Normal tasks save frozen `*.input.json` documents and receipts in their private
+decision journal. Offline replay also accepts historical `*.snapshot.json` captures:
+
+```bash
+flywheel decision replay --input frozen.input.json --response native-response.json \
+  --endpoint "$JEV_ENDPOINT" --model jev-1.14.0 --expected-model jev-1.14.0
+```
+
+Replay reads no credential, makes no HTTP request and writes no journal or task
+state. A bare Snapshot requires `--policy reviewed-policy.json`; an explicit policy
+replaces the complete captured policy rather than inheriting missing fields.
+
+For a deliberate online evaluation, enable JEV in the relevant scope first:
+
+```bash
+flywheel decision evaluate --cwd "$repo_dir" --input frozen.input.json \
+  --directory ./decision-evaluation --max-calls 5
+```
+
+The endpoint, fixed model and credential variable come from the same configuration.
+Legacy explicit target flags must match it. Evaluation forces advisory behavior;
+it never dispatches an action or changes task state. Its call cap, timeout,
+thresholds and data categories cannot loosen the configured bounds. Reusing an
+input and journal reads the original receipt; it does not resend an unknown call.
+
+Both tools return `adopted: false`. Live failures and unknown outcomes return exit
+code 3, input/configuration errors return 1, and cancellation returns 143. Offline
+fixture success is not evidence of live model accuracy or lower task latency.
+
+## Migration from shadow evaluation
+
+The old automatic observer and separate shadow network client have been removed.
+Old `jev-shadow` configuration remains readable for migration: connection hints are
+retained, but the old enabled flag never activates online decisions. An explicit
+new `jev` section takes precedence. Saving through the editor writes the unified
+section and removes the legacy key while preserving the normal backup/revision
+checks. The retired `shadow` command reports the migration path without running
+an experiment. Historical records and their schema remain available as evidence.
+
+To assess value, compare complete tasks with JEV off and on: time to useful evidence,
+actions performed/deferred, total latency, actual/unknown usage, and final quality.
+A different action order or a passing fixture alone does not establish a speedup.