sortie-dogs 0.1.2 → 0.1.4

package/README.md

@@ -2,6 +2,9 @@
 
 **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)
@@ -19,13 +22,29 @@ Guides: [日本語](docs/guide-ja.md) · [简体中文](docs/guide-zh-CN.md)
 
 ## Quick start
 
-Install the public npm package and generate the project-local runtime files:
+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`:
 
@@ -145,9 +164,9 @@ 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`, and `blocker-resolution` roles always use
-the dedicated Sol worker; user configuration cannot replace those routes. For
-other explicitly routed roles, resolution is deterministic: Sortie-dogs tries
+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.
 
@@ -161,8 +180,7 @@ default or an explicit route keep OpenCode's already selected model.
       "preferred": { "model": "openai/gpt-5.6-luna", "variant": "xhigh" }
     },
     "dog-advisor": {
-      "preferred": { "model": "fable/opus", "variant": "thinking" },
-      "fallback": [{ "model": "provider/general" }]
+      "preferred": { "model": "openai/gpt-5.6-sol", "variant": "xhigh" }
     },
     "dog-reviewer": {
       "preferred": { "model": "fable/opus", "variant": "thinking" },
@@ -171,6 +189,7 @@ default or an explicit route keep OpenCode's already selected model.
   },
   "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" }
