sortie-dogs 0.1.11 → 0.2.2

package/README.md

@@ -1,283 +1,348 @@
-# Sortie-dogs
-
-**Give OpenCode a task; get a bounded, validated implementation loop instead of an open-ended agent run.**
-
-> **Project status: Experimental / unsupported.** No stability, compatibility,
-> or support guarantees are provided. Mk2A2 remains the canonical internal workflow.
-
-[![npm](https://img.shields.io/npm/v/sortie-dogs)](https://www.npmjs.com/package/sortie-dogs)
-[![license](https://img.shields.io/npm/l/sortie-dogs)](LICENSE)
-[![Node.js](https://img.shields.io/node/v/sortie-dogs)](https://www.npmjs.com/package/sortie-dogs)
-
-![Sortie-dogs coordinating a bounded implementation workflow](https://raw.githubusercontent.com/zufall-upon/Sortie-dogs/main/docs/assets/sortie-workflow.gif)
-
-Sortie-dogs is an opt-in OpenCode orchestration plugin. It turns a task into a
-scoped plan, parallel investigation, dedicated implementation, canonical
-validation, and evidence-backed completion—while preserving standard OpenCode
-agents and settings.
-
-Requirements: Node.js 22.6 or newer, npm, and OpenCode.
-
-Guides: [日本語](docs/guide-ja.md) · [简体中文](docs/guide-zh-CN.md)
-
-## Quick start
-
-Install the public npm package in the project and generate the project-local
-OpenCode runtime files:
-
-```sh
-npm install --save-dev sortie-dogs
-npx sortie-dogs init .
-```
-
-Alternatively, install the CLI globally and initialize OpenCode's global
-configuration:
-
-```sh
-npm install --global sortie-dogs
-sortie-dogs init --global
-```
-
-This installs the canonical runtime assets in OpenCode's global configuration,
-so `dog-coordinator` can be selected from other projects without project-local
-initialization. Global initialization and project-local initialization are
-separate: `sortie-dogs init .` still writes runtime files only into that
-project. Project-local configuration and the plugin bridge below remain
-available when a project needs its own settings or dependency.
-
-`dog-coordinator` and `dog-scout` default to `openai/gpt-5.6-luna`. To use a
-different model for both roles, save this as `.opencode/sortie-dogs.json`:
-
-```json
-{
-  "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. Then create
-`.opencode/plugins/sortie-dogs.ts` as the OpenCode plugin bridge:
-
-```ts
-export { SortieDogsPlugin } from "sortie-dogs/plugin";
-```
-
-OpenCode discovers the bridge automatically; no `plugin` entry in
-`opencode.json` is required. 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.
-
-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" }
-}
-```
-
-- `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.
-- `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 single model every worker role resolves to.
-  It defaults to `openai/gpt-5.6-sol` with variant `xhigh`; declare your own when
-  that model is unavailable. Worker roles always resolve to this one target and
-  cannot be routed per role.
-
-## Why Sortie-dogs
-
-- **Focused when invited, invisible otherwise.** Activate it with `/sortie` or
-  select `dog-coordinator`; ordinary OpenCode sessions remain unchanged.
-- **Parallel context without uncontrolled fan-out.** Every worker handoff uses
-  exactly three bounded scouts before implementation begins.
-- **Writes stay inside the assignment.** Exact source or operation manifests
-  gate edits and handoffs.
-- **One accountable implementation path.** A dedicated Sol worker handles
-  implementation, remediation, and blocker resolution.
-- **Evidence before completion.** Canonical validation, risk-based review, and
-  terminal evidence gate coordinator-owned completion and commits.
-- **Long work can recover.** Restart recovery and bounded compaction continue
-  from retained handoff context rather than silently starting over.
-
-## 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 ×3: investigation complete
-dog-worker: implementation complete
-validation: npm test — PASS
-review: skipped — low risk
-dog-coordinator: completion evidence accepted
-```
-
-## The workflow
-
-1. **Brief and plan** — `dog-coordinator` turns the request into acceptance
-   criteria, a write manifest, and validation requirements.
-2. **Exactly three scouts** — bounded, read-only investigation collects
-   complementary evidence without expanding the write scope.
-3. **Dedicated worker** — the Sol worker implements only the approved manifest
-   and also owns scoped remediation or blocker resolution.
-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. **Coordinator completion** — only the coordinator closes the loop and owns
-   any commit after manifest, validation, review, and evidence gates pass.
-7. **Bounded continuation** — restart recovery and compaction handoffs preserve
-   progress; repeated batches remain bounded rather than becoming endless
-   delegation.
-
-## 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.
-
-## Model routing
-
-`dog-coordinator` and `dog-scout` default to `openai/gpt-5.6-luna` with the
-`xhigh` variant. This is the recommended balance: bounded prompts, concise
-scout evidence, and fewer unnecessary context or tool turns can reduce token
-use while preserving quality. Project-local routing can override either
-default.
-
-The `implementation`, `remediation`, `blocker-resolution`, and `dog-advisor`
-roles always use dedicated Sol `xhigh`; user configuration cannot replace those
-routes. For other explicitly routed roles, resolution is deterministic: Sortie-dogs tries
-the preferred target, then ordered fallbacks. Roles without either a built-in
-default or an explicit route keep OpenCode's already selected model.
-
-```json
-{
-  "modelRouting": {
-    "dog-coordinator": {
-      "preferred": { "model": "openai/gpt-5.6-luna", "variant": "xhigh" }
-    },
-    "dog-scout": {
-      "preferred": { "model": "openai/gpt-5.6-luna", "variant": "xhigh" }
-    },
-    "dog-advisor": {
-      "preferred": { "model": "openai/gpt-5.6-sol", "variant": "xhigh" }
-    },
-    "dog-reviewer": {
-      "preferred": { "model": "fable/opus", "variant": "thinking" },
-      "fallback": [{ "model": "provider/general" }]
-    }
-  },
-  "modelCatalog": {
-    "project": [
-      { "model": "openai/gpt-5.6-sol", "variants": ["xhigh"] },
-      { "model": "openai/gpt-5.6-luna", "variants": ["xhigh"] },
-      { "model": "fable/opus", "variants": ["thinking"] },
-      { "model": "provider/general" }
-    ]
-  }
-}
-```
-
-Save project configuration as `.opencode/sortie-dogs.json`. The `dog-advisor`
-entry above shows the built-in effective route and is not user-overridable.
-`modelCatalog`
-declares provider models and named variants that are actually available;
-Sortie-dogs does not invent, probe, or translate variants. Resolution tries the
-preferred target and then its fallbacks, rejecting an explicitly routed role
-when no candidate appears in the catalog. The advisor route is authoritative; the
-reviewer route remains an optional secondary example.
-
-`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.
-
-## Updates and migration
-
-After replacing the dependency with a newer release asset, run:
-
-```sh
-npx sortie-dogs init .
-```
-
-`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.
-
-## 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
+
+**Give OpenCode a task; get a bounded, validated implementation loop instead of an open-ended agent run.**
+
+> **Project status: Experimental / unsupported.** No stability, compatibility,
+> or support guarantees are provided. Mk2A2 remains the canonical internal workflow.
+
+[![npm](https://img.shields.io/npm/v/sortie-dogs)](https://www.npmjs.com/package/sortie-dogs)
+[![license](https://img.shields.io/npm/l/sortie-dogs)](LICENSE)
+[![Node.js](https://img.shields.io/node/v/sortie-dogs)](https://www.npmjs.com/package/sortie-dogs)
+
+![Sortie-dogs coordinating a bounded implementation workflow](https://raw.githubusercontent.com/zufall-upon/Sortie-dogs/main/docs/assets/sortie-workflow.gif)
+
+Sortie-dogs is an opt-in OpenCode orchestration plugin. It turns a task into a
+scoped plan, parallel investigation, dedicated implementation, canonical
+validation, and evidence-backed completion—while preserving standard OpenCode
+agents and settings.
+
+Requirements: Node.js 22.6 or newer, npm, and OpenCode.
+
+Guides: [日本語](docs/guide-ja.md) · [简体中文](docs/guide-zh-CN.md)
+
+## Quick start
+
+Install the public npm package in the project and generate the project-local
+OpenCode runtime files:
+
+```sh
+npm install --save-dev sortie-dogs
+npx sortie-dogs init .
+```
+
+Alternatively, install the CLI globally and initialize OpenCode's global
+configuration:
+
+```sh
+npm install --global sortie-dogs
+sortie-dogs init --global
+```
+
+This installs the canonical runtime assets in OpenCode's global configuration,
+so `dog-coordinator` can be selected from other projects without project-local
+initialization. Global initialization and project-local initialization are
+separate: `sortie-dogs init .` still writes runtime files only into that
+project. Project-local configuration and the plugin bridge below remain
+available when a project needs its own settings or dependency.
+
+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 of the OpenCode configuration the agents run under —
+`~/.config/opencode/opencode.json` for the global assets, or 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` and `dog-scout` default to `openai/gpt-5.6-luna`. To use a
+different model for both roles, save this as `.opencode/sortie-dogs.json`:
+
+```json
+{
+  "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": 3 }
+}
+```
+
+- `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.
+- `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 single model every worker role resolves to.
+  It defaults to `openai/gpt-5.6-sol` with variant `medium`; declare your own when
+  that model is unavailable or when you want a different worker effort. Worker
+  roles always resolve to this one target and cannot be routed per role.
+- `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, raise or lower `maxAutoContinues` (default `3`, maximum `10`) to
+  change the ceiling, and set `summarizeModel` to pin the compaction model when
+  the host default is unsuitable.
+
+## Why Sortie-dogs
+
+- **Focused when invited, invisible otherwise.** Activate it with `/sortie` or
+  select `dog-coordinator`; ordinary OpenCode sessions remain unchanged.
+- **Parallel context without uncontrolled fan-out.** Every worker handoff uses
+  exactly three bounded scouts before implementation begins.
+- **Writes stay inside the assignment.** Exact source or operation manifests
+  gate edits and handoffs.
+- **One accountable implementation path.** A dedicated Sol worker handles
+  implementation, remediation, and blocker resolution.
+- **Evidence before completion.** Canonical validation, risk-based review, and
+  terminal evidence gate coordinator-owned completion and commits.
+- **Long work can recover.** Restart recovery and bounded compaction continue
+  from retained handoff context rather than silently starting over.
+
+## 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 ×3: investigation complete
+dog-worker: implementation complete
+validation: npm test — PASS
+review: skipped — low risk
+dog-coordinator: completion evidence accepted
+```
+
+## The workflow
+
+1. **Brief and plan** — `dog-coordinator` turns the request into acceptance
+   criteria, a write manifest, and validation requirements.
+2. **Exactly three scouts** — bounded, read-only investigation collects
+   complementary evidence without expanding the write scope.
+3. **Dedicated worker** — the Sol worker implements only the approved manifest
+   and also owns scoped remediation or blocker resolution.
+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. **Coordinator completion** — only the coordinator closes the loop and owns
+   any commit after manifest, validation, review, and evidence gates pass.
+7. **Bounded continuation** — restart recovery and compaction handoffs preserve
+   progress; repeated batches remain bounded rather than becoming endless
+   delegation.
+
+## 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
+
+`dog-coordinator` and `dog-scout` default to `openai/gpt-5.6-luna` with the
+`xhigh` variant. This is the recommended balance: bounded prompts, concise
+scout evidence, and fewer unnecessary context or tool turns can reduce token
+use while preserving quality. Project-local routing can override either
+default.
+
+The `implementation`, `remediation`, `blocker-resolution`, and `dog-worker`
+roles always use the dedicated worker target, `openai/gpt-5.6-sol` with the
+`medium` variant. Worker effort is deliberately below review effort: source
+review is mandatory for risky candidates and returns findings the worker must
+remediate, so the loop already re-runs weak implementation work and top-of-range
+first-attempt effort mostly buys accuracy the reviewer supplies anyway. Raise
+`dedicatedWorkerModel` when you would rather pay for it up front. `modelRouting`
+cannot replace those routes, and only `dedicatedWorkerModel` moves them. For other explicitly
+routed roles, resolution is deterministic: Sortie-dogs tries the preferred
+target, then ordered fallbacks. Roles without either a built-in default or an
+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, one effort step above the worker target. A host that redeclares
+`dedicatedWorkerModel` keeps that target as its first fallback, since such a
+host may not serve the shipped model at all. Nothing here requires a particular
+vendor: both roles stay fully configurable, so declare whichever model you can
+actually serve.
+
+```json
+{
+  "modelRouting": {
+    "dog-coordinator": {
+      "preferred": { "model": "openai/gpt-5.6-luna", "variant": "xhigh" }
+    },
+    "dog-scout": {
+      "preferred": { "model": "openai/gpt-5.6-luna", "variant": "xhigh" }
+    },
+    "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": ["xhigh"] },
+      { "model": "anthropic/claude-opus-5" }
+    ]
+  }
+}
+```
+
+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.
+
+## Updates and migration
+
+After replacing the dependency with a newer release asset, run:
+
+```sh
+npx sortie-dogs init .
+```
+
+`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.
+
+## 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.