@ckanner/flywheel 0.31.0 → 0.32.0

package/docs/en/workflow.md

@@ -1,54 +1,111 @@
-# From requirements to a merged PR
+# Workflow: from a goal to a pull request
 
-[English README](../../README.en.md) · [中文](../workflow.md) · [Getting started](getting-started.md)
+[Documentation](../README.md) · English · [简体中文](../zh-CN/workflow.md)
 
-This guide describes the **current source implementation** and a recommended operating workflow. It does not assert that a particular npm version has been published. Check the registry when installing. The engine's local delivery and the host's GitHub operations are separate responsibilities.
+Flywheel turns a reviewed task contract into verified local Git changes. The host
+assistant prepares the task; the Go engine owns scheduling, verification, recovery,
+and delivery. The workflow console can also create and merge a PR when those remote
+operations are explicitly authorized.
+
+Use this guide for an existing repository. For installation and a disposable first
+run, start with [Getting started](getting-started.md).
 
 ## 0. Normal entry: describe a goal and launch
 
-With a matching CLI/plugin release containing the adaptive workflow, use:
+In DSH Chat, describe the requirement with the task skill:
 
 ```text
-/flywheel-task Fix the identified bug, add regression coverage, and complete verification. mode=auto
+/flywheel-task Fix the identified issue, add regression coverage, and complete verification. mode=auto
 ```
 
-The current host conversation researches the code, creates or reuses the task integration worktree, prepares contracts and workflow facts, and calls `flywheel_launch`. Go validates eligibility and starts the engine; DSH associates that exact task with the initiating session's Flywheel view. There is normally no need to copy paths or repeat an authorization already given. Check `flywheel control launch --help` before relying on this new entry; older installation commands do not prove its availability.
+The host researches the code, selects or reuses the task execution directory,
+prepares the Spec, packets, executable acceptance checks, and workflow evidence,
+then calls `flywheel_launch` within the authorized scope. The plugin associates the
+actual task with the conversation. Loading a skill or receiving a proposal alone
+does not mean the engine started; check the launch result and task status.
 
-| Choice | Selection and loop |
+| Mode | Selection and execution |
 |---|---|
-| Auto, the new entry's default | Select Quick from supported contract facts; use Full when facts are insufficient or risks remain |
-| Quick | One milestone and packet: Execute, all required checks, one independent final Review, Git delivery |
-| Full | Plan, packet execution/review, integrated L2/L3, Judge |
-
-Quick requires clear scope, a known implementation pattern, complete verification mappings, and a final reviewer able to assess the whole task. Missing L2/L3 needs an explicit inapplicability reason. File count does not establish safety: authentication, permissions, payments, migrations, concurrency, and unresolved design use Full. An explicit Quick request still has to qualify. A verification gap or new risk causes a persisted upgrade to Full while preserving task identity, work, budget, and history.
-
-The first-success Quick path has two stage-agent calls, Execute and final Review. Host preparation, internal model/tool turns, and retries are separate. Required coverage, integration/user-path tests, and applicable defect sampling still run against the final candidate; Plan/Judge are recorded as not applicable with reasons, never as fabricated passes.
-
-Use `/flywheel-new` when the user only wants a proposal and `/flywheel-run <actual task path>` to start or resume an existing task. Preserve prior implementation and delivery authorization; honor an explicit request to review a proposal first. The sections below explain the individual checkpoints, not mandatory approval stops for the unified entry.
+| Auto, the default | Go selects Quick when recorded qualification facts are sufficient; otherwise Full |
+| Quick, also labelled ultraWork in the console | One milestone and packet; Execute, required checks, independent final Review, and Git delivery |
+| Full | Plan, packet execution and review, integrated L2/L3 checks, and Judge |
+
+Quick needs clear scope, a known implementation approach, complete requirement
+coverage, and a final review that can assess the whole task. Missing L2/L3 checks
+need explicit reasons. Authentication, permissions, payments, migrations,
+concurrency, or unresolved design risks select Full. An explicit Quick request
+still has to qualify; file count alone is not a risk assessment.
+
+A first-success Quick run has two stage-agent calls: Execute and final Review.
+Preparation, internal tool turns, retries, and upgrades are additional work. Required
+tests, coverage, applicable L2/L3, defect sampling, budgets, and cleanup remain in
+force. Plan/Judge are marked not applicable with reasons. A newly discovered risk or
+verification gap saves a one-way Quick → Full upgrade, preserving work and budgets.
+
+Use `/flywheel-new <goal>` for preparation without launching, and
+`/flywheel-run <absolute-task-directory>` for an existing task. Kimi uses
+`/skill:flywheel-task` and the corresponding `/skill:` names.
+
+## 0.1 Investigation and direct controls
+
+Task can accept “diagnose this and explain the cause” directly, prepare its contract
+and enter the Go-owned investigation. Calling New first is not required. Report-only
+goals stop at the report; authorized repair continues within the original scope
+when the evidence supports a conclusion. See [Investigation](investigation.md) for
+contracts, evidence, JEV and recovery. New → review → Run remains appropriate when
+proposal review is requested. Plan / Exec / Verify / Review / Status / Stop remain.
+
+Full reuses a confirmed, persisted Plan checkpoint when its inputs and baseline stay
+valid. Explicit Plan, verification gaps, changed contracts or untrusted baselines
+still replan. Targeted executor checks complement the complete Go gate and independent
+Review. Default model bindings remain; execution allowlists and verified incremental
+context are independent opt-ins described in [Configuration](configuration.md).
+
+Authorized investigations can include exact reproduction commands in private
+input copies and explicit GET/HEAD requests. Their real execution boundary,
+deadline, output limits and receipts belong to the investigation contract.
+Enabling JEV also permits bounded choices after confirmed implementation failures:
+repair, an approved feedback check, replanning, or an already allowed execution
+binding. Go retains workflow eligibility and the complete final gates; a successful
+feedback experiment does not complete the implementation.
 
 ## 1. Choose a model for preparation
 
