sortie-dogs 0.10.5 → 0.10.6

package/README.md

@@ -1,64 +1,20 @@
-# Sortie-dogs
-
-**A goal-preserving, adaptive execution harness for OpenCode
-that optimizes cost, time, and proof without taking your setup over.**
-
-Use OpenCode normally. Invoke Sortie only when you want
-scoped implementation, validation, review, and model routing.
-
-### Four design pillars
-
-- **Goal invariance** — Accepted outcomes and proof requirements survive delegation, continuation, and remediation. A child agent cannot silently weaken the job to make it easier to finish.
-- **Adaptive execution** — Small work stays small. Parallel workers, stronger models, and independent review are added only when task shape and risk justify them.
-- **Coexistence and portability** — Sortie activates only when invited, preserves normal OpenCode agents and settings, and keeps project-local setup as the default.
-- **Cost, time, and proof** — The objective is not maximum agent count. It is the lowest practical cost and effort for a verified outcome, with explicit evidence when work does or does not pass.
-
-### Direction for v0.10.x
-
-The v0.10.x line is being developed around an **Astra operator / Terra dogs** split. Astra is the
-top-level decision authority that protects the accepted goal, quality bar, escalation decisions,
-and final acceptance. Because Astra is expensive, it should do only the small amount of work that
-requires that level of judgment. Terra-based dogs handle most bounded planning, coordination, and
-execution. The intended result is Astra-level judgment with Terra-level operating cost.
-
-This is an architectural direction under active validation, not a demonstrated benchmark result.
-Goal and quality authority remain centralized; implementation volume does not.
-
-## Try it
-
-Requirements: Node.js 22.6 or newer, npm, and OpenCode.
-Start in your project directory. This block covers all four steps;
-the JSON belongs in the configuration file, and `/sortie` runs inside OpenCode.
-If the configuration already exists, add `sortie-dogs` to its `plugin` array
-while keeping existing entries and settings.
-
-```text
-1. Install — run in your terminal
-   npm install --save-dev sortie-dogs
-   npx sortie-dogs init .
-
-2. Add plugin — save or merge into .opencode/opencode.json
-   {
-     "plugin": ["sortie-dogs"]
-   }
-
-3. Restart OpenCode
-
-4. Start a task — enter in OpenCode
-   /sortie <task>
-```
-
-Project-local setup is recommended. `init` installs runtime assets;
-the plugin entry enables the plugin, including model routing.
-See [configuration details](#configuration) for model selection and other setup options.
-
-> **v0.10.x migration:** Give workflow instructions to **`dog-operator`**, not
-> `dog-coordinator`. `dog-operator` is the user-facing authority in v0.10.x;
-> coordinator roles are internal delegates and are not the task entry point.
-
-> **Project status: Beta.** v0.10.x is under active stabilization. Runtime
-> behavior, configuration, and runtime assets may still change before 1.0.
-
+# Sortie-dogs
+
+**A goal-preserving, adaptive execution harness for OpenCode that optimizes cost,
+time, and proof without taking your setup over.**
+
+Use OpenCode normally. Invoke Sortie only when you want scoped investigation,
+implementation, validation, review, and model routing.
+
+- **Goal invariance**: accepted outcomes and proof requirements survive delegation,
+  continuation, remediation, and restart.
+- **Adaptive execution**: small work stays small; additional agents and stronger
+  models are used only when task shape or risk justifies them.
+- **Coexistence**: Sortie activates only when selected and preserves normal
+  OpenCode agents, settings, and user-owned files.
+- **Cost, time, and proof**: the objective is a verified result at the lowest
+  practical cost and wall time, not the largest agent count.
+
 [![GitHub Release](https://img.shields.io/github/v/release/zufall-upon/Sortie-dogs)](https://github.com/zufall-upon/Sortie-dogs/releases/latest)
 [![npm](https://img.shields.io/npm/v/sortie-dogs?label=npm)](https://www.npmjs.com/package/sortie-dogs)
 [![Tests](https://github.com/zufall-upon/Sortie-dogs/actions/workflows/test.yml/badge.svg)](https://github.com/zufall-upon/Sortie-dogs/actions/workflows/test.yml)
@@ -66,586 +22,306 @@ See [configuration details](#configuration) for model selection and other setup
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/node/v/sortie-dogs)](https://www.npmjs.com/package/sortie-dogs)
 [![MIT License](https://img.shields.io/npm/l/sortie-dogs)](LICENSE)
-
-![Sortie-dogs coordinating a bounded implementation workflow](https://raw.githubusercontent.com/zufall-upon/Sortie-dogs/main/docs/assets/sortie-workflow.gif)
-
-Sortie-dogs turns selected work into a scoped plan, optional evidence gathering,
-bounded implementation, canonical validation, and evidence-backed completion.
-
-Guides: [日本語](docs/guide-ja.md) · [简体中文](docs/guide-zh-CN.md) · [テスト実行](docs/testing.md) · [CLI testing](docs/cli-testing.md)
-
-Release: [v0.10.5](https://github.com/zufall-upon/Sortie-dogs/releases/tag/v0.10.5)
-
-## Latest local benchmark case study
-
-**Completion-filtered reference values, not a successful benchmark or leaderboard claim.**
-On 2026-09-14, Bare OpenCode and Sortie-dogs v0.9.12 each collected three completed runs of the
-same frozen task, `datacurve/anko-typed-variable-bindings`. Bare needed three attempts; Sortie
-needed five because two attempts returned `INTERRUPTED`. These were separate local trial batches,
-not three matched pairs. Docker and Runta were intentionally unused.
-
-Run configuration was fixed per product configuration:
-
-- **Bare OpenCode:** standard `build` agent, `openai/gpt-5.6-sol` / `high`, with no Sortie plugin
-  or Sortie runtime assets in the effective configuration.
-- **Sortie v0.9.12:** `dog-coordinator` on `openai/gpt-5.6-terra` / `high`; observed implementation
-  children on `openai/gpt-5.6-sol` / `medium`, with the pinned Sortie package and runtime assets.
-  No Luna, Astra, or Opus messages were observed in these trials.
-
-| Metric · one frozen task | Bare OpenCode | Sortie v0.9.12 | Sortie v0.10.1 RC qualification | Sortie v0.10.3 qualification · Terra/xhigh | Sortie v0.10.4 qualification · Terra/xhigh | Sortie v0.10.5 candidate qualification · Terra/xhigh + Luna/max |
-| --- | ---: | ---: | ---: | ---: | ---: | ---: |
-| Attempts needed | 3 | 5 | 1 | 1 | 2 | 1 recorded success |
-| Completed runs compared | 3 | 3 | 1 | 1 | 2 | 1 recorded success |
-| Verified PASS | 0/3 | 0/3 | 0/1 | 0/1 | 0/2 | **1/1** |
-| Task checks · F2P | 11.1% · 3/27 | 85.2% · 23/27 | 88.9% · 8/9 | 77.8% · 7/9 | 72.2% · 5/9 and 8/9 | **100% · 9/9** |
-| Retained checks · P2P | 282/282 | 282/282 | 94/94 | 94/94 | 94/94 | **94/94** |
-| Median agent wall | 24.5 min | 25.7 min | 23.2 min · n=1 | 22.7 min · n=1 | 31.1 min · n=2 | 43.1 min · n=1 |
-| Median model steps | 43 | 39 | 41 · CLI stream only | 36 · CLI stream only | 44 · CLI stream only | 25 · CLI stream only |
-| Implementation child sessions · total | 0 | 13 | 3 | 5 | 10 | 3 |
-| Estimated API-equivalent cost · median completed run | $3.53 | $2.85 | **$4.48** · n=1 | **$3.79** · n=1 | **$3.82** · n=2 | **$1.72** · n=1 |
-| Estimated cost · completed runs | $10.69 | $9.74 | **$4.48** | **$3.79** | **$7.64** | **$1.72** |
-| Additional interrupted-attempt cost · same fixed snapshot | $0 | $6.20 | $0 | $0 | $0 | Not reported |
-| Total cost to acquire completed runs · same fixed snapshot | $10.69 | $15.94 | **$4.48** | **$3.79** | **$7.64** | Not reported |
-
-All three Bare runs passed 1/9 task checks. The three completed Sortie runs passed 7/9, 8/9,
-and 8/9. Every compared candidate retained 94/94 prior checks, but every official verifier still
-returned reward 0. The two interrupted Sortie attempts are excluded from completed-run quality,
-time, and cost aggregates; their attempt count and estimated cost remain visible above.
-
-The v0.10.1 RC value is a standalone qualification-only reference, not a fourth matched run or a
-FrontierHarness leaderboard result. It used no fresh Bare control and a localized Docker-free
-verifier. The RC label identifies an unreleased working-tree snapshot; the benchmark tarball's
-package metadata remained `0.10.0`, fixed by package SHA-256
-`67582ee023c3bd57813262e292c067a3f90f30d61c01d8caf6f91f09ae78f61d`.
-
-Its estimated API-equivalent cost is **$4.478613**: $3.23 Sol and $1.25 Terra when rounded to cents.
-The audit prices all root and descendant assistant messages: 84 priced requests, 4,215,698 tokens,
-100% pricing coverage, and no unpriced requests. It uses the product's 2026-09-14 Standard schedule
-per request, including cached input, reasoning as output, and the long-context rate band. The earlier
-delivery-incomplete package was a different source snapshot (`32dea0a3…`): it spent **$4.276578**
-across 90 priced requests and 3,704,649 tokens, with no terminal outcome or verifier. It is not folded
-into this RC's same-snapshot acquisition cost. Observed spend across both distinct snapshots was
-**$8.755191**, which is development spend rather than this RC's acquisition cost. Historical Bare and
-v0.9.12 costs retain their 2026-07-30 schedule; their cost cells are not same-rate comparisons with
-this RC estimate.
-
-The released **v0.10.3** Terra/xhigh treatment is a separate one-shot qualification, not a matched
-comparison or leaderboard result. It reached `DONE` and the localized Docker-free official verifier,
-which returned reward **0**, F2P **7/9**, and P2P **94/94**. Its full root-plus-eight-descendant audit
-prices 93 assistant requests and 4,809,706 tokens at **$3.789190** API-equivalent cost: **$2.186540**
-for Terra/xhigh and **$1.602650** for Sol/low. Pricing coverage is 100%, with no unpriced or pending
-requests. This uses the same 2026-09-14 per-request schedule; the observed host cost of $0 is not used
-as cost evidence, and the estimate is not an invoice or subscription charge.
-
-The released **v0.10.4** Terra/xhigh treatment repeats that qualification twice on the same frozen
-task, pins, and verifier. Both runs reached `DONE` with confirmed cleanup, and the localized
-Docker-free official verifier returned reward **0** with P2P **94/94** each time. F2P was **5/9** and
-**8/9**, so the single v0.10.3 observation of 7/9 sits inside this spread: neither release solves the
-task, and the per-run difference is run-to-run variance at n=1 and n=2, not a measured quality change.
-
-The **v0.10.5 candidate** switches the v0.10 implementation worker default from Sol/low to
-Luna/max. One separate qualification on the same frozen task, pins, and localized Docker-free
-official verifier reached `DONE` and returned reward **1**, F2P **9/9**, and P2P **94/94**. Agent
-wall was **2,583,374 ms** (43.1 min), the CLI stream recorded 25 model steps, and the operation
-created three implementation child sessions. Its full root-plus-five-descendant audit prices 106
-assistant requests and 8,830,131 tokens at **$1.719999** API-equivalent cost: **$1.436725** for
-Terra/xhigh and **$0.283274** for Luna/max. Pricing coverage was 100%, with no unpriced or pending
-requests. The candidate package was built before the release version bump and reported package
-metadata `0.10.4`; this is a source-snapshot reference, not a released-package measurement.
-
-The v0.10.5 column deliberately reports this one verified success only. It is not a success-rate or
-acquisition-cost aggregate, and its `Not reported` cells do not imply zero cost or zero failed
-attempts outside this recorded success.
-
-The release payload this qualification exists to check is a prompt-cache correctness fix, and that
-effect is separable from task quality. Before the fix the proposal investigation child re-sent its
-whole prompt uncached on every request, because a consumed-read counter sat in the system block and a
-system element is an absolute prompt prefix. The audit now reports per-session prefix reuse, which
-isolates exactly that failure: the v0.10.3 proposal child reused a median **0.065** of the previous
-prompt and was the only flagged session in its run, while both v0.10.4 runs reuse **0.957** and
-**0.986** and flag none. Its uncached input fell from **406,202** tokens to **213,115** and
-**285,060**, and its estimated cost fell from **$0.943508** to **$0.574788** and **$0.802139**. Whole-run
-cost is not a clean measure of the same fix, because each run performed a different amount of work:
-the two v0.10.4 runs priced 97 requests at **$3.268415** and 119 requests at **$4.368122**, both at
-100% pricing coverage on the 2026-09-14 per-request schedule.
-
-![Historical local case study: Bare completed 11.1 percent of task checks at a median estimated API-equivalent cost of $3.53; Sortie v0.9.12 completed 85.2 percent at $2.85. The one-shot v0.10.3 Terra/xhigh qualification completed 77.8 percent at $3.79. Neither configuration achieved a Verified PASS.](docs/assets/quality-cost-reference.svg)
-
-Cost audits use deduplicated root and descendant session tokens, grouped by the model that produced
-each message. Historical values retain their frozen 2026-07-30 short-context schedule; the v0.10
-qualifications use the product's 2026-09-14 per-request schedule described above. Completed-run cost shows execution
-efficiency; same-snapshot acquisition cost adds interrupted attempts. These are API-equivalent
-estimates, not invoices.
-
-The product objective is **more verified outcomes per unit of cost and time without weakening the
-accepted goal**. This small, single-task local case study does not establish that claim, isolate
-orchestration from model quality, or establish a cost advantage. Codex, Pi, and Oh My OpenCode use
-separate methodologies and are not assigned quantitative positions from these observations.
-
-[Definitions, frozen inputs, current failure status, and limitations](docs/benchmark-reference.md)
-· [Machine-readable reference values](docs/benchmarks/provisional-reference.json)
-
-## How the design is enforced
-
-The four pillars above become operational constraints rather than a second set
-of product promises:
-
-### 1. Keep the goal invariant
-
-Sortie turns the requested outcome into explicit acceptance criteria and carries
-them through planning, delegation, continuation, validation, and remediation.
-Workers receive bounded units, but unit boundaries do not redefine success. A
-child result, local process limit, or convenient partial implementation cannot
-silently remove an unmet criterion. Only an explicit user-authorized revision
-changes the accepted goal.
-
-### 2. Adapt execution to the work
-
-Small changes can use one worker and targeted validation without paying for Scout,
-parallel coordination, independent review, or a full-suite run. Larger work can be
-split into bounded units; safely independent units may use a Luna fabric DAG.
-Higher-risk candidates add stronger implementation or independent review. The
-harness expands because the task requires it, not because more agents look better.
-
-### 3. Coexist with OpenCode
-
-Use normal OpenCode normally. Sortie activates only for `/sortie` or
-`dog-coordinator`; it does not disable or replace standard agents. Project-local
-installation is the default, existing settings remain authoritative, and unknown
-user-owned runtime files are preserved. The same package can move with a project
-without requiring users to surrender their global OpenCode environment.
-
-### 4. Optimize cost, time, and proof together
-
-Lower-cost models handle bounded retrieval and parallel volume work; stronger
-models are reserved for implementation, escalation, and independent review where
-their capability can change the outcome. Writes remain scoped, and completion
-requires validation evidence rather than agent confidence. The returned Speed /
-Cost / Proof debrief makes incomplete and failed outcomes visible too. Agent count
-is an implementation detail, not the optimization target.
-
-## Designed to coexist with OpenCode
-
-Sortie-dogs adds a workflow to your existing setup rather than replacing it.
-
-- It does not disable OpenCode's native agents or replace standard roles such as
-  `build`, `plan`, `explore`, or `general`.
-- Ordinary sessions are not automatically converted into Sortie workflows.
-- Project-local initialization is the recommended setup and does not change
-  user settings.
-- Global runtime availability and cross-project reflection require separate,
-  explicit opt-in. Reflection is disabled by default.
-- Unknown or user-owned runtime files are preserved rather than overwritten.
-- Manual removal targets only known Sortie-owned runtime assets.
-
-Use OpenCode normally. Invoke the pack only when you want it.
-
-## Configuration
-
-The [Try it](#try-it) steps above are the recommended project-local installation.
-Runtime assets stay with the project. This section covers plugin behavior, model
-selection, and alternative loading after installation.
-
-Installing the runtime assets does not load the plugin, and without the plugin
-every role runs on whichever model the caller happened to use. Add the package
-to the `plugin` array in the project's `.opencode/opencode.json`:
-
-```json
-{
-  "plugin": ["sortie-dogs"]
-}
-```
-
-Restart OpenCode afterwards. A `plugin` entry must name the package, not a
-subpath: `sortie-dogs/plugin` is an import specifier, not a plugin specifier.
-
-`dog-coordinator` defaults to `openai/gpt-5.6-terra` with the `high` variant; `dog-scout` defaults to
-`openai/gpt-5.6-luna`. To pin either role to another model, save this
-as `.opencode/sortie-dogs.json`:
-
-```json
-{
-  "dedicatedWorkerModel": {
-    "model": "openai/gpt-5.6-sol",
-    "variant": "medium"
-  },
-  "modelRouting": {
-    "dog-coordinator": {
-      "preferred": { "model": "provider/model" }
-    },
-    "dog-scout": {
-      "preferred": { "model": "provider/model" }
-    }
-  },
-  "modelCatalog": {
-    "project": [{ "model": "provider/model" }]
-  }
-}
-```
-
-Replace `provider/model` with a model available to you.
-
-A project that depends on the package can load it from
-`.opencode/plugins/sortie-dogs.ts` instead of the `plugin` array:
-
-```ts
-export { SortieDogsPlugin } from "sortie-dogs/plugin";
-```
-
-OpenCode discovers that file automatically. Export the plugin and nothing else:
-OpenCode calls every runtime export of a plugin module as a plugin factory, so
-one extra export disables the whole module. Restart OpenCode, then start a task:
-
-```text
-/sortie <task>
-```
-
-Selecting `dog-coordinator` directly also activates the workflow.
-
-## The write gate
-
-The write gate is opt-in per project. Without `operation-manifest.json` in the
-project root, the plugin stays passive and never denies a tool call. Creating
-that file is how a project opts in, so the coordinator can always create it.
-
-```json
-{
-  "version": "0.1.0",
-  "task_id": "add-requested-behavior",
-  "read": ["src/feature.ts", "test/feature.test.ts"],
-  "write": ["src/feature.ts", "test/feature.test.ts"],
-  "validation": ["npm test"]
-}
-```
-
-- `write` lists the only paths a bound worker may change. A listed directory
-  covers the files under it; every other entry is an exact path.
-- `validation` lists the exact commands a bound worker may run. Build and test
-  commands cannot be classified by path, so a command is allowed only when it
-  matches a declared entry exactly. Anything else is denied as unclassified.
-- `read` documents the intended reading scope; reads are never blocked.
-
-`dog-coordinator` owns this file. A worker binds to it once per candidate with
-`sortie_bind_write_gate`, and only after the coordinator's handoff has been
-inspected. Coordinator sessions are never gated.
-
-Both documents are schema-checked before inspection and binding, and every object
-rejects unknown properties. A rejection always names the failing document, the
-exact JSON pointer, and the failing rule, for example
-`Defects: handoff /state/blocked/0 schema_type`, so the coordinator repairs that
-pointer instead of resending an unchanged document. Check a handoff before
-dispatch with the read-only `sortie_check_contract` tool, which reports the same
-defects without inspecting or binding, or with `sortie-dogs lint <handoff.json>
---manifest <operation-manifest.json>`. The two most common defects are a
-`state.blocked` list of strings instead of `{ reason, needed }` objects, and an
-operation manifest that declares anything other than `version`, `task_id`,
-`read`, `write`, and `validation`.
-
-Optional settings in `.opencode/sortie-dogs.json`:
-
-```json
-{
-  "operationManifestPath": "operation-manifest.json",
-  "handoffPaths": ["handoff.json"],
-  "readOnlyTools": ["my_mcp_search"],
-  "dedicatedWorkerModel": { "model": "provider/model", "variant": "deep" },
-  "continuation": { "enabled": true, "maxAutoContinues": 10 },
-  "reflection": {
-    "enabled": false,
-    "layers": { "run": true, "project": true, "global": false },
-    "maxInjectedTokens": 500
-  }
-}
-```
-
-The same schema may be saved globally as
-`~/.config/opencode/sortie-dogs.json` (on Windows,
-`%USERPROFILE%\.config\opencode\sortie-dogs.json`). Precedence is built-in
-defaults, global file, project file, `SORTIE_DOGS_CONFIG`, then plugin factory
-options. OpenCode plugin normalization may omit factory options, so use the
-global file for durable global settings.
-
-- `operationManifestPath` moves the manifest; the path is project-relative.
-- `handoffPaths` lists the handoff files the plugin inspects. A worker can only
-  bind after one of these files passes inspection, so an empty list disables
-  binding entirely. Relative entries are also candidate-relative in a nested
-  repository: a child candidate may use its own `handoff.json` while OpenCode is
-  opened at the parent workspace. For operational work the coordinator creates
-  that valid handoff before dispatch and sends its exact absolute path; the
-  binding child must use the built-in Read tool on it immediately before bind.
-  New coordinator contracts are emitted under the candidate-relative
-  `.sortie-dogs/contracts/` directory as `handoff.<id>.json` and
-  `<id>.operation-manifest.json`. The directory is ignored by this repository's
-  `.gitignore`; legacy root/scoped paths and configured custom paths remain
-  readable and preflight-compatible, but are never moved or deleted.
-  Remove the directory only when no Sortie run is active.
-- `readOnlyTools` adds host-specific tool names that never change files, such as
-  MCP tools. Unknown tools are denied for a bound session by default.
-- `dedicatedWorkerModel` selects the serial implementation target used by
-  `implementation`, `remediation`, `blocker-resolution`, `sol-worker-mk2a2`, and
-  `dog-worker`. It defaults to `openai/gpt-5.6-sol` with variant `medium`.
-  The installed `dog-luna-worker` fabric route remains fixed to
-  `openai/gpt-5.6-luna` with variant `max`; pointing the serial target at that
-  Luna model is invalid because it would collapse the two route identities. The
-  coordinator dispatches this role only for a ready descriptor of a prepared
-  `luna-fabric` run; a `sol-serial` run keeps `dog-worker`.
-- `continuation` bounds the batch loop. After a terminal unit and its checkpoint,
-  `dog-coordinator` calls `sortie_compact_and_continue`, which compacts the run
-  and resumes the same root session on the next independent unit. Only a root
-  `dog-coordinator` session is ever resumed: a child session is never promoted and
-  another coordinator is never adopted. Set `enabled` to `false` to keep every
-  batch manual, lower `maxAutoContinues` (default and maximum `10`) to change the
-  ceiling, and set `summarizeModel` to override the latest coordinator
-  model used for compaction. Normal OpenCode auto-compaction keeps the
-  host's auto-continue behavior; Sortie suppresses it only while its own
-  explicitly queued rollover owns the resume.
-  Every terminal root-coordinator response that does not resume another unit
-  compacts without auto-continuing, so completed tool output is not carried into
-  the next user request.
-- `reflection` is an opt-in process-prevention companion for an activated root
-  `dog-coordinator`. It is disabled by default. Run and project layers default
-  to enabled after opt-in; the cross-project global storage layer remains
-  disabled unless explicitly enabled. Child and non-coordinator sessions fail
-  closed, and `SORTIE_REFLECTION=0` is an immediate kill switch. The coordinator
-  injects the governing `REFLECTION_POLICY` only while reflection is enabled.
-  `maxInjectedTokens` budgets the dynamic `SORTIE_PROCESS_REFLECTIONS` heading
-  and persisted entry lines; the policy is outside that entry budget.
-  The coordinator
-  evaluates it only after a resolved blocker/review defect and at a terminal
-  unit, with a maximum of three records per run; routine bugs and external
-  failures are never journaled.
-
-## Example run
-
-An illustrative low-risk run stays bounded and reports its gates:
-
-```text
-You: /sortie Add the requested behavior
-dog-coordinator: manifest confirmed
-dog-scout: skipped — no concrete evidence gap
-dog-worker: implementation complete
-validation: npm test — PASS
-review: skipped — low risk
-dog-coordinator: completion evidence accepted
-```
-
-## The workflow
-
-1. **Freeze the goal and plan** — `dog-coordinator` turns the request into invariant
-   acceptance criteria, a write manifest, and validation requirements.
-2. **Optional scout** — one bounded, read-only investigation runs only for a
-   concrete pre-worker evidence gap.
-3. **Adaptive execution** — the coordinator selects one worker or bounded parallel
-   units according to task shape; workers implement only their approved manifests.
-4. **Canonical validation** — the declared test or build command must produce
-   acceptable evidence.
-5. **Risk-based review** — high-risk candidates receive independent review;
-   low-risk candidates can skip that extra pass after validation.
-6. **Goal-level completion** — only the coordinator closes the loop after every
-   accepted criterion has manifest, validation, review, and evidence coverage.
-7. **Bounded continuation** — restart recovery and compaction handoffs preserve
-   progress; repeated batches remain bounded rather than becoming endless
-   delegation.
-
-## Built to work on itself
-
-Self-improvement keeps the same scoped manifests, worker ownership, validation,
-and review gates as other work. A loaded plugin is not treated as hot-reloadable:
-source changes are validated first, then packaged into an isolated `_testenv`
-fixture and exercised through the real OpenCode CLI. Continuation and compaction
-changes must demonstrate same-session recovery and terminal completion there.
-
-`npm run test:full` is reserved for explicit release validation; ordinary
-changes run targeted tests and `npm test`. The control plane coordinating a run
-is not replaced while that run is in flight.
-
-## A visual walkthrough
-
-### Control complexity
-
-![Bounded roles and gates containing orchestration complexity](https://raw.githubusercontent.com/zufall-upon/Sortie-dogs/main/docs/assets/sortie-complexity.png)
-
-The coordinator keeps investigation, implementation, validation, and review in
-separate roles. Manifest gates keep their writes bounded even as the project
-gets more complex.
-
-### Finish with evidence
-
-![Validated work reaching coordinator-owned completion](https://raw.githubusercontent.com/zufall-upon/Sortie-dogs/main/docs/assets/sortie-complete.png)
-
-Validation and risk-based review happen before coordinator-owned completion, so
-the result returns with a concise record of what changed and how it was checked.
-
-## Scope and session guarantees
-
-The plugin is passive by default. It activates a session only when a message
-uses `/sortie` or the selected agent is `dog-coordinator`. It validates exact
-write scope through source or operation manifests and rejects invalid worker
-handoffs. Standard OpenCode agents, roles, settings, and unrelated sessions are
-preserved.
-
-On `session.idle`, the final handoff is checked and the session is released. A
-`session.deleted` event also releases it. A later request must activate the
-workflow again.
-
-One host defect is repaired in place. A subagent result is built from the last
-text part of the child's final message, so a reasoning model that closes its
-turn with an empty text part returns an empty result and the coordinator
-re-dispatches work the worker already finished. When a completed `task` result
-is empty, Sortie-dogs restores the last real assistant text from that child
-session. Non-empty results, other tools, and unreadable child sessions are left
-untouched.
-
-## Model routing
-
-Default routes split work by required capability and repeated-context cost.
-Sortie-dogs keeps retrieval on Luna, coordinator routing on Terra, and independent
-review on Sol unless the host declares another target.
-
-`dog-coordinator` defaults to `openai/gpt-5.6-terra` with the `high` variant. Coordinator quality controls
-planning and forward progress, so Terra High is the default balance between capability and cost.
-Project or global `modelRouting` can override
-this default. If the host proves Terra unavailable,
-the existing availability policy uses a configured free-tier fallback when present
-and otherwise preserves the session model.
-
-`dog-scout` defaults to `openai/gpt-5.6-luna` with the `high` variant, since
-gathering bounded evidence is retrieval rather than reasoning and that tier is
-where the curve gives the most per unit of cost. Nobody selects a model for a
-session the loop spawns, which is why delegated roles carry defaults and the
-coordinator does not. Project-local routing can override this default.
-
-The `implementation`, `remediation`, `blocker-resolution`, `sol-worker-mk2a2`,
-and `dog-worker` roles always use the stable serial target,
-`openai/gpt-5.6-sol` with the `medium` variant. `dedicatedWorkerModel` may move
-that serial target when a host cannot serve it. The installed `dog-luna-worker`
-route is separately fixed to `openai/gpt-5.6-luna` with the `max` variant. Its
-shared worker contract requires one validated fabric descriptor: the coordinator
-admits a v0.8 DAG contract with `sortie_admit_luna_fabric`, prepares it with
-`sortie_prepare_luna_fabric`, and materializes only the current ready wave, with
-at most five distinct Luna units. The complete DAG may contain up to 64 units.
-After every active artifact is verified, `sortie_advance_luna_fabric_wave`
-integrates them into a runtime-owned hidden candidate, cleans those worktrees,
-and creates fresh worktrees from that exact snapshot. After the final wave,
-`sortie_validate_luna_fabric_candidate` runs canonical validation once and
-`sortie_accept_luna_fabric_candidate` records review before one target CAS.
-Declared shared-path ownership serializes overlapping units
-across waves; unowned overlap or any admission defect routes the whole job back
-to one `dog-worker`. The fabric never duplicates one unit across lanes.
-`modelRouting` cannot replace either fixed
-route, and a serial override naming the Luna fabric model is invalid rather than
-silently collapsing both identities. Version 0.7.0 routed `dog-worker` to Luna
-Max; v0.8 intentionally preserves that history while splitting stable Sol and
-fabric Luna roles. Other explicit routes try the preferred target, then ordered
-fallbacks. Roles without a built-in default or explicit route keep OpenCode's
-already selected model.
-
-`dog-reviewer` and `dog-advisor` must never inherit the caller's model, because
-review and strategy lose their value when they run on the model that produced
-the candidate. Both default to `anthropic/claude-opus-5` when the catalog
-declares it, and otherwise fall back to `openai/gpt-5.6-sol` with the `xhigh`
-variant. That fallback uses higher effort than the Sol Medium worker because
-review has to be able to reject work the worker just produced. Moving
-`dedicatedWorkerModel` does not change consultation policy. Nothing here requires
-a particular vendor: both roles stay fully configurable, so declare whichever
-model you can actually serve.
-
-```json
-{
-  "dedicatedWorkerModel": {
-    "model": "openai/gpt-5.6-sol",
-    "variant": "medium"
-  },
-  "modelRouting": {
-    "dog-coordinator": {
-      "preferred": { "model": "openai/gpt-5.6-luna", "variant": "max" }
-    },
-    "dog-scout": {
-      "preferred": { "model": "openai/gpt-5.6-luna", "variant": "high" }
-    },
-    "dog-reviewer": {
-      "preferred": { "model": "anthropic/claude-opus-5" },
-      "fallback": [{ "model": "openai/gpt-5.6-sol", "variant": "xhigh" }]
-    },
-    "dog-advisor": {
-      "preferred": { "model": "openai/gpt-5.6-sol", "variant": "xhigh" }
-    }
-  },
-  "modelCatalog": {
-    "project": [
-      { "model": "openai/gpt-5.6-sol", "variants": ["medium", "xhigh"] },
-      { "model": "openai/gpt-5.6-luna", "variants": ["max", "high"] },
-      { "model": "anthropic/claude-opus-5" }
-    ]
-  }
-}
-```
-
-`dog-worker` intentionally has no `modelRouting` entry. It uses
-`dedicatedWorkerModel`, shared with the other stable serial implementation roles.
-`dog-luna-worker` remains a separate fixed fabric route.
-
-Save project configuration as `.opencode/sortie-dogs.json`. `modelCatalog`
-declares provider models and named variants that are actually available;
-Sortie-dogs does not invent, probe, or translate variants. The built-in catalog
-intentionally omits `anthropic/claude-opus-5`, so the preferred consultation
-model applies only after you declare it. Resolution tries the preferred target
-and then its fallbacks, rejecting an explicitly routed role when no candidate
-appears in the catalog.
-
-`dog-advisor` accepts bounded Strategy or SourceReview consultation from the
-coordinator. `dog-reviewer` independently checks high-risk candidates after
-canonical validation. Neither role implements, stages, commits, or acts as a
-user-facing worker.
-
-## Optional global availability
-
-If you intentionally want the Sortie roles available across projects, install
-the CLI and runtime assets globally:
-
-```sh
-npm install --global sortie-dogs
-sortie-dogs init --global
-```
-
-This writes canonical Sortie runtime assets to OpenCode's global configuration;
-it does not make project-local initialization global. Load the plugin from the
-global `~/.config/opencode/opencode.json` when using these assets:
-
-```json
-{
-  "plugin": ["sortie-dogs"]
-}
-```
-
-Project-local configuration and plugin loading remain available when a project
-needs its own settings or dependency.
-
-## Updates and migration
-
-After replacing the dependency with a newer release asset, run:
-
-```sh
-npx sortie-dogs init .
-```
-
-After initialization, fully restart the OpenCode host before resuming a coordinator or opening a
-fresh session. Plugin modules are process-scoped, so a new session alone cannot load the update.
-
-`init` is idempotent. It updates files owned by Sortie-dogs, migrates recognized
-older runtime files, and records the installed version in
-`.opencode/sortie-dogs.version`. Conflicting or unrecognized files remain
-untouched and initialization stops safely. User-owned configuration—including
-`.opencode/sortie-dogs.json`—and standard OpenCode files are preserved.
-
-## Maintainer releases
-
-The [release batch guide](docs/release-batch.md) covers fixed-tarball CLI verification,
-global application, resumable GitHub publication, and manual npm publication checks.
-
-## Safe manual removal
-
-There is no supported Sortie-dogs uninstall command. Remove the npm dependency
-separately, then follow the [safe manual removal guide](docs/uninstall.md) to
-delete only Sortie-dogs-owned runtime files without affecting user files or
-standard OpenCode agents.
+
+![Sortie-dogs coordinating a bounded implementation workflow](https://raw.githubusercontent.com/zufall-upon/Sortie-dogs/main/docs/assets/sortie-workflow.gif)
+
+Guides: [日本語](docs/guide-ja.md) · [简体中文](docs/guide-zh-CN.md) ·
+[Testing](docs/testing.md) · [CLI testing](docs/cli-testing.md)
+
+Release: [v0.10.6](https://github.com/zufall-upon/Sortie-dogs/releases/tag/v0.10.6)
+
+> **Beta:** v0.10.x is under active stabilization. Runtime behavior,
+> configuration, and generated assets may still change before 1.0.
+
+## Quick start
+
+Requirements: Node.js 22.6 or newer, npm, and OpenCode.
+
+Run these commands in the target project:
+
+```sh
+npm install --save-dev sortie-dogs
+npx sortie-dogs init .
+```
+
+The beta package defaults to the v0.10 profile. Add the plugin and the required
+two-level subagent depth to `.opencode/opencode.json`, preserving existing values:
+
+```json
+{
+  "plugin": ["sortie-dogs"],
+  "subagent_depth": 2
+}
+```
+
+Restart OpenCode, then run:
+
+```text
+/sortie-v010 <task>
+```
+
+Selecting `dog-operator` directly starts the same workflow. `dog-operator` is the
+only user-facing v0.10 authority. `dogs-coordinator` and every `*-v010` role are
+internal children and must not be selected as task entry points.
+
+`init` installs runtime assets; the `plugin` entry loads runtime enforcement and
+model routing. Both are required. A new session alone does not reload an updated
+plugin process, so restart OpenCode after installation or upgrade.
+
+## v0.10.x direction
+
+v0.10.x separates strategic authority from bounded operations:
+
+- `dog-operator` preserves the original request, acceptance criteria, scope,
+  review decision, and final acceptance.
+- Hidden `dogs-coordinator` investigates or advances an approved serial queue,
+  but cannot edit source, change acceptance, review, or publish.
+- `dog-worker-v010` implements one host-generated unit inside exact read, write,
+  and validation boundaries.
+- Scout, advisor, and reviewer roles are optional and bounded by an explicit
+  evidence gap, strategy trigger, or risk decision.
+
+The v0.10 profile is serial by design. The stable profile's Luna fabric and
+parallel integration path are not exposed in this profile. More agents are not a
+goal; preserving quality while reducing unnecessary expensive work is.
+
+### SWE-bench policy from v0.10.6
+
+Starting with v0.10.6, development proceeds alongside recurring SWE-bench
+measurement. This is a measurement policy, not a claim that an unrun suite passed.
+
+- Freeze the task input, package/source snapshot, model routes, budgets, tools,
+  and stop endpoint before comparing runs.
+- Freeze the candidate only after all writers stop, then grade a separate copy
+  with one pinned official verifier execution.
+- Record benchmark completion, official task correctness, and harness terminal
+  state independently. A Sortie `DONE` or review `PASS` is not an official
+  verifier reward.
+- Record agent-to-freeze and verifier time separately, plus root and descendant
+  tokens, model steps, children, cache behavior, estimated cost, and coverage.
+- Keep infrastructure failure distinct from scored failure. Small or unmatched
+  samples remain case studies, not leaderboard or general success-rate claims.
+
+The pre-v0.10.6 local benchmark condition is closed historical evidence. New
+development decisions use SWE-bench measurements collected under the frozen
+contract in [Coding benchmark completion and correctness](docs/benchmark-completion-contract.md).
+
+## Historical local case study
+
+These are completion-filtered local references on one frozen DeepSWE task,
+`datacurve/anko-typed-variable-bindings`, collected from 2026-09-14 through
+2026-09-18. They are not matched pairs or a leaderboard result.
+
+- Bare OpenCode: Verified PASS `0/3`, F2P `3/27`, median agent wall `24.5 min`,
+  median completed-run API-equivalent cost `$3.53`.
+- Sortie v0.9.12: Verified PASS `0/3`, F2P `23/27`, median wall `25.7 min`,
+  median completed-run cost `$2.85`; two additional interrupted attempts cost
+  an estimated `$6.20`.
+- Sortie v0.10.3 one-shot: Verified PASS `0/1`, F2P `7/9`, wall `22.7 min`,
+  estimated cost `$3.79`.
+- Sortie v0.10.5 one-shot: Verified PASS `1/1`, F2P `9/9`, P2P `94/94`, wall
+  `43.8 min`, estimated cost `$2.58`.
+
+The v0.10.5 result is one verified success, not a success rate. Historical rate
+schedules and endpoints differ, and the host-reported zero cost is not treated as
+a bill. See [definitions, frozen inputs, and limitations](docs/benchmark-reference.md)
+and [machine-readable values](docs/benchmarks/provisional-reference.json).
+
+## How v0.10.6 works
+
+1. **Freeze intent**: `dog-operator` preserves the complete request as ordered
+   requirements, negative constraints, quality thresholds, references, and finite
+   proposal/execution budgets.
+2. **Investigate only when needed**: a nontrivial task can send one bounded,
+   read-only proposal investigation to `dogs-coordinator`. It cannot edit, run
+   shell commands, dispatch workers, or widen its approved read prefixes.
+3. **Approve an exact plan**: the root compares the proposal with the original
+   request and approves its exact revision and hash. Uncovered requirements or
+   widened scope fail closed. A simple task with a complete known contract can
+   use the direct worker fast path.
+4. **Generate controls**: the host creates and schema-validates the handoff,
+   operation manifest, acceptance ledger, and short task reference. Models do not
+   hand-authorize their own write scope.
+5. **Execute serial units**: one unit goes directly to `dog-worker-v010`; a
+   multi-unit plan is advanced serially by hidden `dogs-coordinator`. A worker
+   binds once and can modify only declared paths and run only declared validation.
+6. **Collect host evidence**: validation identity binds source snapshot,
+   candidate, command, environment, scope, and owner. Claims in prose do not
+   become proof.
+7. **Review by risk**: high-risk candidates receive independent SourceReview;
+   low-risk review may be explicitly skipped. The reviewer is tool-free and does
+   not implement fixes.
+8. **Remediate without weakening the goal**: acceptance failures and blocking
+   review findings create a same-goal replacement from the committed candidate,
+   retaining acceptance and cumulative budget. Scope growth still requires a
+   later explicit user decision.
+9. **Accept explicitly**: only the root's successful completion operation closes
+   the run. Terminal states remain `DONE`, `INTERRUPTED`, `BLOCKED`, and
+   `NEED_DECISION`; the host-generated return report uses observed evidence.
+
+Durable profile state and hash-bound task references support restart and
+compaction recovery without reconstructing criteria from summary prose. Stale,
+foreign-root, or changed references are rejected. An optional Git lifecycle can
+create one non-overwriting branch and one explicit-path commit; it never grants
+arbitrary Git, force push, release, or publication authority.
+
+## Configuration
+
+### Profile files and precedence
+
+The default package entry is the v0.10 profile:
+
+- Command: `/sortie-v010`
+- Primary agent: `dog-operator`
+- Project settings: `.opencode/sortie-dogs-v010.json`
+- Global settings: `~/.config/opencode/sortie-dogs-v010.json`
+- JSON environment override: `SORTIE_DOGS_V010_CONFIG`
+- Runtime state: `.sortie-dogs-v010/`
+- Installed asset marker: `.opencode/sortie-dogs-v010.version`
+
+Precedence is built-in defaults, global file, project file, environment JSON,
+then plugin factory options. Unknown properties or invalid types are rejected.
+Use external v0.10 role names such as `dog-operator`, `dogs-coordinator`, and
+`dog-reviewer-v010` in `modelRouting`; do not also declare their stable aliases.
+
+Example `.opencode/sortie-dogs-v010.json`:
+
+```json
+{
+  "validationProfile": "balanced",
+  "readOnlyTools": ["my_mcp_search"],
+  "freeTierFallbackModels": ["opencode/deepseek-v4-flash-free"],
+  "modelRouting": {
+    "dog-operator": {
+      "preferred": { "model": "provider/model", "variant": "high" }
+    },
+    "dogs-coordinator": {
+      "preferred": { "model": "provider/model", "variant": "deep" }
+    }
+  },
+  "modelCatalog": {
+    "project": [
+      { "model": "provider/model", "variants": ["high", "deep"] }
+    ]
+  },
+  "continuation": {
+    "enabled": true,
+    "maxAutoContinues": 10,
+    "taskWatchdogMilliseconds": 300000
+  }
+}
+```
+
+Declare only models and named variants the host actually provides. Sortie does
+not invent, probe, or translate variant names.
+
+### Settings reference
+
+- `readOnlyTools`: additional host-specific tools known not to mutate project
+  files. Values accumulate across configuration layers. Unknown tools are denied
+  in a bound worker session.
+- `modelRouting`: preferred and ordered fallback targets by external profile role.
+- `modelCatalog`: available `project` and `global` model/variant declarations.
+- `freeTierFallbackModels`: ordered global last-resort model IDs. Default:
+  `opencode/deepseek-v4-flash-free`; `[]` disables this fallback.
+- `dedicatedWorkerModel`: canonical stable serial target, default
+  `openai/gpt-5.6-sol` / `medium`. The v0.10 profile also supplies its explicit
+  role routes below; do not infer the v0.10 worker route from this stable setting.
+- `consultation.strategy`: fixed advisor identity, optional `required`, and
+  positive `maxCallsPerCandidate`; default one call and not required.
+- `consultation.sourceReview`: risk-based review with `maxCallsPerCandidate`
+  default `1` and `maxArtifactBytes` default/maximum `30720`. Unavailable review
+  blocks only when review is required.
+- `continuation.enabled`: default `true`.
+- `continuation.maxAutoContinues`: positive integer, default and maximum `10`.
+- `continuation.taskWatchdogMilliseconds`: root inactivity while an implementation
+  Task is outstanding; default `300000`, valid range `10..1800000`.
+- `continuation.summarizeModel`: optional explicit compaction model; omission
+  reuses the latest observed root model.
+- `validationProfile`: `fast`, `balanced`, or `assurance`; default `balanced`.
+- `reflection`: accepted by the shared schema, but reflection writes are not
+  exposed by the serial v0.10 profile. Stable reflection remains opt-in and off by
+  default.
+
+The v0.10 host owns handoff and manifest controls under
+`.sortie-dogs-v010/contracts/`. Do not create a legacy root
+`operation-manifest.json` for this profile and do not edit generated controls.
+Delete `.sortie-dogs-v010/` only when no Sortie run is active.
+
+### Validation policy
+
+`validationProfile` chooses non-canonical depth:
+
+- `fast`: static checks
+- `balanced`: targeted checks
+- `assurance`: related checks
+
+Canonical proof remains canonical. Full-suite execution requires release context
+or explicit risk. Workers own static, targeted, and related checks; the root owns
+canonical and full-suite checks. An unchanged candidate, command, and environment
+reuse the same evidence instead of spending the validation budget again.
+
+### Default v0.10 routes
+
+- `dog-operator`: `openai/gpt-5.6-luna-fast` / `max`
+- `dogs-coordinator`: `openai/gpt-5.6-terra` / `xhigh`
+- `dog-worker-v010`: `openai/gpt-5.6-luna-fast` / `max`
+- `dog-scout-v010`: `openai/gpt-5.6-luna-fast` / `xhigh`
+- `dog-reviewer-v010`: `openai/gpt-5.6-terra` / `xhigh`
+- `dog-advisor-v010`: preferred declared `anthropic/claude-opus-5`, otherwise
+  `openai/gpt-5.6-sol` / `xhigh`
+
+An explicit model and variant selected in OpenCode remains authoritative for that
+session. Child role defaults fill absent native settings and may be overridden by
+valid profile routing. Review never silently inherits the implementation model.
+
+## Stable compatibility profile
+
+The earlier parallel-capable runtime remains available explicitly:
+
+```sh
+npx sortie-dogs init . --profile stable
+```
+
+Load it through a project bridge instead of the default package plugin entry:
+
+```ts
+export { SortieDogsPlugin } from "sortie-dogs/plugin/stable";
+```
+
+The stable profile uses `/sortie`, `dog-coordinator`,
+`.opencode/sortie-dogs.json`, `SORTIE_DOGS_CONFIG`, and `.sortie-dogs/`. Do not
+register stable and v0.10 from the same package installation path in one host.
+
+## Global availability
+
+Project-local installation is recommended. To expose v0.10 assets globally:
+
+```sh
+npm install --global sortie-dogs
+sortie-dogs init --global --profile v010
+```
+
+Then add `sortie-dogs` and `subagent_depth: 2` to the global OpenCode config.
+Global initialization installs assets only; it does not silently change the
+default agent or merge user settings.
+
+## Updates and removal
+
+After replacing the dependency, rerun initialization and restart OpenCode:
+
+```sh
+npx sortie-dogs init .
+```
+
+`init` is idempotent. It updates recognized Sortie-owned assets, records the asset
+version, preserves user configuration, and stops safely on unknown ownership or
+conflicting files.
+
+There is no supported uninstall command. Remove the npm dependency separately,
+then follow the [safe manual removal guide](docs/uninstall.md). Delete only known
+Sortie-owned paths; never remove the whole `.opencode` directory or use broad
+wildcards.
+
+Maintainers: the [release batch guide](docs/release-batch.md) covers fixed-tarball
+validation, global application, GitHub publication, and manual npm publication.