sortie-dogs 0.9.6 → 0.9.8

package/README.md

@@ -1,13 +1,13 @@
 # Sortie-dogs
 
-**Give OpenCode a task; get a bounded, validated implementation loop instead of an open-ended agent run.**
+**Add a bounded, cost-aware execution loop to OpenCode without taking OpenCode over.**
 
-Sortie-dogs is an execution harness for OpenCode, applying harness-engineering
-principles through mechanical write boundaries, validation, review, and bounded
-orchestration.
+Sortie-dogs is an opt-in overlay, not a replacement. It stays passive until you
+invoke `/sortie` or select `dog-coordinator`. Standard OpenCode agents and
+unrelated sessions remain available and unchanged.
 
-> **Project status: Beta.** Stable in regular use. As a pre-1.0 release,
-> configuration and runtime assets may still change between releases.
+> **Project status: Beta.** v0.9.x is under active stabilization. Runtime
+> behavior, configuration, and runtime assets may still change before 1.0.
 
 [![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)
@@ -15,47 +15,63 @@ orchestration.
 
 ![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, optional evidence gathering, one bounded implementation unit, canonical
-validation, and evidence-backed completion—while preserving standard OpenCode
-agents and settings.
+Sortie-dogs turns selected work into a scoped plan, optional evidence gathering,
+bounded implementation, canonical validation, and evidence-backed completion.
 
 Requirements: Node.js 22.6 or newer, npm, and OpenCode.
 
 Guides: [日本語](docs/guide-ja.md) · [简体中文](docs/guide-zh-CN.md) · [CLI testing](docs/cli-testing.md)
 
-Release: [v0.9.6](https://github.com/zufall-upon/Sortie-dogs/releases/tag/v0.9.6)
-
-## Quick start
-
-Install the public npm package in the project and generate the project-local
-OpenCode runtime files:
+Release: [v0.9.8](https://github.com/zufall-upon/Sortie-dogs/releases/tag/v0.9.8)
+
+## Why Sortie-dogs?
+
+### Invisible until invited
+
+Use normal OpenCode normally. Sortie activates only for `/sortie` or
+`dog-coordinator`; it does not disable or replace OpenCode's standard agents.
+
+### Spend strong models only where they matter
+
+Lower-cost models handle bounded retrieval and parallel volume work. Stronger
+models are reserved for implementation, escalation, and independent review.
+
+### Return with proof
+
+Writes stay scoped, and completion requires validation evidence. Every completed
+run can return a concise Speed / Cost / Proof debrief.
+
+## 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.
+
+## 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`:
+npx sortie-dogs init .
+```
+
+This is the recommended setup. Runtime assets stay project-local.
+
+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
 {
@@ -218,26 +234,7 @@ global file for durable global settings.
   unit, with a maximum of three records per run; routine bugs and external
   failures are never journaled.
 
-## Why Sortie-dogs
-
-- **Focused when invited, invisible otherwise.** Activate it with `/sortie` or
-  select `dog-coordinator`; ordinary OpenCode sessions remain unchanged.
-- **Evidence gathering without arbitrary dispatch ceilings.** A bounded scout resolves
-  each concrete manifest, validation, or ownership gap whenever it appears; unchanged
-  requests are not repeated.
-- **Writes stay inside the assignment.** Exact source or operation manifests
-  gate edits and handoffs.
-- **Autonomous implementation routing.** An accepted scope with at least two safe independent
-  units defaults to Luna fabric without opt-in. An explicit serial/no-parallel request wins;
-  other work uses sequential workers. The separate parallel contract remains explicit.
-- **Runtime overlap protection.** Active equal or ancestor write scopes are rejected
-  before mutation, and full validation waits until every parallel unit joins.
-- **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
+## Example run
 
 An illustrative low-risk run stays bounded and reports its gates:
 
@@ -400,7 +397,30 @@ 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
+## 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:
 
@@ -417,7 +437,12 @@ older runtime files, and records the installed version in
 untouched and initialization stops safely. User-owned configuration—including
 `.opencode/sortie-dogs.json`—and standard OpenCode files are preserved.
 
-## Safe manual removal
+## 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

package/dist/asset-version.d.ts

@@ -2,5 +2,5 @@
  * Version of the installable runtime assets. Kept in its own module so the plugin can compare an
  * installed project marker without importing every asset body.
  */
-export declare const RUNTIME_ASSET_VERSION = "0.3.81-mission-debrief-v1";
+export declare const RUNTIME_ASSET_VERSION = "0.3.84-dispatch-recovery-v1";
 export type RuntimeAssetVersion = typeof RUNTIME_ASSET_VERSION;

package/dist/asset-version.js

@@ -2,4 +2,4 @@
  * Version of the installable runtime assets. Kept in its own module so the plugin can compare an
  * installed project marker without importing every asset body.
  */
-export const RUNTIME_ASSET_VERSION = "0.3.81-mission-debrief-v1";
+export const RUNTIME_ASSET_VERSION = "0.3.84-dispatch-recovery-v1";

package/dist/core/goal-bound.d.ts

@@ -243,7 +243,7 @@ export interface GoalFlightState {
 }
 export declare class GoalBoundError extends Error {
     readonly code: "invalid" | "transition" | "budget" | "ticket" | "evidence";
-    constructor(code: "invalid" | "transition" | "budget" | "ticket" | "evidence", message: string);
+    constructor(code: GoalBoundError["code"], message: string);
 }
 export declare function goalFingerprint(value: unknown): string;
 export declare function selectGoalDelivery(input: {

package/dist/core/goal-declaration-format.d.ts

@@ -2,3 +2,5 @@
 export declare const GOAL_DELIVERY_INTENTS: readonly ["design", "registration", "implementation", "repair", "controlled-change"];
 export declare const GOAL_DELIVERY_MODES: readonly ["planning-only", "mvp-first", "repair-first", "controlled-change"];
 export declare const GOAL_DECLARATION_FORMAT: string;
+/** Normalize a shared declaration without guessing acceptance, coverage, delivery, or validation. */
+export declare function expandGoalDeclaration(value: unknown): string;

package/dist/core/goal-declaration-format.js

@@ -1,12 +1,16 @@
+import { goalFingerprint } from "./goal-bound.js";
 /** Shared planner guidance and admission enums; no inferred acceptance or dispatch authority. */
 export const GOAL_DELIVERY_INTENTS = ["design", "registration", "implementation", "repair", "controlled-change"];
 export const GOAL_DELIVERY_MODES = ["planning-only", "mvp-first", "repair-first", "controlled-change"];
-export const GOAL_DECLARATION_FORMAT = `Goal declaration belongs in the Task prompt, not in the handoff JSON or operation manifest.
+export const GOAL_DECLARATION_FORMAT = `Declare a goal once, then reference it with goal_declaration_path in the Task prompt.
+The referenced JSON may contain shared defaults and a criteria array; the host expands them privately.
+An inline ext["sortie-dogs/goal-declaration"] in the registered handoff is also supported.
+Existing accepted goals need no repeated declaration; budget-only revisions retain their criteria.
+Legacy flat goal_* fields remain supported. No need to rewrite unrelated files or repeat common fields for each criterion.
 delivery_intent must be exactly one of: ${GOAL_DELIVERY_INTENTS.join(" | ")}. Never use prose or a boolean.
 delivery_mode is a separate optional enum: ${GOAL_DELIVERY_MODES.join(" | ")}.
 Use flat key: value lines. Each criterion begins with its own goal_criterion_id: line.
-Repeat the entire flat criterion block for multiple criteria. Do not use goal_criteria, goal_acceptance.criteria,
-YAML object/list wrappers, inline { goal_criterion_id: ... }, or JSON objects for these blocks.
+For legacy flat input each criterion has a goal_criterion_id line. Prefer shared JSON defaults for multiple criteria.
 Replace every placeholder with the accepted task's actual value; preserve its acceptance and validation:
 goal_acceptance_fingerprint: <sha256: followed by exactly 64 lowercase hexadecimal characters>
 delivery_intent: implementation
@@ -31,3 +35,48 @@ goal_validation_command: <exact operation manifest validation command>
 The example's implementation/mvp-first selections apply only to an implementation without its usable path;
 select other enum values only from the accepted request. A declaration rejection launches no child.
 Repair the Task prompt's named fields, not unrelated files; retry only with the corrected declaration.`;
+/** Normalize a shared declaration without guessing acceptance, coverage, delivery, or validation. */
+export function expandGoalDeclaration(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("goal declaration must be an object");
+    const object = value;
+    if (!Array.isArray(object.criteria) || object.criteria.length === 0)
+        throw new Error("goal declaration requires criteria");
+    const defaults = object.defaults !== null && typeof object.defaults === "object" && !Array.isArray(object.defaults)
+        ? object.defaults : {};
+    const fields = ["criterion_id", "target", "entrypoint", "workload", "oracle_coverage", "build_boundary", "source",
+        "candidate", "source_binding", "candidate_binding", "fixture", "proof_scope", "expected_outcome", "validation_command"];
+    const scalar = (value) => {
+        if (Array.isArray(value))
+            return JSON.stringify(value);
+        if (typeof value === "string" && !/[\r\n]/u.test(value))
+            return value;
+        if (typeof value === "boolean" || typeof value === "number")
+            return String(value);
+        throw new Error("goal declaration field must be a single-line scalar or array");
+    };
+    const normalizedFields = (values) => Object.fromEntries(fields.flatMap(field => {
+        const found = values[`goal_${field}`] ?? values[field];
+        return found === undefined ? [] : [[`goal_${field}`, found]];
+    }));
+    const criteria = object.criteria.map(raw => {
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+            throw new Error("goal criterion must be an object");
+        return { ...normalizedFields(defaults), ...normalizedFields(raw) };
+    });
+    const identity = { criteria, delivery_intent: object.delivery_intent, delivery_mode: object.delivery_mode,
+        usable_path_established: object.usable_path_established, controlled_change: object.controlled_change };
+    const lines = [`goal_acceptance_fingerprint: ${scalar(object.goal_acceptance_fingerprint ?? goalFingerprint(identity))}`];
+    for (const field of ["delivery_intent", "delivery_mode", "usable_path_established", "controlled_change",
+        "goal_budget_units", "goal_budget_time_ms", "goal_budget_cost_usd"]) {
+        if (object[field] !== undefined)
+            lines.push(`${field}: ${scalar(object[field])}`);
+    }
+    for (const criterion of criteria) {
+        criterion.goal_criterion_id ??= `criterion-${goalFingerprint(criterion).slice(7, 31)}`;
+        for (const field of fields)
+            if (criterion[`goal_${field}`] !== undefined)
+                lines.push(`goal_${field}: ${scalar(criterion[`goal_${field}`])}`);
+    }
+    return lines.join("\n");
+}

package/dist/plugin/continuation.js

@@ -12,6 +12,7 @@
  * identity fails closed into "no automatic continuation" rather than into a guess.
  */
 import { openCodeModel } from "./model-routing-hook.js";
+import { terminalRunOutcome } from "./run-metrics.js";
 /** Plugin tool name the coordinator asset names as the direct continuation capability. */
 export const CONTINUATION_CAPABILITY = "sortie_compact_and_continue";
 /** Fallback marker, used only when the direct capability is unavailable. */
@@ -445,8 +446,8 @@ export function createContinuationHooks(client, directory, policySource, timings
         return firstCheckpoint(text)?.status;
     }
     function terminalCheckpoint(text) {
-        const status = checkpointStatus(text);
-        return status === "DONE" || status === "NEED_DECISION" || (status === "BLOCKED" && trueBlockerReport(text));
+        // Use the same terminal vocabulary as the receipt/debrief path, including INTERRUPTED.
+        return terminalRunOutcome(text) !== undefined;
     }
     function trueBlockerReport(text) {
         const checkpoint = firstCheckpoint(text);

package/dist/plugin/index.d.ts

@@ -65,6 +65,8 @@ export interface OpenCodeHooks {
     /** Continuation observes the coordinator's completed final text to honour its fallback markers. */
     "experimental.text.complete"?: (input: {
         sessionID: string;
+        messageID?: string;
+        partID?: string;
     }, output: {
         text: string;
     }) => Promise<void>;