-Preparation turns a requirement into a Spec, task packets, acceptance commands, boundaries, and recorded dry-run evidence. `flywheel-task` and `flywheel-new` use the host's current conversation model. They do not switch it based on `loops.plan`; that binding controls planning and revisions after the Go engine starts.
+`flywheel-task` and `flywheel-new` run in the host's current conversation. The
+`loops.plan` binding controls planning **after the engine starts**; it does not
+change that host conversation's model.
 
-For accounts that expose the named models, these are practical starting points:
-
-| Requirement | Preparation model and effort | Reason for the recommendation |
+| Preparation work | Suggested DSH provider / model | Effort |
 |---|---|---|
-| Ambiguous requirements, architecture, protocol, or process lifecycle changes | `chatgpt/gpt-6-astra`, `high` | Spend more reasoning on constraints, failure cases, and testable acceptance before execution |
-| A clear repository feature with known boundaries | `chatgpt/gpt-6.1-sol`, `high` | A practical default for making a concrete implementation plan |
-| A small, explicit fix or documentation update | `deepseek-account/deepseek-flash`, `high` | Keep preparation proportional to a narrow task |
+| Architecture, protocols, lifecycle, or uncertain acceptance | `chatgpt` / `gpt-6-astra` | `high` |
+| A bounded feature with established implementation patterns | `chatgpt` / `gpt-6.1-sol` | `high` |
+| An explicit small fix or documentation update | `deepseek-account` / `deepseek-flash` | `high` |
 
-These are engineering recommendations, not benchmark results or evidence that one setting is universally best. Confirm the exact model ID and supported effort in the selected account and adapter. The checked DSH Flash adapter accepts `off/low/high/max`, not `medium`. A catalog entry or accepted configuration does not prove that real inference has succeeded.
+These are engineering starting points, not project benchmark results. Check exact
+model IDs and supported effort in the selected account. Raising effort does not
+repair missing requirements or an invalid test oracle. Runtime defaults and the
+separate account channels are described in [Model policy](model-policy.md) and
+[Configuration](configuration.md).
 
-DeepSeek uses the existing signed-in, funded DSH account. `deepseek-official` API access is an explicit alternative; the default preset has no fallback to it. User-defined fallback policies remain explicitly configured. `high` remains an engineering baseline without project A/B evidence; do not automatically raise every stage to `xhigh` or `max`.
+## 2. Choose the task execution directory
 
-Use the preparation model to identify risks and improve the contract. Increasing effort cannot repair missing requirements, an invalid test oracle, or an incorrectly chosen working directory. Later execution routes and the independent Review/Judge stages remain explicit configuration; see [Configuration](configuration.md).
+Keep these locations distinct:
 
