@ckanner/flywheel 0.30.2 → 0.31.1

package/docs/en/contributing.md

@@ -0,0 +1,303 @@
+# Contributing to Flywheel
+
+English · [简体中文](../zh-CN/contributing.md) · [Documentation](../README.md)
+
+Start with the [project overview](../../README.md), the authoritative
+[system design](../design.md) (Chinese), and [AGENTS.md](https://github.com/ckanner/flywheel/blob/main/AGENTS.md).
+Flywheel is a deterministic Go orchestrator: models plan, implement, and review
+bounded tasks; code owns state transitions, verification, budgets, and process
+lifecycles. Contributions must preserve that boundary.
+
+## License and scope
+
+Flywheel is distributed under the [MIT License](../../LICENSE). Keep its copyright
+and license notice with copies or substantial portions of the software. Preserve
+third-party notices and the provenance of bundled dependencies; the repository's
+license does not replace their terms.
+
+Keep credentials, private project contents, and unredacted model/session logs out
+of issues, PRs, and fixtures. For a sensitive security report, request a private
+reporting route before disclosing details; the repository does not publish a
+separate response-time commitment.
+
+## Choose a branch and execution directory
+
+Use or reuse a worktree dedicated to the change. For a new change, when `origin`
+and `main` are the intended remote and base:
+
+```sh
+git status --short
+git fetch origin
+git worktree add -b task/my-change ../flywheel-my-change origin/main
+cd ../flywheel-my-change
+```
+
+Inspect an existing branch or directory before reusing it. Preserve other work
+and keep the change's contracts, configuration, checks, and commits in the same
+integration checkout. The original repository remains the session's project
+workspace; the integration checkout and packet worktrees are execution locations.
+When Flywheel develops the change, follow the effective `worktree.enabled` policy.
+The engine merges accepted packets into the integration checkout's current
+branch, not automatically into `main`.
+
+Worktrees isolate checkout files and the index; they are not security sandboxes.
+Serial execution can retain the documented `in-place` fallback. Parallel execution
+with automatic worktree management requires successfully created isolated
+worktrees. With automatic management disabled, shared execution uses batch-wide
+verification and delivery. See the [workflow](workflow.md) and
+[console](flow-console.md) guides for these distinctions and external directory
+registration.
+
+Prepare requirements, scope, and executable acceptance criteria before a large
+implementation. Open a Draft PR once there is a useful reviewable plan or change;
+one PR may cover several packets. Keep commits focused and use English
+Conventional Commit subjects, such as `fix: preserve cleanup evidence`.
+Agents follow the user's existing commit, push, and merge authorization without
+asking again for an already authorized step or extending it to a different action.
+
+## Implement against observable contracts
+
+The [design invariants](../design.md#2-设计不变量) and AGENTS file define the core rules:
+
+- Go and `internal/state` own task state. Writes use revision compare-and-set and
+  atomic replacement; models and skills never edit `state.json`.
+- Contract schemas define valid input. Validate at load time and update the design
+  before changing a wire contract, including the error taxonomy.
+- Test completion, cancellation, timeouts, and cleanup using observable results.
+  A terminal text marker or worker exit does not prove its child groups stopped.
+- Verification and independent review apply to the candidate that is committed
+  and merged. Preserve work and evidence when a gate or Git delivery fails.
+- Missing usage, cost, permission, or capability evidence stays unknown; it cannot
+  become success or zero cost.
+- Skills validate inputs and invoke the CLI. The desktop plugin consumes Go
+  control interfaces; neither owns a second state machine or retry loop.
+
+Use meaningful failure-path tests and narrow I/O injection points. Every measured
+Go function must reach 100% statement coverage; only the trivial `cmd/flywheel`
+entry stub is excluded. Preserve that gate and test behavior rather than repeating
+the implementation solely to increase the percentage.
+
+## Build and verification
+
+Source development needs **Go 1.27 or later** and Git. Flywheel's npm runtime
+requires **Node 22.18.0 or later**; the selected DSH release may require a newer
+Node version. CI and releases pin **Node 24.22.1 / npm 12.2.1**. Use those versions
+when reproducing package and installation evidence.
+
+Run the applicable checks from the repository root:
+
+```sh
+make quality-gate
+npm --prefix plugins/dsh ci --ignore-scripts
+npm --prefix plugins/dsh run check
+FLYWHEEL_TEST_NODE_BRIDGE=1 go test ./internal/drivers -run '^Test(DSH|CodexPro|ClaudeCodePro)NodeWorkerOfflineBridge$' -count=1
+npm test
+npm run build:npm
+FLYWHEEL_NPM_PACKAGES_DIR=dist-npm npm run test:install
+```
+
+| Change | Required verification |
+|---|---|
+| Go engine | `make quality-gate`: vet, formatting, tests, and coverage |
+| DSH plugin or worker | Plugin checks and the applicable Go-to-Node bridges |
+| npm installation or release | Root npm tests, a six-package candidate build, and installation of those tarballs |
+| Documentation | Links, anchors, fences, runnable examples, translation consistency, and affected embedding/package contents |
+
+The Claude bridge needs the exact optional 0.4.0 machine API in the worker's
+dependency tree. An absent-peer skip does not verify that backend. Preserve the
+reviewed source/tarball identity when using a source candidate. Codex Pro's
+bundled 0.9.0 source package is likewise pinned by its actual integrity and
+[vendor record](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/vendor/README.md).
+
+For lifecycle, state, or process changes, reproduce the Linux CI race check:
+
+```sh
+go test -race ./internal/machine ./internal/verify ./internal/watchdog ./internal/drivers ./internal/cli ./internal/modules ./internal/diagnostic -count=1
+```
+
+For changes to session quality or the evaluation harness, use the fixed offline
+paired scenarios described in [Session evaluation](session-evaluation.md):
+
+```sh
+make build
+FLYWHEEL_EVAL_BINARY="$PWD/flywheel" npm run test:sessions
+```
+
+Default tests exercise real Git, processes, workers, and public adapter packages
+with offline fixtures. Installation tests consume actual candidate tarballs in an
+isolated registry and user directory; desktop registration uses a CLI fixture.
+Dependencies require registry access or the documented verified fixture. These
+checks do not establish live account access, model quality, subscription quota,
+or a real Mac desktop pass.
+
+CI uses the same candidate on Ubuntu and macOS, with race checks on Linux. Report
+what actually ran: unavailable CI remains unavailable, and cross-compiling a Mac
+binary does not establish its runtime behavior. Stop additional testing once the
+applicable gates and concrete remaining risks are resolved.
+
+## Keep documentation organized
+
+Documentation changes belong in the same PR as the behavior they describe. Identify
+which guides are affected before implementation, then update those guides in both
+languages. A narrow change does not require rewriting every guide or running every
+repository test.
+
+### Use the right source for each claim
+
+| Claim | Authoritative source | How to use it |
+|---|---|---|
+| Architecture, responsibilities, and invariants | [System design](../design.md), especially its design invariants | Treat these as intended constraints, not optional descriptions. |
+| Legal fields, types, required values, and wire formats | [Schemas and templates](https://github.com/ckanner/flywheel/tree/main/templates), the relevant parser, and [worker protocol](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/PROTOCOL.md) | Check examples against the applicable schema and implemented interface. A schema accepting a field does not prove a backend supports it. |
+| Defaults, precedence, migration, and model bindings | [Templates embedded from the current source revision](https://github.com/ckanner/flywheel/tree/main/templates) and [configuration parsing and normalization](https://github.com/ckanner/flywheel/tree/main/internal/config) | For an installed release, also verify that version's actual templates and `config inspect` output. Distinguish defaults, omitted-field compatibility, and the user's effective configuration; an older installation cannot establish new source defaults. |
+| CLI, worker, and desktop behavior | Current [CLI](https://github.com/ckanner/flywheel/tree/main/internal/cli), [drivers](https://github.com/ckanner/flywheel/tree/main/internal/drivers), and [DSH plugin](https://github.com/ckanner/flywheel/tree/main/plugins/dsh) implementation and relevant tests | Verify commands, lifecycle boundaries, permission support, and UI labels against the implemented path. |
+| Packaging, release order, and automated gates | [Package manifest](https://github.com/ckanner/flywheel/blob/main/package.json), lockfiles, [scripts](https://github.com/ckanner/flywheel/tree/main/scripts), and [workflows](https://github.com/ckanner/flywheel/tree/main/.github/workflows) | Document the commands and gates that exist. A policy in prose is not evidence that CI enforces it. |
+| Completed tests, releases, or evaluations | [Dated validation records](../validation/README.md) and [evaluation evidence](../evaluation/README.md) | Limit claims to the recorded source, platform, inputs, and results; past results do not establish current registry or live-account status. |
+
+When design and implementation disagree, record the mismatch and resolve the
+intended behavior from the task's accepted requirements and design constraints.
+Correct the implementation when it violates that contract; update the design when
+an intended design change is part of the task, then align code, tests, and guides in
+the same PR. Do not silently declare the code correct by weakening an invariant,
+or describe a planned capability as implemented. If the intended behavior remains
+unresolved, state that limit instead of inventing a resolution.
+
+### Put content in its canonical location
+
+The default root and plugin `README.md` are English, with `README.zh-CN.md`
+counterparts. `README.en.md` remains a compatibility link, not another manual.
+Current user and maintainer guides use matching filenames in `docs/en/` and
+`docs/zh-CN/`, with reciprocal language links and the appropriate documentation index.
+
+| Content | Canonical location |
+|---|---|
+| Product overview and first commands | Root READMEs |
+| Current installation, workflow, configuration, and maintenance | `docs/en/` and `docs/zh-CN/` |
+| Current architecture and invariants | `docs/design.md` |
+| Design proposals and their original context | `docs/plans/` |
+| Executed checks, environments, evidence, and limits | `docs/validation/` and `docs/evaluation/` |
+| Historical reviews and superseded material | `docs/reviews/` and `docs/archive/` |
+| Package-specific interfaces and provenance | `plugins/dsh/` |
+| Rules for contributors and coding agents | The paired contribution guides and [AGENTS.md](https://github.com/ckanner/flywheel/blob/main/AGENTS.md) |
+
+This repository's documentation is separate from the `docs/<task>/` contracts and
+runtime ledger created in a target repository.
+
+### Map a change to its documentation
+
+Use the following as an impact checklist. Update the named material only where the
+change affects its claims; design/schema/protocol changes also follow their own
+contract rules.
+
+| Change | Documentation to inspect and update when affected |
+|---|---|
+| Installation, upgrade, prerequisites, or setup | Root and plugin READMEs, `getting-started.md`, installation examples, and package contents |
+| CLI commands, control responses, workers, or backend support | `getting-started.md`, `workflow.md`, relevant backend guide, plugin README/`PROTOCOL.md`, and affected skill instructions |
+| Configuration, defaults, accounts, models, or permissions | `configuration.md`, `model-policy.md`, relevant README tables, actual template explanations, and migration instructions |
+| Scheduling, worktrees, execution locations, or delivery | `workflow.md`, `configuration.md`, `flow-console.md`, design sections, and affected skills |
+| Session reuse, recovery, handoff, or accounting | `session-recovery.md`, configuration/workflow/console sections, design, and affected worker contracts |
+| Desktop UI, task discovery, or operator controls | `flow-console.md`, plugin READMEs, and getting-started instructions that name the UI |
+| Evaluation tools, scenarios, or result interpretation | `session-evaluation.md` or `jev-shadow.md`, their input/output contracts, and dated evidence when new checks actually run |
+| Package layout, licenses, or release behavior | `releasing.md`, relevant installation instructions, manifests/lockfiles, packaged links, and applicable license/provenance notices |
+| A documentation move, rename, or heading change | Both documentation indexes, language links, all incoming paths/anchors, package lists, embedding references, scripts, and tests |
+| Contributor or AI operating rules | [AGENTS.md](https://github.com/ckanner/flywheel/blob/main/AGENTS.md), both contribution guides, and their navigation; keep the requirements consistent |
+
+The affected English and Chinese guides must ship in the same PR. Translate the
+meaning, not just the headings: commands, model IDs, JSON fields, examples, defaults,
+permissions, failure behavior, and capability limits must agree. A translation must
+not promise a broader capability or hide a limitation present in the other language.
+
+### Maintain readable structure and reliable history
+
+Update the section that owns a behavior; add a named subsection only when needed.
+Keep one page title, a logical heading hierarchy, short introductions, typed code
+fences, readable tables, and blank lines around headings and lists. Label fragments
+and placeholders, and use consistent terminology for project workspace, execution
+directory, task, packet, and session. Write concrete instructions rather than a
+conversation transcript. Do not prepend development updates to introductions or
+append unrelated status paragraphs after the license. Release changes belong in
+`CHANGELOG.md`; dated execution evidence belongs in validation records.
+
+Historical plans, reviews, archives, and validation records retain their original
+language and dated context. Preserve recorded dates, commits, trees, versions,
+hashes, inputs, platforms, and pass/fail/skip/not-run results. Correct a historical
+error with an explicitly labelled correction that identifies what changed and why;
+do not silently rewrite an old outcome or replace its candidate identity with a
+new one. Later completion belongs in a new dated record, linked from the old record
+when useful. Historical material does not need duplicate translations, but indexes
+must make its language and status clear.
+
+### Validate the affected documentation
+
+Before requesting review, check the items relevant to this change:
+
+- [ ] Update the owning section and affected English/Chinese counterparts in the
+  same PR, with equivalent meaning, matching filenames, and reciprocal language links.
+- [ ] Verify behavior and default claims against the relevant design, CLI, schema,
+  and source templates; support completed-test claims with matching dated evidence.
+  State unresolved differences and validation limits.
+- [ ] For moves or heading changes, use `rg` to check incoming paths and anchors in
+  guides, READMEs, skills, template embedding code, manifests, scripts, and tests.
+  Resolve links from the referring file; preserve historical immutable commit links.
+- [ ] Check local links, anchors, headings, fences, JSON/YAML examples, and safe shell
+  syntax as applicable; run `git diff --check`. Use a repository documentation checker
+  only if one exists; identify manual or ad hoc checks accurately.
+- [ ] For package or embedding changes, inspect the relevant build/pack output and
+  links in the actual candidate. Include relative-link targets or use repository URLs
+  for source-only material; an old tarball cannot verify newly edited documentation.
+- [ ] Record actual passed/failed/skipped/not-run results, methods, environments, and
+  applicable candidate identity in the PR. Do not imply unconfigured CI checks or
+  validation beyond the evidence; apply only gates relevant to the change.
+
+Use source/help inspection, syntax checks, or isolated fixtures for examples. Do not
+run live models, change accounts, install into real user profiles, publish, or deploy
+merely to check documentation; those actions require an already authorized task scope.
+
+## AI-assisted contribution workflow
+
+1. Establish the current task scope and existing authorization. Read applicable
+   repository instructions, inspect the branch, HEAD, and dirty work, and preserve
+   unrelated edits. Reuse the intended PR/worktree when continuing a task.
+2. Inspect the relevant authoritative sources and identify documentation impact
+   before implementation. Separate current behavior, proposed changes, and historical
+   evidence; surface unresolved design/code differences.
+3. Implement the scoped change and its affected bilingual documentation in the same
+   PR. Preserve the engine's state ownership, frozen contracts, and user customizations.
+4. Run the applicable checks and resolve concrete failures. Do not expand a small
+   documentation change into unrelated runtime work or live-account experiments.
+5. Review the final diff, relevant branch/base changes, translations, references, and
+   verification evidence. Recheck any conclusions invalidated by later edits.
+6. Complete the authorized commit/push/PR work and report the result. Reuse prior
+   authorization without asking again for the same action; a request for a PR alone
+   does not authorize merging, publishing, deploying, or changing repository visibility.
+
+## Prepare a reviewable PR
+
+Explain the concrete problem, the change and resulting behavior, the affected
+bilingual guides, and any intentionally unchanged documentation whose relevance is
+not obvious. Review the final diff and evidence independently of an implementing
+model's completion claim. Follow active merge requirements and the user's
+authorization; preserve required gates and repository settings.
+
+Record each applicable check as **passed**, **failed**, **skipped**, or **not run**,
+including the command/method, relevant environment, and reason for skipped or
+unavailable checks. Distinguish local evidence from remote CI and live validation.
+For package or release work, record the tested candidate's source commit/tree,
+snapshot hash, tarball integrity, and dirty/clean status as applicable. Do not attach
+results from a different source or candidate to the PR's final state without stating
+that limitation. Source merge and npm publication remain separate operations.
+
+## Release changes
+
+Follow the [release guide](releasing.md). All six Flywheel packages share one exact
+version with exact internal dependencies and the pinned Codex Pro runtime. Build
+once from final clean source and test those tarballs. Preserve the source commit,
+tree, snapshot hash, and package integrity values; the release tag must identify
+that source. Do not relabel a dirty candidate as a clean release or rebuild
+different bytes for a published version.
+
+Use the repository's release scripts for candidate checks, publication, registry
+verification, and promotion. Publish platform packages and the plugin before the
+meta package, test the exact registry version before moving `latest`, and verify
+all six tags and integrities. A partial publication resumes with the same
+candidate. Manual publication requires its own explicit authorization and an
+accurate record of completed and unavailable checks.

package/docs/en/flow-console.md

@@ -1,28 +1,68 @@
-# Flywheel workflow console
+# Workflow console
 
-This guide describes the current source. Source, development candidates, local installation and npm publication are separate acceptance boundaries. Keep the CLI, platform packages and DSH plugin at one version.
+[Documentation](../README.md) · English · [简体中文](../zh-CN/flow-console.md)
+
+The DSH Flywheel view brings task selection, workflow stages, configuration, session
+interaction, and delivery into one place. Keep the CLI, platform packages, and DSH
+plugin at the same version. For installation, see [Getting started](getting-started.md).
 
 ## Find a task without entering paths
 
-The canvas starts with task selection. One registered task belonging to the current DSH conversation opens automatically; multiple tasks require a choice. Terminal runs also record DSH's host session ID. This is discovery metadata, never authorization. The UI reads Go state after finding an index entry; the index is not proof of liveness or completion.
+The canvas starts with task selection. One registered task belonging to the current DSH conversation opens automatically; multiple tasks require a choice. Terminal runs record DSH's host session ID when it is available. This is discovery metadata, never authorization. The UI reads Go state after finding an index entry; the index is not proof of liveness or completion.
 
 Older records without a host ID remain selectable under Recent tasks on this computer. Selection performs a read-only status query and associates the task with the conversation. Refreshing the list does not start, retry or replace a manually selected task. Read failures retain the existing canvas; unresolved operations still require reconciliation against their original task.
 
-There are no editable task/project path fields. The assistant and engine supply the location; known workspace, task-record location and branch values appear as read-only information, while missing values are omitted. The task folder contains the specification, acceptance checks and progress; the workspace is the actual execution project/worktree. A prepared task can be associated by the assistant using read-only status and then selected from the list.
+There are no editable task/project path fields. The project workspace remains the original repository; the execution directory may be a task checkout or independent Worktree. These locations are displayed separately when known. The task folder contains the specification, acceptance checks and progress. A prepared task can be associated using read-only status and then selected from the list.
+
+DSH keeps the original repository in the Session header and switches the current execution directory through its public API. The desktop Host periodically attaches Flywheel SDK sessions to matching existing projects; task status also ensures the original project is registered. It does not create a desktop workspace for every packet Worktree or rewrite old Session headers. Probes use temporary persistence, leaving no new user sessions. Native Providers start sessions in the project; task prompts name the actual execution directory for every shell/file operation. Backends unable to separate a `workspace-write` sandbox root reject that combination before dispatch instead of widening permissions. Full access and supported read-only modes retain their actual semantics.
+
+Loading a skill does not start the engine. `flywheel-task` prepares the appropriate contract and invokes either the bounded investigation control or `flywheel_launch` for implementation. A preparation/proposal-only response must explicitly say execution was not started. Single-stage skills query `flywheel_control status` afterward to associate their canvas, or disclose the exact path when that tool is absent rather than claiming association.
+
+| Conversation entry | Does it start the engine? | How the UI finds the task |
+|---|---|---|
+| `/flywheel-new <goal>` | Prepares contracts for review only | Before handing over the proposal, the assistant registers a candidate through read-only `status`; an uninitialized task shows its identity and location, not execution progress |
+| `/flywheel-run <task directory>` | Starts or resumes an existing task | Start and query the original task path to associate it with the conversation; select the intended task when there are multiple candidates |
+| `/flywheel-task <goal>` | Prepares, then starts | Launch and associate through `flywheel_launch`, then check status |
 
-Loading a skill does not start the engine. flywheel-task prepares and calls flywheel_launch; a research/proposal-only response must explicitly say the engine was not started. Single-stage skills query flywheel_control status afterward to associate their canvas, or disclose the exact path when that tool is absent rather than claiming association.
+`new → run` and `task` use the same engine; the canvas is not exclusive to one
+skill. Writing task files alone does not register a view, and a failed association
+query must not be replaced with launch merely to populate the canvas. Report an
+unavailable association tool explicitly. Tasks actually run from a standalone
+terminal remain selectable under Recent tasks on this computer.
+
+While the canvas is visible, registered-task discovery refreshes every five seconds.
+An observed running task refreshes status every two seconds, backing off to ten
+seconds after an unsuccessful response. Hidden documents skip those requests.
+Refresh is read-only and does not replay uncertain operations.
 
 ## This stage versus the full workflow
 
-When run.kind and control.kind identify the same single-stage operation, This run shows its recorded outcome. A review-only run defaults to **L1 → Review**, including the recorded verdict and score, while stating that overall delivery is not complete. Switch to Full workflow for the larger graph.
+When `run.kind` and `control.kind` identify the same single-stage operation, This run shows its recorded outcome. A review-only run defaults to **L1 → Review**, including the recorded verdict and score, while stating that overall delivery is not complete. Switch to Full workflow for the larger graph.
 
 Continue workflow is behind an explicit disclosure. A passed stage does not start subsequent stages or mark the task completed. Failed, cancelled and unknown operations cannot inherit an older green verdict. Run ID, HEAD and digests are collapsed under Run details and file locations.
 
+## Investigation before implementation
+
+A task with a preparation record and no implementation state opens the investigation
+panel. It shows the goal, action budget, collected observations, truncated excerpts,
+decision receipts, and the evidence report. Continue investigation submits the current
+revision to Go; a pending invocation instead offers reconciliation of the original
+receipt. Unknown control results require status reconciliation before another mutation.
+Stop waits for the running owner to settle; it cannot turn a missing action receipt
+into a confirmed cancellation.
+
+The panel does not offer ordinary code-workflow launch while the task is in preparation.
+`awaiting-report` asks the host assistant to submit an evidence-based analysis; it is
+not implementation completion. A report-only goal ends with that report. An already
+authorized repair can proceed after a supported report and a valid Spec are prepared,
+retaining the original scope and usage. See [bounded investigation](investigation.md)
+for the supported read/search actions, command protocol, and handoff requirements.
+
 ## Configuration
 
-In an existing DSH conversation view, Flywheel remains after Statistics; the blank new-session landing page does not yet show these conversation views. Its pages are Workflow canvas, Global/project configuration, and Runs and comparison. Global settings require no task directory. Project settings target the selected Git root. Discovery still selects one complete file in task → project → global → embedded order; it does not deep-merge files.
+In an existing DSH conversation view, Flywheel remains after Statistics; the blank new-session landing page does not yet show these conversation views. Its navigation tabs are Workflow, Run history, and Configuration. Global settings require no task directory. Project settings target the selected Git root. Discovery still selects one complete file in task → project → global → embedded order; it does not deep-merge files.
 
-Opening Configuration automatically reads the selected scope. Workflow policy, model assignments, budget/retries and JEV shadow advice have separate sections. Save and Discard appear beside the form only after edits. Ordinary saving takes one click; first enabling JEV confirms the task-summary transfer boundary. Serial mode omits concurrency controls. Minutes and seconds are converted precisely to engine millisecond fields.
+Opening Configuration automatically reads the selected scope. Workflow policy, model assignments, budget/retries and JEV shadow advice have separate sections. Save and Discard appear beside the form only after edits. Ordinary saving takes one click; first enabling JEV explains local capture and the separate explicit evaluation transfer. Serial mode omits concurrency controls. Minutes and seconds are converted precisely to engine millisecond fields.
 
 More configuration actions provides reload and installed-default restoration. Scope changes or reloads first disclose unsaved drafts; restoring defaults loads a pending full replacement before saving. Failures retain the draft and an uncertain save requires reconciliation. Go checks file identity, backs up the original and publishes atomically. A running engine retains its snapshot. The displayed source is file-level: task → project → global → installed defaults selects one file, not a per-field overlay. New files start from the installed template.
 
@@ -30,6 +70,11 @@ Resources include ChatGPT through DSH or Codex Pro, Kimi Code, DeepSeek Account
 
 `permissions.bindings` overrides `loops.<role>`, `routes.<route>` or `judge-panel`. Unspecified bindings use the global policy. History overrides are role-based: execution routes share the execute policy while each packet keeps its own session. Scoped continuation requires the same task, role, goal and eligible binding; fresh also retains invocation-safety records.
 
+The optional [JEV shadow evaluator](jev-shadow.md) is disabled by default. Enabling
+it captures a local task summary; only an explicit `shadow run` sends it for evaluation.
+Advice does not select workflow policy. Investigation decisions use a separate,
+explicit policy described in the [investigation guide](investigation.md).
+
 ## Canvas and operations
 
 The left-to-right overview groups Plan/decomposition, scheduling, task branches, integration/final checks and PR/Merge. Selecting a node opens view-local Progress, Sessions and Run configuration details. Open task workflow drills into Execute, L1, Review and Git delivery; integration and remote delivery groups also expand. Colors have text labels. Identity, project/worktree, branch, HEAD, run ID, bindings and evidence come from actual receipts.
@@ -48,17 +93,19 @@ Node operation confirmation freezes the observed revision; a changed snapshot in
 - Continue workflow resumes the persisted Full or ultraWork/Quick policy.
 - Stop waits for managed work to settle; closing a view is not a stop.
 
-Explicitly independent packets with satisfied dependencies can be run ahead in isolated worktrees. Integration changes invalidate old acceptance. Each asynchronous node operation records running/passed/failed/cancelled and its reason. Quick retains deterministic checks and independent final Review; omitted Plan/Judge stages are not presented as passes.
+Explicitly independent packets with satisfied dependencies can be run ahead in their registered execution directories, subject to the selected worktree policy. Integration changes invalidate old acceptance. Each asynchronous node operation records running/passed/failed/cancelled and its reason. Quick retains deterministic checks and independent final Review; omitted Plan/Judge stages are not presented as passes.
 
 ## Parallel execution
 
+### Eligibility and limits
+
 Read `flywheel template scheduler-policy.schema.json` for the current fields and bounds. For example:
 
 ```json
 {"scheduler":{"mode":"parallel","max-parallel":2,"providers":{"deepseek-account":1}}}
 ```
 
-Provider-limit keys are account channel names. Eligibility comes from frozen packet contracts:
+Provider-limit keys are actual configuration channel names. The example uses the inline template's `deepseek-account`; a binding using `deepseek-account-sdk` needs that key instead. Eligibility comes from frozen packet contracts:
 
 ```yaml
 schedule:
@@ -68,10 +115,20 @@ schedule:
 
 Dependencies reference earlier known packet IDs. Writes are normalized relative paths or directory prefixes, without globs or escapes. Include ordinary tests/configuration and account for shared test resources. Undeclared independence, overlapping scopes and live-credential units remain serial.
 
-Only Execute/L1 run concurrently. Each unit has a worktree; one Go coordinator serializes CAS writes and accounting. Hard budgets admit only one model call at a time, retaining its slot through durable accounting. Other modes enforce total and channel concurrency. Cancellation awaits every started worker.
+### Execution directories
+
+Configuration → Workflow policy → Automatically manage task Worktrees is on by default (`worktree.enabled`). It controls automatic directory creation/management independently from parallel scheduling. The installation default allows parallel execution with a limit of two; existing complete files without `scheduler` remain serial, as do explicit serial settings. Parallel automatic management requires isolated worktrees and stops if creation fails; the legacy serial path can record an in-place fallback. With automatic management off, tasks may run concurrently in the task checkout or choose their own Worktrees. Shared directories do not provide file isolation: write-scope conflicts, candidate drift and failed acceptance still stop progress.
+
+To select another execution Worktree, the executor first prepares a clean checkout of the same repository and task baseline, unclaimed by another unit in this workflow and with a branch not shared by multiple Worktrees, then returns only `{"flywheelExecutionDirectory":{"cwd":"/absolute/worktree","branch":"actual-branch"}}` before implementation. Go validates and records it; the next invocation, tests, Review and delivery follow that directory. Registration is not task completion and its model usage is still billed. External Worktrees are retained. A prompt-only directory claim or edited state file cannot replace this registration.
+
+Independent Worktrees permit concurrent Execute/L1. Shared checkouts run Execute concurrently, then verify and review serially after all workers finish. One Go coordinator serializes CAS writes and accounting. Hard budgets admit only one model call at a time, retaining its slot through durable accounting. Other modes enforce total and channel concurrency. Cancellation awaits every started worker.
 
 Review, integration and milestone gates remain serial. A combined candidate is revalidated after incorporating earlier work. Bounded execution failures retain their escalation policy. Integration conflicts and failed gates preserve the worktree and evidence. Write scopes are orchestration/acceptance contracts; full access is not an OS sandbox.
 
+### Shared-checkout batches
+
+When a batch shares one checkout, all executor calls finish before L1 and independent Review validate the complete combined candidate. Changes are projected onto declared scopes; undeclared and forbidden paths still fail. This does not attribute filesystem writes to individual processes. Repairs invalidate earlier proofs. Only after every peer passes can code be committed and all completions published in one state CAS; failed publication never optimistically completes a subset. Mixed batches deliver the shared checkout first, then revalidate and integrate external Worktrees. Manual integration/final checks cannot bypass the batch barrier; resume the complete workflow. The canvas shows the cohort and previous error.
+
 ## Controlled Provider session interaction
 
 Read latest response opens the exact digest-bound receipt, not an invented native history path or a claim of complete provider history.
@@ -91,7 +148,7 @@ Ledger storage v2 is accepted by the new engine alongside legacy v1. Older engin
 
 ## Discovery and comparison
 
-CLI and desktop starts register run IDs. A conversation retains multiple confirmed task associations. The index lives in runs/ beside the global configuration, optionally overridden by absolute FLYWHEEL_RUNS_DIR. It shows the latest 100 registrations and never scans the disk. Query Go again for liveness.
+CLI and desktop starts register run IDs. A conversation retains multiple confirmed task associations. The index lives in `runs/` beside the global configuration, optionally overridden by absolute `FLYWHEEL_RUNS_DIR`. It shows the latest 100 registrations and never scans the disk. Query Go again for liveness.
 
 Run history uses a selection list with adjacent details for operation kind, branch, HEAD, contract/configuration conditions, elapsed time and newly observed attempts, failures and deliveries. Selecting a record does not launch it; opening its canvas refreshes current Go state. Metrics scope chooses the selected run or all calls for its task, including legacy observations. The reference compares conditions without changing the metrics target. Invocation/receipt reconciliation precedes aggregation; late receipts keep their original attribution and are not double-billed. A group with entirely missing cost shows Not reported, not $0.
 
@@ -107,4 +164,9 @@ Merge rechecks the PR, head, base and checks, using `--match-head-commit`. It ne
 
 Retries reconcile existing PR/merge results before mutations. Missing receipts remain unknown. Remote state is separate from local engine completion. Publication must bind the actual merge commit and artifacts for its own validation; Merge does not automatically publish npm packages or deploy.
 
-The configuration panel also exposes default-off **JEV shadow evaluation (optional)**. See the [JEV guide](jev-shadow.md) for the switch, transmitted data and nonblocking failures. This requires the 0.30.1 CLI/plugin.
+## Related guides
+
+- [Configuration](configuration.md): complete files, model bindings, permissions, and scheduling.
+- [Workflow](workflow.md): preparation, execution, and PR review checkpoints.
+- [Investigation](investigation.md): bounded evidence collection, reports, and optional JEV decisions.
+- [Recovery](session-recovery.md): durable receipts and unresolved invocation handling.