@@ -179,12 +198,14 @@ default or an explicit route keep OpenCode's already selected model.
 }
 ```
 
-Save project configuration as `.opencode/sortie-dogs.json`. `modelCatalog`
+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 and reviewer routes above
-are optional secondary examples; omit them when they are not needed.
+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

package/dist/cli/main.js

@@ -21,7 +21,8 @@ const USAGE = `Usage: sortie-dogs lint <handoff.json> [<handoff.json> ...]
   [--changed-paths-from <file|->]
   [--changed-path <path> ...]
   [--format text|json] [--quiet] [--strict]`;
-const INIT_USAGE = "Usage: sortie-dogs init [project-root]";
+const INIT_USAGE = `Usage: sortie-dogs init [project-root]
+       sortie-dogs init --global`;
 class InputFailure extends Error {
     safeMessage;
     constructor(safeMessage) {
@@ -226,15 +227,29 @@ export async function run(argv) {
             process.stdout.write(`${INIT_USAGE}\n`);
             return 0;
         }
-        if (argv.length > 2 || argv[1]?.startsWith("-") === true) {
+        const global = argv[1] === "--global";
+        if (argv.length > 2 || (argv[1]?.startsWith("-") === true && !global)) {
             process.stderr.write(`${INIT_USAGE}\n`);
             return 2;
         }
         try {
-            const initialized = await initializer.initializeProject(argv[1]);
-            process.stdout.write(initialized.status === "installed"
-                ? `Initialized Sortie-dogs ${initialized.version}.\n`
-                : `Sortie-dogs ${initialized.version} is already initialized.\n`);
+            const target = global ? await initializer.resolveGlobalConfigRoot() : undefined;
+            const initialized = global
+                ? await initializer.initializeGlobal(target)
+                : await initializer.initializeProject(argv[1]);
+            if (global) {
+                process.stdout.write(initialized.status === "installed"
+                    ? `Initialized Sortie-dogs ${initialized.version} globally at ${target}.\n`
+                    : `Sortie-dogs ${initialized.version} is already initialized globally at ${target}.\n`);
+            }
+            else {
+                process.stdout.write(initialized.status === "installed"
+                    ? `Initialized Sortie-dogs ${initialized.version}.\n`
+                    : `Sortie-dogs ${initialized.version} is already initialized.\n`);
+            }
+            if (initialized.preservedLegacyPaths.length > 0) {
+                process.stdout.write(`Preserved legacy runtime files: ${initialized.preservedLegacyPaths.join(", ")}.\n`);
+            }
             return 0;
         }
         catch (error) {

package/dist/core/consultation.d.ts

@@ -0,0 +1,145 @@
+export declare const CONSULTATION_CAPABILITIES: readonly ["strategy", "sourceReview"];
+export type ConsultationCapability = typeof CONSULTATION_CAPABILITIES[number];
+export declare const CONSULTATION_ROLE_POLICY: Readonly<{
+    readonly strategy: "dog-advisor";
+    readonly sourceReview: "dog-reviewer";
+}>;
+export declare const STRATEGY_TRIGGERS: readonly ["architecture-choice", "cross-boundary-tradeoff", "material-uncertainty"];
+export type StrategyTrigger = typeof STRATEGY_TRIGGERS[number];
+export interface StrategyTriggerInput {
+    readonly candidateId: string;
+    readonly trigger?: StrategyTrigger;
+    readonly callsForCandidate: number;
+    readonly decisionAlreadyRecorded?: boolean;
+    readonly mechanicalChange?: boolean;
+    readonly sameTaskResume?: boolean;
+}
+/** Strategy is advisory, bounded to one call, and excluded when no design decision remains. */
+export declare function shouldConsultStrategy(input: StrategyTriggerInput): boolean;
+export declare const SOURCE_REVIEW_RISK_TAGS: readonly ["security", "credential", "permission", "network", "public-api", "storage-compatibility", "package", "build", "release", "migration", "concurrency", "process-io", "write-gate", "authorization"];
+export type SourceReviewRiskTag = typeof SOURCE_REVIEW_RISK_TAGS[number];
+export declare function isSourceReviewRiskTag(value: unknown): value is SourceReviewRiskTag;
+export declare function requiresSourceReview(riskTags: readonly SourceReviewRiskTag[]): boolean;
+export type SourceReviewRequirement = "SKIP_LOW_RISK" | "WAIT_CANONICAL_VALIDATION" | "REVIEW_REQUIRED" | "REVIEW_TOO_LATE" | "RISK_TAGS_INVALID";
+export interface SourceReviewRequirementInput {
+    readonly riskTags: unknown;
+    readonly canonicalValidationExit?: number;
+    readonly stagingStarted: boolean;
+}
+/** Places required review strictly after canonical PASS and before staging. */
+export declare function evaluateSourceReviewRequirement(input: SourceReviewRequirementInput): SourceReviewRequirement;
+export type ReviewAvailability = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: "REVIEW_UNAVAILABLE";
+};
+export declare function evaluateReviewAvailability(required: boolean, available: boolean): ReviewAvailability;
+export interface StrategyConsultationRequest {
+    readonly requestId: string;
+    readonly candidateId: string;
+    readonly capability: "strategy";
+    readonly agent: string;
+    readonly question: string;
+    readonly constraints: readonly string[];
+    readonly options: readonly string[];
+}
+export interface ReviewArtifact {
+    readonly schemaVersion: 1;
+    readonly candidateId: string;
+    readonly sourceFingerprint: string;
+    readonly acceptance: readonly string[];
+    readonly manifest: readonly string[];
+    readonly riskTags: readonly SourceReviewRiskTag[];
+    readonly riskBearingHunks: readonly string[];
+    readonly validation: {
+        readonly command: string;
+        readonly exit: 0;
+        readonly fingerprint: string;
+    };
+    readonly invariants: readonly string[];
+}
+export interface SourceReviewConsultationRequest {
+    readonly requestId: string;
+    readonly candidateId: string;
+    readonly capability: "sourceReview";
+    readonly agent: string;
+    readonly artifact: ReviewArtifact;
+}
+export type ConsultationRequest = StrategyConsultationRequest | SourceReviewConsultationRequest;
+export interface StrategyConsultationResult {
+    readonly requestId: string;
+    readonly candidateId: string;
+    readonly capability: "strategy";
+    readonly status: "completed";
+    readonly recommendation: string;
+    readonly considerations: readonly string[];
+}
+export interface UnavailableConsultationResult {
+    readonly requestId: string;
+    readonly candidateId: string;
+    readonly capability: ConsultationCapability;
+    readonly status: "unavailable";
+}
+export type ReviewVerdictKind = "PASS" | "MUST_FIX" | "BLOCKED";
+export type ReviewFindingSeverity = "major" | "medium";
+export interface ReviewFinding {
+    readonly severity: ReviewFindingSeverity;
+    readonly path: string;
+    readonly evidence: string;
+    readonly requiredFix: string;
+}
+export interface ReviewVerdict {
+    readonly verdict: ReviewVerdictKind;
+    readonly sourceFingerprint: string;
+    readonly findings: readonly ReviewFinding[];
+}
+export interface SourceReviewConsultationResult {
+    readonly requestId: string;
+    readonly candidateId: string;
+    readonly capability: "sourceReview";
+    readonly status: "completed";
+    readonly review: ReviewVerdict;
+}
+export type ConsultationResult = StrategyConsultationResult | SourceReviewConsultationResult | UnavailableConsultationResult;
+/** Host-owned adapters implement transport. Core never executes commands or selects providers. */
+export interface ConsultationAdapter {
+    consult(request: ConsultationRequest): Promise<ConsultationResult>;
+}
+export declare const MAX_REVIEW_ARTIFACT_BYTES = 30720;
+export type ValidationResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+    readonly bytes?: number;
+} | {
+    readonly ok: false;
+    readonly code: string;
+};
+/** Strict bounded schema; unknown fields and opaque/raw payloads are rejected. */
+export declare function validateReviewArtifact(value: unknown, maxBytes?: number): ValidationResult<ReviewArtifact>;
+export declare function validateReviewVerdict(value: unknown): ValidationResult<ReviewVerdict>;
+export interface ReviewGateInput {
+    readonly phase: "initial" | "verification";
+    readonly candidateId: string;
+    readonly currentSourceFingerprint: string;
+    readonly artifact: unknown;
+    readonly verdict: unknown;
+    readonly reviewedFingerprints: readonly string[];
+    /** The configured budget applies independently to each explicit review phase. */
+    readonly maxCallsPerCandidate: number;
+    readonly callsForPhase: number;
+    readonly initialVerdict?: ReviewVerdictKind;
+    readonly initialArtifact?: unknown;
+    readonly remediationApplied?: boolean;
+    readonly maxArtifactBytes?: number;
+}
+export type ReviewGateResult = {
+    readonly ok: true;
+    readonly permitStage: boolean;
+    readonly verdict: ReviewVerdictKind;
+} | {
+    readonly ok: false;
+    readonly code: string;
+};
+/** Enforces one initial review and, only after remediation, one verification review. */
+export declare function evaluateReviewGate(input: ReviewGateInput): ReviewGateResult;

package/dist/core/consultation.js

@@ -0,0 +1,207 @@
+export const CONSULTATION_CAPABILITIES = ["strategy", "sourceReview"];
+export const CONSULTATION_ROLE_POLICY = Object.freeze({
+    strategy: "dog-advisor",
+    sourceReview: "dog-reviewer",
+});
+export const STRATEGY_TRIGGERS = [
+    "architecture-choice",
+    "cross-boundary-tradeoff",
+    "material-uncertainty",
+];
+/** Strategy is advisory, bounded to one call, and excluded when no design decision remains. */
+export function shouldConsultStrategy(input) {
+    return input.candidateId.length > 0 &&
+        input.trigger !== undefined &&
+        input.callsForCandidate < 1 &&
+        input.decisionAlreadyRecorded !== true &&
+        input.mechanicalChange !== true &&
+        input.sameTaskResume !== true;
+}
+export const SOURCE_REVIEW_RISK_TAGS = [
+    "security",
+    "credential",
+    "permission",
+    "network",
+    "public-api",
+    "storage-compatibility",
+    "package",
+    "build",
+    "release",
+    "migration",
+    "concurrency",
+    "process-io",
+    "write-gate",
+    "authorization",
+];
+const riskTagSet = new Set(SOURCE_REVIEW_RISK_TAGS);
+export function isSourceReviewRiskTag(value) {
+    return typeof value === "string" && riskTagSet.has(value);
+}
+export function requiresSourceReview(riskTags) {
+    return riskTags.length > 0;
+}
+/** Places required review strictly after canonical PASS and before staging. */
+export function evaluateSourceReviewRequirement(input) {
+    if (!Array.isArray(input.riskTags))
+        return "RISK_TAGS_INVALID";
+    const riskTags = [...input.riskTags];
+    if (!riskTags.every(isSourceReviewRiskTag))
+        return "RISK_TAGS_INVALID";
+    if (!requiresSourceReview(riskTags))
+        return "SKIP_LOW_RISK";
+    if (input.canonicalValidationExit !== 0)
+        return "WAIT_CANONICAL_VALIDATION";
+    return input.stagingStarted ? "REVIEW_TOO_LATE" : "REVIEW_REQUIRED";
+}
+export function evaluateReviewAvailability(required, available) {
+    return required && !available ? { ok: false, code: "REVIEW_UNAVAILABLE" } : { ok: true };
+}
+export const MAX_REVIEW_ARTIFACT_BYTES = 30_720;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isStringList(value) {
+    return Array.isArray(value) && value.every(isNonEmptyString);
+}
+/** Strict bounded schema; unknown fields and opaque/raw payloads are rejected. */
+export function validateReviewArtifact(value, maxBytes = MAX_REVIEW_ARTIFACT_BYTES) {
+    let bytes;
+    try {
+        const serialized = JSON.stringify(value);
+        if (serialized === undefined)
+            return { ok: false, code: "ARTIFACT_NOT_JSON" };
+        bytes = Buffer.byteLength(serialized, "utf8");
+    }
+    catch {
+        return { ok: false, code: "ARTIFACT_NOT_JSON" };
+    }
+    if (!Number.isInteger(maxBytes) || maxBytes <= 0 || maxBytes > MAX_REVIEW_ARTIFACT_BYTES) {
+        return { ok: false, code: "ARTIFACT_LIMIT_INVALID" };
+    }
+    if (bytes > maxBytes)
+        return { ok: false, code: "ARTIFACT_TOO_LARGE" };
+    if (!isRecord(value) || !hasExactKeys(value, [
+        "schemaVersion",
+        "candidateId",
+        "sourceFingerprint",
+        "acceptance",
+        "manifest",
+        "riskTags",
+        "riskBearingHunks",
+        "validation",
+        "invariants",
+    ]))
+        return { ok: false, code: "ARTIFACT_SCHEMA_INVALID" };
+    if (value.schemaVersion !== 1 ||
+        !isNonEmptyString(value.candidateId) ||
+        !isNonEmptyString(value.sourceFingerprint) ||
+        !isStringList(value.acceptance) ||
+        !isStringList(value.manifest) ||
+        !Array.isArray(value.riskTags) ||
+        !value.riskTags.every(isSourceReviewRiskTag) ||
+        !isStringList(value.riskBearingHunks) ||
+        !isRecord(value.validation) ||
+        !hasExactKeys(value.validation, ["command", "exit", "fingerprint"]) ||
+        !isNonEmptyString(value.validation.command) ||
+        value.validation.exit !== 0 ||
+        !isNonEmptyString(value.validation.fingerprint) ||
+        !isStringList(value.invariants))
+        return { ok: false, code: "ARTIFACT_SCHEMA_INVALID" };
+    return { ok: true, value: value, bytes };
+}
+export function validateReviewVerdict(value) {
+    if (!isRecord(value) || !hasExactKeys(value, ["verdict", "sourceFingerprint", "findings"])) {
+        return { ok: false, code: "VERDICT_SCHEMA_INVALID" };
+    }
+    if (!["PASS", "MUST_FIX", "BLOCKED"].includes(value.verdict) ||
+        !isNonEmptyString(value.sourceFingerprint) ||
+        !Array.isArray(value.findings))
+        return { ok: false, code: "VERDICT_SCHEMA_INVALID" };
+    for (const finding of value.findings) {
+        if (!isRecord(finding) ||
+            !hasExactKeys(finding, ["severity", "path", "evidence", "requiredFix"]) ||
+            (finding.severity !== "major" && finding.severity !== "medium") ||
+            !isNonEmptyString(finding.path) ||
+            !isNonEmptyString(finding.evidence) ||
+            !isNonEmptyString(finding.requiredFix))
+            return { ok: false, code: "VERDICT_SCHEMA_INVALID" };
+    }
+    if (value.verdict === "PASS" && value.findings.length !== 0) {
+        return { ok: false, code: "PASS_WITH_FINDINGS" };
+    }
+    if (value.verdict !== "PASS" && value.findings.length === 0) {
+        return { ok: false, code: "NON_PASS_WITHOUT_FINDINGS" };
+    }
+    return { ok: true, value: value };
+}
+/** Enforces one initial review and, only after remediation, one verification review. */
+export function evaluateReviewGate(input) {
+    if (!Number.isInteger(input.maxCallsPerCandidate) ||
+        input.maxCallsPerCandidate <= 0 ||
+        !Number.isInteger(input.callsForPhase) ||
+        input.callsForPhase < 0)
+        return { ok: false, code: "REVIEW_BUDGET_INVALID" };
+    if (input.callsForPhase >= input.maxCallsPerCandidate) {
+        return { ok: false, code: "REVIEW_BUDGET_EXHAUSTED" };
+    }
+    const artifact = validateReviewArtifact(input.artifact, input.maxArtifactBytes);
+    if (!artifact.ok)
+        return artifact;
+    const verdict = validateReviewVerdict(input.verdict);
+    if (!verdict.ok)
+        return verdict;
+    if (artifact.value.candidateId !== input.candidateId)
+        return { ok: false, code: "CANDIDATE_MISMATCH" };
+    if (artifact.value.sourceFingerprint !== input.currentSourceFingerprint) {
+        return { ok: false, code: "STALE_FINGERPRINT" };
+    }
+    if (verdict.value.sourceFingerprint !== artifact.value.sourceFingerprint) {
+        return { ok: false, code: "FINGERPRINT_MISMATCH" };
+    }
+    if (input.reviewedFingerprints.includes(artifact.value.sourceFingerprint)) {
+        return { ok: false, code: "FINGERPRINT_REUSED" };
+    }
+    if (input.phase === "initial") {
+        if (input.reviewedFingerprints.length !== 0)
+            return { ok: false, code: "REVIEW_LIMIT_REACHED" };
+    }
+    else if (input.reviewedFingerprints.length !== 1 ||
+        input.initialVerdict !== "MUST_FIX" ||
+        input.remediationApplied !== true) {
+        return { ok: false, code: "VERIFICATION_NOT_ALLOWED" };
+    }
+    else {
+        const initialArtifact = validateReviewArtifact(input.initialArtifact, input.maxArtifactBytes);
+        if (!initialArtifact.ok)
+            return { ok: false, code: "INITIAL_ARTIFACT_INVALID" };
+        if (!sameReviewScope(initialArtifact.value, artifact.value)) {
+            return { ok: false, code: "REVIEW_SCOPE_MISMATCH" };
+        }
+    }
+    return {
+        ok: true,
+        permitStage: verdict.value.verdict === "PASS",
+        verdict: verdict.value.verdict,
+    };
+}
+function sameStringList(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function sameReviewScope(initial, verification) {
+    return initial.schemaVersion === verification.schemaVersion &&
+        initial.candidateId === verification.candidateId &&
+        sameStringList(initial.acceptance, verification.acceptance) &&
+        sameStringList(initial.manifest, verification.manifest) &&
+        sameStringList(initial.riskTags, verification.riskTags) &&
+        sameStringList(initial.riskBearingHunks, verification.riskBearingHunks) &&
+        sameStringList(initial.invariants, verification.invariants) &&
+        initial.validation.command === verification.validation.command;
+}

package/dist/core/initialize.d.ts

@@ -10,5 +10,9 @@ export declare class ProjectInitializationError extends Error {
     readonly code: ProjectInitializationErrorCode;
     constructor(code: ProjectInitializationErrorCode, message: string, options?: ErrorOptions);
 }
+/** Resolves the OpenCode global configuration directory without platform-specific paths. */
+export declare function resolveGlobalConfigRoot(env?: NodeJS.ProcessEnv, home?: string): Promise<string>;
 /** Installs the packaged runtime into one existing project without changing user settings. */
 export declare function initializeProject(projectRoot?: string): Promise<InitializeProjectResult>;
+/** Installs the packaged runtime into OpenCode's global configuration directory. */
+export declare function initializeGlobal(globalRoot?: string): Promise<InitializeProjectResult>;