-## 2. Choose the task execution directory
+| Location | Purpose |
+|---|---|
+| Project workspace | Stable repository identity for Provider sessions; normally the original checkout |
+| Task integration directory | Checkout and branch where contracts are prepared and verified packets are integrated |
+| Task files directory | `docs/<slug>` inside that checkout; contains Spec, packets, state, and reports |
+| Packet execution directory | Candidate checkout used by Execute, verification, and Review; usually an engine-managed worktree |
 
-First inspect the effective `worktree.enabled` setting. The default enabled mode follows the independent Worktree flow below. With automatic management off, use the selected task checkout; callers may still choose a Worktree and parallel scheduling remains independent. Session project membership is recorded separately from execution location. See the [console guide](flow-console.md).
+The project workspace and execution directory may differ. Provider project
+membership does not redirect file operations: prompts and evidence identify the
+actual execution directory. A backend that cannot represent the selected split
+`workspace-write` sandbox rejects that combination before dispatch.
 
-For an existing repository, create or deliberately reuse a task branch in its own worktree before invoking `flywheel-new`. The host or user performs this step. Choose unused names and substitute the repository's actual base branch:
+For a repository using the default worktree policy, create or deliberately reuse a
+task branch and worktree before preparation. Inspect existing changes first, use
+unused names, and substitute the repository's actual base branch:
 
 ```sh
 git status --short
@@ -58,50 +115,63 @@ cd ../repo-my-feature
 git branch --show-current
 ```
 
-Inspect the initial status before proceeding. These commands create a new task branch without moving the original checkout's `main`. Do not use forced branch replacement to resolve a naming collision. If a task branch/worktree already exists, inspect its state and reuse it deliberately.
+Keep this task's files at `docs/my-feature` inside the selected checkout. The
+integration branch is the branch checked out in the supplied `cwd`; it is not
+hardcoded to `main`. Do not pair task files from one checkout with another
+checkout's `cwd`, or switch its branch during a run.
 
