@ckanner/flywheel 0.31.0 → 0.31.1

package/docs/en/investigation.md

@@ -0,0 +1,219 @@
+# 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 reads/searches and an evidence 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.
+
+The initial action family is implemented directly by Go:
+
+| 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 |
+
+Paths must be clean repository-relative paths. Each action references an approved
+path and existing hypotheses. The opened inode must match the inspected inode;
+`os.Root` confines traversal. A directory grant permits names only. This version
+has no arbitrary shell, external query, production restart, cache flush, data
+repair or writable investigator Agent action. Existing full-access configuration
+does not add capabilities to these Go handlers. Broader experiments require
+additional handlers, contracts and validation.
+
+`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.
+
+## 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, 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.
+
+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.
+
+## Optional JEV decisions
+
+Preparation `decision` is independent of legacy `jev-shadow` and absent by default.
+Its schema defines an explicit endpoint, fixed `jev-x.y.z` model, credential
+environment-variable name, timeout, policy version, mode, allowed data categories,
+thresholds and maximum calls. Credential values never enter the contract.
+
+- Off/offline do not contact the service; shadow captures a local snapshot;
+  advisory records advice; adopt can select one approved diagnostic action.
+  Thresholds are explicit experiment parameters, not measured deployment accuracy.
+- At least two legal choices and actual semantic uncertainty are required. One
+  request pairs applicability Noul with Choice and retains full probabilities.
+  Missing applicability, version mismatch, unauthorized fields, insufficient budget
+  or unknown execution cause abstention.
+- Before adoption, recheck task/run/revision, contracts, candidate, observations and
+  action binding. Consume the decision and bind a unique action invocation in one
+  CAS before dispatch. JEV cannot invent commands, skip acceptance or declare success.
+- An unknown optional request is not resent. Usage remains unknown and the task can
+  take its legal deterministic baseline. An unknown action outcome blocks. Ending,
+  cancellation and deadline expiration still reconcile the optional request read-only.
+- Maximum calls include unknowns. Hard budgets skip optional JEV when the API cannot
+  enforce a provable request ceiling. Character estimates are not reservations.
+
+Legacy workflow shadow captures only a local bounded summary; explicit `shadow run`
+evaluates it later. That switch cannot adopt actions or authorize new source/log
+sharing. Offline or shadow results do not establish a causal speedup. Compare full
+tasks using the existing baseline, core improvements without JEV, and those same
+improvements plus one action family.
+
+### Offline replay and explicit advisory evaluation
+
+The general decision capture is a `*.snapshot.json` document containing the frozen
+`snapshot`, `policy` and source `target-hash`. It is distinct from the legacy workflow
+shadow dataset. Review its facts and data permissions before any live evaluation.
+
+```bash
+flywheel decision replay --input frozen.snapshot.json --response native-response.json \
+  --endpoint "$JEV_ENDPOINT" --model jev-1.14.0 --expected-model jev-1.14.0
+```
+
+Replay accepts a recorded native System One response or a fixture, forces `offline`,
+does not read a credential, sends no HTTP and writes no journal or task state. The
+endpoint and equal fixed model IDs identify the intended target; the version above
+is an example and must match the response under evaluation. A bare Snapshot JSON
+requires `--policy reviewed-policy.json`. That flag also replaces the entire captured
+policy when used with a wrapper; omitted data permissions are not inherited.
+
+For an explicitly authorized live experiment:
+
+```bash
+flywheel decision evaluate --input frozen.snapshot.json --policy reviewed-policy.json \
+  --endpoint "$JEV_ENDPOINT" --model jev-1.14.0 --expected-model jev-1.14.0 \
+  --directory ./decision-evaluation --key-env MEROUTER_API_KEY --max-calls 5
+```
+
+`evaluate` always forces `advisory`, even if the source policy says `adopt`. The
+credential environment-variable name, fixed target, separate private journal and
+cumulative call cap are explicit. It preserves source data-category permissions and
+requires them to cover the snapshot. `--hard-budget` skips the optional call because
+the native API cannot enforce a request usage ceiling. Reusing the same journal and
+snapshot reads the original receipt; unknown requests consume the cap and are never
+resent. The command does not execute an action or change task state.
+
+Both commands print the baseline, effective policy, probabilities and receipt with
+`adopted: false`. Live errors or unknown outcomes return exit code 3 with that receipt;
+input/configuration errors return 1, cancellation before dispatch returns 143. A
+successful offline replay is parser/fixture evidence, not a measured model success.
+Limited task adoption still requires the separate preparation policy, data opt-in,
+frozen concrete Go action and current-state checks described above.
+
+## 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.
+This change does not enable a new default model, JEV, prewarming or higher
+concurrency. Ready queues, persistent workers and importing existing candidates
+remain conditional on measurement and their own recovery/acceptance evidence.

package/docs/en/jev-shadow.md

@@ -0,0 +1,67 @@
+# Optional JEV shadow evaluation
+
+[Documentation](../README.md) · English · [简体中文](../zh-CN/jev-shadow.md)
+
+This guide covers the optional workflow-shadow experiment. It captures a bounded
+task summary for later, explicit evaluation and does not choose the production workflow. Start with the
+[normal workflow](workflow.md); enable shadow evaluation only when collecting
+comparison evidence for a configured endpoint.
+
+## Enable or disable
+
+JEV is **off by default**. Missing `jev-shadow` in older configuration also means off: no credential lookup, network requests or shadow records. Existing Go Quick/Full selection stays in charge.
+
+In the desktop, open **Flywheel → Configuration**, choose the global or project
+scope, then open **JEV shadow advice**. Configuration loads automatically; review
+the endpoint and save. Alternatively merge this section into the effective
+complete `flywheel.config.json`:
+
+```json
+{
+  "jev-shadow": {
+    "enabled": false,
+    "endpoint": "https://merouter.play.one2x.ai/v1/systemone",
+    "model": "jev",
+    "expected-model": "jev-1.14.0",
+    "key-env": "MEROUTER_API_KEY",
+    "timeout-ms": 5000
+  }
+}
+```
+
+The shared template leaves the endpoint empty. Configuration stores the environment variable **name**, never the key. Local capture does not look up credentials; the process running an explicit `shadow run` must inherit the variable. Never put credentials in endpoint or model fields. Discovery selects one complete file in task → project → global → embedded order, without merging. Inspect the source with `config inspect --json`; saves affect subsequent starts. Disabling preserves previous records.
+
+Enabling captures task goals, requirement/acceptance descriptions and planning evidence privately for later review and labeling. The task itself sends nothing to JEV. No source files, diffs, execution logs or provider conversations are read. URL/home-prefix removal and common credential-pattern rejection are best effort, not universal anonymization. Review the business summary before explicitly sending it to your configured endpoint. This setting never authorizes a new data category or automatic adoption of diagnostic decisions.
+
+Only a new task's first ordinary run is captured, after existing workflow state is saved. It writes the bounded input and pinned target locally, with no HTTP wait, credential lookup or background goroutine. Resume, retry and single-step commands do not backfill observations. Invalid targets, rejected summaries and record failures log a warning and leave the primary workflow running. Hard-budget tasks can also capture, because capture creates no API usage. Cancellation skips capture and retains the normal task-stop behavior. Explicit Full and structural Quick exclusions remain deterministic blockers when a later experiment evaluates the snapshot.
+
+Advice never changes Quick/Full, routing, permissions, sessions, acceptance or PR/Merge gates. Independent usage and latency records do not enter the task budget. Unknown usage stays unknown; no billing savings are implied.
+
+## Explicit experiments
+
+Automatic captures live under `~/.config/flywheel/shadow/<target-digest>/<input-digest>/` (0700 directories, 0600 files). Logs identify the directory. `cases.json` holds the bounded summary; `target.json` pins endpoint, model, questions and policy. Before explicit evaluation, the report shows these cases as not run. The later `shadow run` owns its lifetime and separate call budget; it adds probabilities, suggestions, actual baseline, response model and usage. An intent without a terminal remains unknown and is not replayed. A different directory represents an explicit new experiment.
+
+With a Flywheel version that provides `shadow prepare|run|report`:
+
+```bash
+flywheel shadow prepare --task-dir docs/my-task > /tmp/jev-cases.json
+# Review the summary before sending it; supply MEROUTER_API_KEY in your environment.
+flywheel shadow run --input /tmp/jev-cases.json \
+  --directory /tmp/my-jev-experiment \
+  --endpoint https://merouter.play.one2x.ai/v1/systemone \
+  --max-calls 20 --timeout 5s
+flywheel shadow report --input /tmp/jev-cases.json \
+  --directory /tmp/my-jev-experiment
+```
+
+These explicit commands remain usable with automatic observation disabled. They do not start or mutate a task. Preparation requires a prepared or quiescent task. Reporting is offline and needs no key. For an automatic capture, use its `cases.json` as input. Copy it elsewhere before adding independent labels (`mode`, `status`, `author`, `reason`); labels are excluded from both requests and prediction cache identity. Preserve original captures.
+
+Datasets are limited to 100 cases and 1 MiB, requests to 64 KiB. Explicit `--max-calls` is 1–100; timeout is at most 30 seconds. A batch exceeding the new-call limit is rejected before dispatch. There are no HTTP redirects or retries; error response bodies are not logged. Commands print one JSON document on stdout, errors on stderr. Exit codes: 0 report success, 1 invalid input/runtime failure, 3 failed/unknown/not-run cases, 143 cancellation.
+
+## Interpretation
+
+Eight atomic Noul questions use fixed experimental thresholds: every positive condition ≥0.8 and every risk ≤0.2 yields a Quick candidate; any risk ≥0.8 yields Full; otherwise abstain. The manifest pins questions, thresholds and versions. Individual probabilities are not an overall accuracy score. Unexpected response models abstain until an operator reviews and updates the pin.
+
+This policy is **not production calibrated**. Reports separate decision-time, prepared, replay, historical and synthetic cases, and provisional versus confirmed labels. Current historical state need not be its initial Auto decision. Missing/provisional labels do not establish a false-Quick rate. Auto already uses preparation-time contract evidence; this experiment adds usage rather than removing a classifier call that never existed.
+
+The [six historical summaries](../evaluation/jev-historical-provisional.json) reference completed commits, with unknown actual modes and provisional labels. They test the interface and expose counterexamples, not production benefits. Real automatic workflow routing would require independently confirmed decision-time samples and measured false-Quick/abstention rates. There is no JEV Quick/Full routing switch. The separate bounded diagnostic decision policy cannot inherit this experiment's permissions or thresholds.

package/docs/en/model-policy.md

@@ -1,63 +1,148 @@
-# Reasoning effort and account selection
-
-[中文](../model-policy.md) · English
-
-Checked on 2026-11-05. This note separates documented capabilities, adapter behavior, engineering recommendations, and measurements. Official model documentation and request paths have been reviewed. **No representative Flywheel comparison of high, xhigh, and max has been run**, and no live user-account inference or quota check was performed. The defaults are editable starting points, not a measured optimum.
-
-## Why most bindings use high
-
-Seven of the eight stage/route bindings use `high`; Intake uses `low`. High matches the documented defaults for Kimi K3.1 Pro and DeepSeek Flash. GPT-6.1 Sol's API default is medium, so Flywheel explicitly requests a higher level. Astra's model page lists five levels without stating a universal API default. Sources: [Kimi models](https://www.kimi.com/code/docs/en/kimi-code/models), [DeepSeek thinking](https://api-docs.deepseek.com/guides/thinking_mode/), [Sol](https://developers.openai.com/api/docs/models/gpt-6.1-sol), and [Astra](https://developers.openai.com/api/docs/models/gpt-6-astra).
-
-High provides an initial comparison baseline without starting every loop at maximum effort. More reasoning can help difficult tasks while adding latency and usage; it does not guarantee a better delivery on every task. OpenAI's [deployment checklist](https://developers.openai.com/api/docs/guides/deployment-checklist) recommends representative evaluation before adopting xhigh/max for their additional cost and latency. That supports the evaluation method, not a claim that this project's defaults have already been benchmarked.
-
-## Effort values differ by backend
-
-| Current path | Checked capability | Flywheel request |
-|---|---|---|
-| GPT-6.1 Sol / Codex Pro 0.9.0 | Model supports `low/medium/high/xhigh/max`; machine API forwards effort | hard: high |
-| Sol and Astra / DSH ChatGPT provider | Models and checked provider catalog support `low/medium/high/xhigh/max`; serialized as `reasoning.effort` | Review and Judge: high |
-| Kimi K3.1 Pro / Kimi CLI | Native `low/high/max`, default high; thinking cannot be disabled | Plan, frontend, Garden: high |
-| DeepSeek Flash / DSH rc.5 | DSH accepts `off/low/high/max`, default high | ordinary execution: high; Intake: low |
-
-GPT supports xhigh and max; their absence from the defaults is a policy choice, not an interface limitation. These names are not a shared scale across providers. Kimi compatibility aliases xhigh/max/ultra resolve to native max. DeepSeek's generic API maps xhigh to high, while the DSH adapter used here rejects xhigh before that mapping because it accepts only the four listed values. Use max when explicitly selecting Flash's higher supported level. See the native model documentation above and DSH's [configuration](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/llm/llm-deepseek/src/config.ts) and [serialization](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/llm/llm-deepseek/src/serialize.ts).
-
-The ChatGPT provider snapshot is `388868f91bcdc05795fb94d21b868ded6d7219c9` (0.1.17): [dated model measurements](https://github.com/ckanner/dsh-plugin-chatgpt/blob/388868f91bcdc05795fb94d21b868ded6d7219c9/src/models/served.ts) and [request serialization](https://github.com/ckanner/dsh-plugin-chatgpt/blob/388868f91bcdc05795fb94d21b868ded6d7219c9/src/convert/request.ts). A catalog is not a live entitlement check for the user's account. The Codex Pro plugin name does not establish a separate server reasoning mode.
-
-## Stages worth comparing first
-
-These are **engineering recommendations inferred from stage responsibilities**, not measured performance results. This correction preserves effort choices; it adds no automatic escalation, effort-changing retry, or budget policy.
-
-| Stage | Baseline | Candidate comparison |
+# Models, reasoning effort, and accounts
+
+[Documentation](../README.md) · English · [简体中文](../zh-CN/model-policy.md)
+
+Flywheel selects a model through a stage or execution-route binding. The
+[default template](https://github.com/ckanner/flywheel/blob/main/templates/flywheel.config.example.json) is the source
+of truth for new configurations; an existing installation keeps its own
+configuration. These defaults are an editable baseline. The repository does not
+establish that they are the optimum for representative tasks, or that increasing
+reasoning effort improves every delivery.
+
+## Default bindings
+
+| Stage or route | Harness | Model | Access path | Effort |
+|---|---|---|---|---|
+| Plan | `kimi` | `kimi-code/k3.1-pro` | Kimi Code subscription through the native CLI | `high` |
+| Execute: default | `dsh` | `deepseek-flash` | DSH `deepseek-account` | `high` |
+| Execute: frontend | `kimi` | `kimi-code/k3.1-pro` | Kimi Code subscription through the native CLI | `high` |
+| Execute: hard | `codex-pro` | `gpt-6.1-sol` | Codex login through the public machine API | `high` |
+| Review | `dsh` | `gpt-6.1-sol` | DSH `chatgpt` provider | `high` |
+| Judge | `dsh` | `gpt-6-astra` | DSH `chatgpt` provider | `high` |
+| Intake | `dsh` | `deepseek-flash` | DSH `deepseek-account` | `low` |
+| Garden | `kimi` | `kimi-code/k3.1-pro` | Kimi Code subscription through the native CLI | `high` |
+
+The harness owns the agent/tool loop. A DSH `provider` selects its native LLM
+adapter, while a `channel` names the configured account/credential path. A
+`codex-pro` harness is not a DSH provider called `subagent_codex_pro`. Kimi uses
+its native CLI, not ACP. Auto, Quick, and Full do not change these bindings or
+increase effort automatically; see [Configuration](configuration.md).
+
+Claude Code Pro is available as an [optional backend](claude-code-pro.md), with
+no default stage or route assigned. Its profile uses an explicit native model
+and effort rather than an implicit replacement for another subscription.
+
+## Account selection
+
+The default and `subscriptions` preset use `deepseek-account` with
+`deepseek-flash`. Standard DSH desktop and SDK profiles under the same DSH home
+can share account authorization without an additional API key. Custom profiles
+must load the account service and adapter. Independent SDK calls still supply
+an explicit provider/model; changing the desktop chat model does not update
+Flywheel's bindings.
+
+`deepseek-official` is a separate API-key provider, selected only by explicit
+configuration. The default preset does not switch payment channels after an
+authentication or quota failure. User-configured fallback chains retain their
+own policy. ChatGPT and Kimi subscriptions likewise require the corresponding
+installed adapter or CLI and its supported login flow.
+
+Upgrades preserve existing user files. To adopt the subscription preset, inspect
+the effective complete configuration, preview the migration, then explicitly
+apply it as described in [Configuration](configuration.md). Restart the engine
+afterward; neither installing packages nor changing a desktop chat model
+migrates a running task.
+
+## Reasoning effort is backend-specific
+
+The following capabilities were checked for the documented integrations on
+**2026-11-05**. They are compatibility evidence for those snapshots, not a live
+catalog or an account-entitlement check.
+
+| Checked integration | Accepted request values | Notes |
 |---|---|---|
-| Intake | Flash low | high for ambiguous input or difficult merging/classification |
-| Plan | Kimi high | max for architecture, dependency, or acceptance-design problems |
-| Execute default | Flash high | max for difficult implementation or root-cause analysis; not xhigh |
-| Execute frontend | Kimi high | max for complex interaction state or cross-component consistency |
-| Execute hard | Sol high | prioritize xhigh comparisons; max for the hardest tasks |
-| Review | Sol high | xhigh for high-impact concurrency, consistency, or permission reviews |
-| Judge | Astra high | prioritize xhigh for high-impact milestone acceptance; max for the hardest cases |
-| Garden | Kimi high | low for routine organization; max for difficult cross-task synthesis |
-
-Hard execution tackles difficult implementation. Judge independently examines a whole milestone after L2/L3, making these two stages useful first comparisons. Changing every stage together makes the cause of any improvement harder to identify. OpenAI's [reasoning guide](https://developers.openai.com/api/docs/guides/reasoning) describes effort by task difficulty; applying that guidance to Flywheel's stages remains an inference.
-
-Change `thinking` in the effective complete configuration, inspect it, and restart the engine. Use `routes.hard.thinking` for hard only and `loops.judge.thinking` for Judge only. Stage overrides avoid changing every consumer of a shared profile. A task file with only those two fields is not a complete configuration and does not inherit the rest of the project file.
-
-For an actual comparison, hold the model, backend, context, task, and acceptance conditions fixed. Measure delivery success, first-pass acceptance, missed defects and false alarms, total time including rework, and input/output/reasoning/cache usage. Record observable subscription quota separately; unknown values remain unknown. API prices do not directly determine subscription task capacity.
-
-## Request evidence is not quality evidence
-
-Source and offline protocol tests establish field transmission and error behavior. SDK configuration acceptance or a successful machine-API request establishes acceptance at that interface. Independent effective-effort evidence and improved delivery quality require server evidence or actual task measurements.
-
-DSH `initialize` validates configuration but returns only serverInfo. Flywheel's `ready.reasoningEffort` echoes the request after initialization; it is not independent model-server attestation. Codex Pro separates `requestedEffort`, `accepted`, and unknown `effectiveEffort:null`. See the [DSH SDK server](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/sdk/server/src/server.ts) and [Codex Pro 0.9.0 protocol](https://github.com/ckanner/dsh-subagent-codex-pro/blob/37da3d75de32b809c4fb1a631ccc15191f3d87f9/docs/machine.md). A no-inference doctor cannot establish account balance, real inference, or higher-effort benefits.
-
-## The funded DeepSeek account is the intended default
-
-Current source selects `deepseek-account` for Flash in defaults and the subscription preset. Standard desktop and SDK profiles can reuse account authorization under the same DSH home; an additional API key is unnecessary. `deepseek-official` remains a separate, explicitly chosen API-key provider, not an automatic fallback.
-
-Desktop login can initialize an account-model default, but independent SDK calls still need explicit provider/model values. Flywheel requests `deepseek-account` and `deepseek-flash`, preserving both the selected access method and the Flash-only choice. Authentication or quota failures are reported. The default preset has no cross-channel fallback; explicit user-defined fallback chains retain their existing policy.
-
-**Release and migration are separate:** 0.28.3 changes the embedded default to account access; 0.28.2 still embeds the API default. Upgrades preserve user configuration, so adoption requires 0.28.3 or later followed by explicit migration. See [Configuration](configuration.md#deepseek-account-and-api-key-providers) for credential-sharing conditions and the preview/apply workflow. No user credentials or running tasks were modified by this source change.
-
-## Optional Claude Code Pro
-
-Claude remains unassigned in the default model policy. The optional `claude-code-pro` harness accepts an explicit native model and low/medium/high/xhigh/max request; an installed CLI or account can reject a choice. No new model ranking or effort benchmark is implied. See [the adapter guide](claude-code-pro.md) for the companion 0.4.0 public API, full-access boundary, and usage semantics.
+| GPT-6.1 Sol / Codex Pro 0.9.0 | `low`, `medium`, `high`, `xhigh`, `max` | The machine API forwards the selected effort |
+| Sol and Astra / DSH ChatGPT provider | `low`, `medium`, `high`, `xhigh`, `max` | The provider serializes `reasoning.effort` |
+| Kimi K3.1 Pro / native CLI | `low`, `high`, `max` | Thinking cannot be disabled; compatibility aliases `xhigh`, `max`, and `ultra` resolve to native `max` |
+| DeepSeek Flash / checked DSH adapter | `off`, `low`, `high`, `max` | This adapter rejects `medium` and `xhigh` |
+
+Names do not form a common scale across providers. In particular, a generic
+API's compatibility mapping does not override the DSH adapter's own input
+validation. Use `max`, not `xhigh`, when evaluating Flash's higher supported
+level on this path. The adapter must reject an unsupported selection rather
+than silently choose another model or effort.
+
+Compatibility references: [Kimi model documentation](https://www.kimi.com/code/docs/en/kimi-code/models),
+[DeepSeek thinking](https://api-docs.deepseek.com/guides/thinking_mode/),
+[Sol model reference](https://developers.openai.com/api/docs/models/gpt-6.1-sol),
+[Astra model reference](https://developers.openai.com/api/docs/models/gpt-6-astra),
+[DSH DeepSeek configuration](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/llm/llm-deepseek/src/config.ts),
+and [serialization](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/llm/llm-deepseek/src/serialize.ts).
+The checked ChatGPT provider is 0.1.17 at `388868f91bcdc05795fb94d21b868ded6d7219c9`:
+[model catalog](https://github.com/ckanner/dsh-plugin-chatgpt/blob/388868f91bcdc05795fb94d21b868ded6d7219c9/src/models/served.ts)
+and [request serialization](https://github.com/ckanner/dsh-plugin-chatgpt/blob/388868f91bcdc05795fb94d21b868ded6d7219c9/src/convert/request.ts).
+
+## Choose and evaluate a baseline
+
+Seven of the eight default bindings use `high`; Intake uses `low`. Keeping a
+stable starting point makes comparisons attributable to a particular stage.
+The following candidates are engineering judgments based on stage
+responsibilities, not measured Flywheel quality results.
+
+| Stage | Candidate comparison |
+|---|---|
+| Intake | Compare `high` for ambiguous input, merging, or classification |
+| Plan | Compare `max` for difficult architecture, dependencies, or acceptance design |
+| Execute: default | Compare Flash `max` for difficult implementation or root-cause analysis |
+| Execute: frontend | Compare Kimi `max` for complex interaction state or cross-component consistency |
+| Execute: hard | Compare Sol `xhigh` first; evaluate `max` on the hardest tasks |
+| Review | Compare `xhigh` for concurrency, consistency, or permission reviews |
+| Judge | Compare Astra `xhigh` for high-impact milestone acceptance, then `max` where justified |
+| Garden | Compare `low` for routine organization and `max` for difficult cross-task synthesis |
+
+Change `thinking` in the effective complete configuration. For example, change
+`routes.hard.thinking` to affect only hard execution, or
+`loops.judge.thinking` to affect only Judge. A stage override avoids changing all
+consumers of a shared profile. Do not create an incomplete task configuration
+containing only these fields: configuration discovery selects one file rather
+than merging files.
+
+Hold the model, harness, context, task, permissions, and acceptance conditions
+fixed. Measure delivery success, first-pass acceptance, missed defects and false
+alarms, total time including rework, and input/output/reasoning/cache usage.
+Record observable subscription quota separately and preserve unknown values.
+API prices do not directly determine subscription task capacity. The
+[session evaluation guide](session-evaluation.md) describes the repository's
+paired experiment tooling; effort comparisons need their own fixed conditions.
+
+## Bounded model and effort experiments
+
+The optional [execution policy](configuration.md#bounded-execution-policy-opt-in)
+declares complete allowed bindings per route, including account, effort,
+permission and history mode. Auto/Quick/Full do not enable it. A confirmed
+repeated L1 stall may advance the declared experiment order within existing
+attempt/token budgets and an explicit switch limit. This deterministic rule
+does not prove the next model is better. Channel errors use separately declared
+fallbacks; neither mechanism may select an undeclared model or payment channel.
+
+Effort changes cold-start the role and record complete before/after bindings.
+Comparisons must include rereading, startup and actual known/unknown usage and
+cost. Offline tests run real engine repair and recovery paths with controlled
+driver results; they do not establish live model quality or speed. Use matched
+real tasks with frozen oracles before changing defaults or claiming savings.
+
+## Interpret configuration and quality evidence
+
+Source and offline protocol tests establish field transmission and error
+behavior. SDK or machine-API acceptance establishes acceptance at that interface.
+Independent effective-effort evidence and better delivery quality require
+backend evidence or actual task measurements.
+
+DSH `initialize` validates configuration but returns only server information.
+Flywheel's `ready.reasoningEffort` echoes the request after initialization;
+it is not independent model-server attestation. Codex Pro separates
+`requestedEffort`, `accepted`, and an unknown `effectiveEffort:null`.
+See the [DSH SDK server](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/sdk/server/src/server.ts)
+and [Codex Pro machine protocol](https://github.com/ckanner/dsh-subagent-codex-pro/blob/37da3d75de32b809c4fb1a631ccc15191f3d87f9/docs/machine.md).
+A no-inference doctor cannot prove account balance, live inference, or the
+benefit of a higher effort setting.