-Keep the task at `docs/my-feature` **inside this worktree**. Run preparation and later CLI commands from this root. If using the desktop view, choose this task directory; leave its optional project directory blank only when the DSH session's current directory is already this worktree. Do not pair the original checkout's task directory with the new worktree's `cwd`, or change the task worktree's branch during a run.
+`worktree.enabled` controls automatic **packet** worktree management, independently
+of scheduling. With it disabled, the selected task checkout can be shared or an
+external worktree can be registered before implementation. External directories
+must satisfy the engine's baseline, branch, cleanliness, and ownership checks; see
+[Parallel execution](flow-console.md#parallel-execution).
 
-The engine's integration checkout is the supplied `cwd`, not a hardcoded `main` branch. Its packet branches normally use `flywheel/<slug>/<packet-id>` and start from that checkout's HEAD. Successful packet delivery fast-forwards into the branch currently checked out there. This is why choosing a task branch before starting matters.
+### Isolation and failure behavior
 
-### Isolation has a fallback
+Worktrees separate working directories and indexes; they are not security sandboxes.
+The legacy serial path can record a worktree-creation failure and fall back to
+in-place execution. Parallel execution with automatic worktree management requires
+isolated directories and fails if they cannot be created. Disabling automatic
+management explicitly permits shared-checkout execution, with different validation
+and batch-delivery rules.
 
-Worktrees isolate working directories and indexes; they are not security sandboxes. The engine normally creates a packet worktree, but a creation failure can record the reason and fall back to **in-place** execution. There is currently no switch that requires successful isolation in every case.
-
-If strict task isolation is required and the log reports `worktree unavailable`, stop and inspect the workspace and recorded mode. Correcting a directory and restarting does not automatically convert an already persisted in-place packet into a new worktree. Preserve its work and resolve the recorded situation explicitly; do not edit `state.json`, delete results, or force-reset a branch to hide it.
+If isolation is required, inspect the recorded workspace mode and stop on an
+unexpected fallback. Preserve existing work and resolve the failure; do not edit
+`state.json` or force-reset a branch to manufacture an isolated state.
 
 ## 3. Prepare and review the contracts
 
-In the task worktree, ask the host to run `flywheel-new`, or inspect the bundled templates and prepare the contract files manually:
+From the task integration directory, use the preparation skill or inspect the
+bundled templates:
 
 ```sh
 flywheel template --list
 flywheel skills read flywheel-new
 ```
 
-In DSH's conversation input, select the skill from the `/` menu or send:
-
 ```text
-/flywheel-new Prepare docs/my-feature for this requirement. Research the actual code, define packets, routes, boundaries and executable acceptance checks, run L1 to record the baseline, then present the contracts for review.
+/flywheel-new Prepare docs/my-feature for this requirement. Inspect the code, define bounded packets and executable acceptance checks, run the baseline checks, and present the contracts for review.
 ```
 
-**No initial Flywheel-view form is required.** The assistant creates or reuses the task worktree, prepares `spec.md` and task packets, and reports two absolute paths: `repo_dir` for the project worktree and `task_dir` for its `docs/my-feature` task files. A project can contain several task directories; its root alone does not identify a Flywheel task.
-
-DSH uses `/flywheel-new`. Kimi uses `/skill:flywheel-new`; the prefixes are host-specific. See the pinned [DSH skill entry contract](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/client/ui-skill/README.md) and [Kimi slash-command reference](https://moonshotai.github.io/kimi-code/en/reference/slash-commands.html).
-
-A runnable task needs a reviewed `spec.md` and at least one legal `task-packet-*.md`, using the bundled schemas. The preparation should establish:
+No initial console form is required. Preparation should report the actual task
+execution root and task files path, while retaining the original project identity.
+A repository can contain several tasks; a repository path alone does not select one.
 
-- Requirement IDs, expected behavior, and scope exclusions.
-- Packet dependencies, execution routes, editable paths, and forbidden paths.
-- Real L1 commands and milestone L2/L3 commands with expected exit codes.
-- Frozen acceptance tests or other oracles, separately protected from implementation tests.
-- Actual dry-run results, with failure output and exit codes where applicable.
+A runnable task needs a reviewed `spec.md` and at least one legal
+`task-packet-*.md`. Establish requirement IDs, exclusions, routes, editable and
+protected paths, L1 commands, milestone L2/L3 commands, and actual baseline results.
+Keep frozen acceptance separate from implementation tests. Executors may add normal
+unit/regression tests; they may not weaken protected acceptance to obtain a pass.
 
-The unified entry also records `workflow` in the Spec: version, requested mode, qualification facts, code evidence, risks, and reasons for inapplicable checks. See [Workflow policy and recovery](configuration.md#workflow-policy-and-recovery). A model's low-risk label alone is insufficient. Old contracts without this field remain Full.
+The Spec's `workflow` records qualification facts, risks, and reasons for inapplicable
+checks. Parallel packets also need explicit `schedule.after` and `schedule.writes`.
+See [Workflow policy](configuration.md#workflow-policy-and-recovery) and
+[Scheduling and worktrees](configuration.md#scheduling-and-worktrees) for field
+examples. Contracts without workflow remain Full; packets without scheduling
+independence remain serial.
 
-Run the stated commands before recording their results. An intentionally failing baseline can be valid evidence; a guessed passing result cannot. Ordinary implementation and regression tests can be added by the executor. Frozen acceptance and configuration must not be rewritten to make an implementation pass.
-
-Review the files, then commit the substantive initial contracts so packet worktrees can obtain them from Git. The following assumes the index has been checked for unrelated staged work:
+Commit the reviewed contracts so packet worktrees can obtain them from Git. Inspect
+the index for unrelated changes first:
 
 ```sh
 git diff -- docs/my-feature
@@ -111,77 +181,122 @@ git diff --cached
 git commit -m "docs: prepare my-feature contracts"
 ```
 
-Stage any additional acceptance fixtures separately after review. Do not create `state.json`; the engine initializes and maintains it. An empty commit does not replace committing the actual contracts.
+Stage any additional acceptance fixtures separately after review. The engine creates
+and maintains `state.json`; neither preparation skills nor models write it.
 
-## 4. Open a task-level Draft PR
+## 4. Use a task-level Draft PR when useful
 
-Once the reviewed contracts are committed, a Draft PR gives the task a durable review location. The user or authorized host runs the GitHub steps:
+A Draft PR can provide a review location once the initial contracts are committed.
+The authorized host or user can open it before execution:
 
 ```sh
 git push -u origin task/my-feature
 gh pr create --draft --base main --head task/my-feature
 ```
 
-Describe the problem, expected outcome, acceptance criteria, and remaining work. Usually one independently deliverable requirement or milestone belongs in one PR. Packets are the engine's internal execution units; the engine does not automatically create a PR for each packet.
-
-Keep the PR in draft while implementation and acceptance are still changing. Opening it early does not imply that it should be merged early.
+Describe the problem, expected outcome, acceptance, and remaining work. Usually one
+independently deliverable requirement or milestone belongs in one PR. Packets are
+internal execution units, not automatically separate PRs. An early Draft PR does not
+authorize merge. The console's later PR operation re-queries an existing PR after
+push, avoiding duplicate creation.
 
-## 5. Run from the same task worktree
+## 5. Run from the same task execution directory
 
-After reviewing and saving the contracts, send these skill invocations separately in DSH Chat, substituting the actual `task_dir` returned during preparation. Query after starting; use the last entry when stopping is needed:
-
-```text
-/flywheel-run /absolute/path/to/repo-my-feature/docs/my-feature
-/flywheel-status /absolute/path/to/repo-my-feature/docs/my-feature
-/flywheel-stop /absolute/path/to/repo-my-feature/docs/my-feature
-```
-
-The skills resolve the project root from that existing task directory and invoke the CLI. They do not require opening or filling in the view. For direct terminal use, keep the current directory at the same task worktree root:
+For an existing prepared task, run these commands from its integration checkout:
 
 ```sh
 flywheel config inspect --cwd "$PWD" --task-dir "$PWD/docs/my-feature" --json
 flywheel doctor --cwd "$PWD" --task-dir "$PWD/docs/my-feature" --probe --json
-flywheel control start --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
+flywheel control launch --cwd "$PWD" --task-dir "$PWD/docs/my-feature" --mode auto
 flywheel control status --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
 ```
 
-Preflight does not infer with a model or execute acceptance commands. Its unknown and warning results still need interpretation. Starting the real task invokes the configured models. A control response's `ok` describes the operation; final task completion is in `state.status`.
+Preflight sends no inference prompt and runs no acceptance command. Starting the
+real task invokes the configured models. A control response's `ok` describes that
+operation; overall completion is reported by `state.status`.
 
-For the new unified entry, use `control launch ... --mode auto` in place of `start`. It consumes prepared contracts and defaults to Auto. `start` and foreground `run` accept optional `--mode auto|quick|full`; omission retains the contract or persisted choice. Existing legacy state remains Full. Restarting or requesting Auto does not reclassify or downgrade an established Full task.
+`launch` defaults to Auto. `start` and foreground `run` accept
+`--mode auto|quick|full`; omission preserves the contract or persisted selection.
+Status/stop never switch modes. Restarting or selecting Auto cannot downgrade an
+established Full task.
 
-DSH's `flywheel_launch` and `flywheel_control` start explicitly associate the supplied `taskDir` and `cwd` with the initiating session. CLI registrations can retain DSH's host session ID; independent terminal runs without that identity can be selected from Recent tasks and freshly queried. The UI has no editable task/project path fields: known locations appear read-only. The host directory comes from public `workingDirectory.get(session)`; a shell `cd` alone does not change it. The plugin does not scan or guess tasks.
+DSH equivalents are `/flywheel-run <absolute-task-directory>` and
+`/flywheel-status <same-path>`. Starts and read-only status association make the task
+available in the console. The console selects registered tasks and has no editable
+task/project path fields. CLI runs with a DSH host ID can be matched to that session;
+other runs remain selectable in Recent tasks. Discovery does not scan directories.
 
 ### Working directory by stage
 
-| Stage or entry | Working directory | Responsibility |
-|---|---|---|
-| `flywheel-task` / `flywheel-new` preparation | Task integration worktree | Host creates or reuses it according to the skill |
-| Full Plan / revision after upgrade | Task integration worktree | Engine uses the startup root to revise the task contracts |
-| Execute, L1, Review | Current packet candidate workspace, normally its packet worktree | Engine creates, records, and reuses that workspace |
-| Quick's applicable L2/L3 | The same packet candidate, before final Review | The engine must not validate a stale integration checkout |
-| Full L2/L3, Judge | Task integration worktree | Engine checks the integrated milestone |
-| Intake, Garden | Selected task's worktree | Host selects the root; Go writes proposals |
-| Status, Stop | Original task directory and execution root | Query or stop the existing task without requiring a new worktree, branch switch, or commit |
-
-Model-call permissions follow `permissions.mode`. Under `role-based`, the default for existing files that omit this setting, Plan/Execute request `workspace-write`; Review/Judge and DSH/Codex (including Codex Pro) Intake/Garden request `read-only`. Under `full-access`, every stage requests full access through the selected backend's public interface. Kimi print retains native auto behavior and provides no claimed OS-level read-only or workspace confinement. Stage duties remain unchanged: reviewers evaluate candidates, auxiliary modules produce advice, and candidate identity checks still run before and after review. See [Configuration](configuration.md) for configuration and migration details.
-
-Every loop does not create its own worktree. The outer task worktree spans the deliverable; a packet workspace spans its execution, acceptance, review, and delivery. Plan commits valid contract revisions in the integration worktree and attempts to fast-forward existing packet worktrees to that checkpoint while preserving implementation work. Conflicts stop for resolution.
-
-Go schedules packets serially and does not need a persistent parent model session to supervise them. `sessions.mode=scoped` permits ordinary repairs to continue the packet's Executor history, and a Reviewer may continue its own independent history for the same review scope. Every re-review still checks the complete current candidate, contract, and applicable requirements; closing old findings is insufficient. Plan history is task/milestone scoped, primary Judge and second opinion are separate, and an explicit Plan `resident-session:false` remains effective. Parallel DAG scheduling and team communication remain outside this implementation.
-
-New configuration templates explicitly select scoped mode; old files without the setting retain fresh mode. Fresh disables general role history reuse while preserving the legacy Kimi Plan resident option. Both modes journal supported main-task Codex Pro, DSH, and Kimi calls. Other adapters, mock, and Intake/Garden retain their existing paths. History reuse does not remove verification requirements or add stages to Quick's two-call first-success path. See [Session policy](configuration.md#session-policy-history-reuse-and-invocation-safety).
-
-Saved receipt recovery retains the original candidate, contract, and role guard evidence. Re-running sampling or verification cannot replace evidence bound to a pending receipt. Consuming an already completed result makes no new model request and does not bill twice; budgets constrain new dispatches. P3 uses public Codex/Claude lifecycle events, durable Go ACKs, and read-only invocation journals; recovered success still requires the original post-call candidate and role proof. P4 adds role overrides, bounded quality rebuilds, and paired evaluation, with thresholds disabled by default and live effects separately measured. See [recovery and quality](session-recovery.md) and [paired evaluation](session-evaluation.md).
-
-`flywheel-verify` runs deterministic acceptance only. Full retains the existing packet L1 / milestone L2/L3 behavior; Quick also collects applicable L2/L3 in the actual candidate workspace. It does **not** call Review or Judge, create worktrees, or perform local delivery. `--only execute` remains a partial Execute/L1 loop. A Quick task's `--only review` performs final Review without delivery; a verification gap, upgrade verdict, or lost Quick eligibility immediately saves the one-way Full checkpoint. The next complete run enters Full. `--only plan` requires Full, so explicitly request `--mode full` when a Quick task needs planning. Resume the complete run to let Go handle the remaining stages and delivery.
-
-The bundled skills check task location before preparation, run, resume, and manual loop actions. By default, development starts outside `main`, `master`, a known default branch, or detached HEAD unless the user has explicitly chosen and authorized that location. Direct CLI and GUI actions do not read or execute `SKILL.md`, create the outer task branch, or inherit those host checks. Read-only status and stopping must remain available even when development-entry checks would fail.
+| Stage | Execution directory |
+|---|---|
+| Preparation; Full Plan and permitted contract revision | Task integration checkout |
+| Execute, L1, independent Review | Current packet candidate directory |
+| Quick's applicable L2/L3 | The same packet candidate, before final Review |
+| Full L2/L3 and Judge | Task integration checkout after packet delivery |
+| Intake and Garden | Selected task execution root |
+| Status and Stop | Original task files and execution root; no new branch or worktree required |
+
+These are execution locations. Provider sessions retain the separately recorded
+project workspace. The task checkout spans the deliverable; each packet directory
+spans implementation, checks, review, and delivery. A new loop does not imply a new
+worktree or a permanently running parent model.
+
+### Scheduling and role history
+
+The embedded installation default selects `scheduler.mode=parallel` with a maximum of two.
+Existing complete configuration files that omit `scheduler` remain serial, as do
+explicit serial settings. Only ready packets with explicit dependencies and
+nonoverlapping declared write scopes qualify. Independent worktrees permit
+concurrent Execute/L1. Shared-checkout batches run Execute concurrently, then
+validate and review the combined candidate. Review, integration, and final gates
+remain serial. Hard budgets allow one model call in flight until its accounting is
+durable. See the [console guide](flow-console.md#parallel-execution).
+
+The optional `scheduler.dispatch="ready-queue"` fills free Execute/L1 slots among
+already independent Full packets with automatic Worktrees. Review, Plan revisions
+and integration still wait for started workers to settle. `scheduler.prewarm=true`
+can prepare one DSH Review runtime alongside a serial packet's deterministic
+checks, without sending a model prompt early. Parallel execution lanes and shared
+candidates do not prewarm; after an independent cohort settles, its serial Review
+path may start preparation. The useful overlap is mainly serial post-Execute L1
+and applicable Quick checks. Defaults remain batch dispatch and no prewarming;
+these settings do not change Task/New/Run or Auto/Quick/Full. Details and limits are
+in [Configuration](configuration.md#ready-queues-and-runtime-preparation).
+
+`scoped` history can reuse an eligible packet Executor session for repairs. Review
+uses its own independent history and always evaluates the complete current candidate.
+Plan is task/milestone scoped; Judge and second opinions remain separate. Old
+configuration without `sessions` retains fresh behavior. Both modes preserve
+invocation-safety records and block on unknown dispatch, outcome, or cleanup.
+[Recovery](session-recovery.md) explains trusted receipts, durable checkpoints, and
+bounded context rebuilding.
+
+### Partial stages and permissions
+
+`flywheel-verify` runs deterministic acceptance without Review/Judge or Git delivery.
+`--only execute` is a bounded Execute/L1 loop. Quick's `--only review` performs final
+Review without delivery and saves a required Full upgrade without starting Plan.
+`--only plan` requires Full. Resume the complete run for remaining stages and delivery.
+The console offers the same managed stage operations with revision checks.
+
+Model permissions follow the effective global policy and per-binding overrides.
+Full access does not remove frozen boundaries or reviewer candidate checks. Kimi
+print does not provide an OS sandbox guarantee. Skills also check the chosen task
+location before development; direct CLI/GUI calls do not execute `SKILL.md` or create
+the outer task branch. Read-only status and stopping remain available independently.
 
 ## 6. Understand local completion before merging the PR
 
-A packet is delivered only after required checks and independent Review match its current candidate, and Git delivery is confirmed. The engine commits implementation changes, performs `git merge --ff-only` into the integration checkout, persists delivery state, and cleans up only when safe. Failed commits or merges preserve the workspace. Full additionally runs integrated L2/L3 and Judge. Quick runs applicable L2/L3 before a final Review that covers every requirement, acceptance sufficiency, and continued eligibility; it then persists that same candidate.
+Local delivery requires current checks, independent Review, and verified Git
+persistence of the same candidate. Packet worktrees are integrated into the task
+checkout; failed delivery preserves work. Shared-checkout batches complete only
+after every member passes on the combined candidate and the batch is durably saved.
+Full also requires integrated L2/L3 and Judge. Quick requires a final Review covering
+all requirements, acceptance sufficiency, and continued eligibility.
 
-After the complete task passes, inspect the integrated changes and push them:
+Remote delivery is a separate operation. You can inspect and push the task branch
+manually:
 
 ```sh
 git status --short
@@ -191,9 +306,17 @@ gh pr ready
 gh pr checks
 ```
 
-Before merging, review the current PR diff, relevant acceptance evidence, required CI results for the current head, and the effect of the current base branch. Changes after a green run or review may require renewed evidence. If a required CI check cannot run, record the blocker and use the repository's explicitly authorized exception process; do not describe an unavailable check as passed.
+Or use the console's PR/Merge nodes after explicitly authorizing the repository,
+source HEAD, task branch, and target branch. These operations require normal GitHub
+CLI authentication and current local acceptance. Merge rechecks PR/head/base/checks
+and binds the request to the approved head; it does not use admin bypass or enable
+auto-merge implicitly. An accepted merge-queue request is not a confirmed merge.
+See [PR and Merge](flow-console.md#pr-and-merge).
 
-Manual merge after those gates is the recommended default. Auto-merge can be appropriate for a repository with an explicit policy, required checks/reviews, protected branches, and a defined class of eligible changes. Enabling it is a host/user decision; Flywheel does not infer that permission from an early Draft PR or a local packet pass.
+Review the current diff, required CI, and current base branch before merging. Changes
+after a green run may require renewed evidence. An unavailable check must be recorded
+as unavailable and handled through the repository's authorized process. Publication
+or deployment has its own validation and is not triggered merely by clicking Merge.
 
 ## 7. Stop and recover without losing evidence
 
@@ -201,20 +324,24 @@ Manual merge after those gates is the recommended default. Auto-merge can be app
 flywheel control stop --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
 ```
 
-Check the stop result and the actual failure before resuming from the **same** root and task path with `control start` or `flywheel-run`. A startup readiness timeout is a reason to query status and logs, not to launch a duplicate run. A stopped engine does not prove that every separately managed process is gone.
-
-Supported main-task adapters retain invocation facts and terminal receipts. Unknown dispatch, outcome, or cleanup blocks further execution in both session modes, including after a backend change. Confirm the task-owned plugin/app-server/guardian processes have ended when cleanup is uncertain; a fixed delay is not evidence, and process exit alone does not establish a known model outcome. Go must reconcile a trusted receipt against the original identity and evidence. Changing to fresh, switching task directories, resetting state, or retrying through another channel cannot bypass an unresolved invocation. Avoid broad process killing that could terminate unrelated sessions.
-
-For a delivery conflict, preserve the packet worktree, inspect Git state, resolve the conflict deliberately, then resume and let the engine revalidate evidence. Do not use forced cleanup or manual state edits as a recovery shortcut. Configuration changes require restarting the engine.
-
-## Reference boundaries
-
-The engine owns local state, bounded loops, verification, and Git delivery. The authorized host/user owns task-branch setup, GitHub pushes and PRs, remote CI policy, PR merge, and publication. Repository visibility and licensing are separate decisions.
+Check the stop receipt and actual failure before resuming from the same paths with
+`control start` or `/flywheel-run`. A readiness timeout or disconnected request calls
+for reconciliation, not a duplicate launch. Closing a view does not stop the engine.
 
-Implementation references: [engine](https://github.com/ckanner/flywheel/blob/main/internal/machine/run.go), [Git/worktree operations](https://github.com/ckanner/flywheel/blob/main/internal/verify/verify.go), [design](https://github.com/ckanner/flywheel/blob/main/docs/design.md), and [bundled skills](https://github.com/ckanner/flywheel/tree/main/skills). Additional documentation: [Git worktree](https://git-scm.com/docs/git-worktree) and [GitHub auto-merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request).
+Unknown dispatch, model outcome, or cleanup blocks further execution in both session
+modes. Process exit alone does not prove a known model result. Go must reconcile a
+trusted receipt against its original identity and evidence; switching to fresh,
+changing backends, or resetting state cannot bypass an unresolved invocation.
 
-## Interactive console delivery
+Preserve worktrees and reports when delivery conflicts. Resolve the actual Git
+conflict and let the engine revalidate. Configuration changes require an engine
+restart. Controlled human interaction with an eligible existing session is described
+in [Provider session interaction](flow-console.md#controlled-provider-session-interaction).
 
-The [workflow console](flow-console.md) adds stage controls, handoff, declared parallelism and explicitly authorized PR/Merge operations. Local completion does not authorize remote writes. An earlier Draft PR is reconciled after push; publication validates the actual merge commit separately.
+## Related guides
 
-Default-off [JEV shadow evaluation](jev-shadow.md) can independently observe new tasks without blocking execution on failure. Advice does not participate in Quick/Full selection or downgrade existing Full tasks. This feature requires the 0.30.1 CLI/plugin.
+- [Configuration](configuration.md): model bindings, permissions, budgets, and policies.
+- [Workflow console](flow-console.md): tasks, stages, sessions, run comparison, and remote delivery.
+- [Recovery and context quality](session-recovery.md): interrupted calls and safe continuation.
+- [JEV decisions](jev.md): one default-off switch for investigation and bounded failure decisions; Go retains workflow eligibility and acceptance.
+- [System design](../design.md): authoritative implementation contracts, in Chinese.

package/docs/evaluation/README.md

@@ -0,0 +1,12 @@
+# Evaluation data
+
+[Documentation](../README.md) · [中文文档](../README.zh-CN.md)
+
+These files are fixed experiment inputs and recorded outputs, not live
+benchmarks. Read the [session evaluation guide](../en/session-evaluation.md)
+or [JEV shadow guide](../en/jev-shadow.md) before interpreting them.
+
+| File | Purpose |
+| --- | --- |
+| [jev-historical-provisional.json](jev-historical-provisional.json) | Provisional historical inputs; not a production routing policy. |
+| [jev-historical-result-2026-11-10.json](jev-historical-result-2026-11-10.json) | Recorded results for the named experiment. |