@kisev/skills-opencode 1.2.0 → 2.0.0

package/dist/routing.js

@@ -1,15 +1,38 @@
 import { createHash } from "node:crypto";
-export const CATEGORIES = ["exploration", "architecture", "implementation", "review", "documentation", "quick"];
+import { validateAgentReport } from "./contracts.js";
+export const CATEGORIES = ["exploration", "architecture", "implementation", "review"];
 const MATRIX = {
     schema_version: 1,
     categories: {
-        exploration: { profiles: ["mapper", "architect"], capabilities: ["read", "search"], tools: ["read", "glob", "grep"], cost: "low", latency: "fast" },
-        architecture: { profiles: ["architect", "mapper"], capabilities: ["read", "architecture"], tools: ["read", "glob", "grep"], cost: "medium", latency: "standard" },
-        implementation: { profiles: ["worker"], capabilities: ["read", "write", "verify"], tools: ["read", "edit", "bash"], cost: "medium", latency: "standard" },
-        review: { profiles: ["review", "critic"], capabilities: ["read", "review"], tools: ["read", "glob", "grep"], cost: "medium", latency: "standard" },
-        documentation: { profiles: ["worker", "review"], capabilities: ["read", "write", "documentation"], tools: ["read", "edit"], cost: "low", latency: "standard" },
-        quick: { profiles: ["mapper", "worker"], capabilities: ["read"], tools: ["read"], cost: "low", latency: "fast" }
-    }
+        exploration: {
+            profiles: ["mapper", "architect"],
+            capabilities: ["read", "search"],
+            tools: ["read", "glob", "grep"],
+            cost: "low",
+            latency: "fast",
+        },
+        architecture: {
+            profiles: ["architect", "mapper"],
+            capabilities: ["read", "architecture"],
+            tools: ["read", "glob", "grep"],
+            cost: "medium",
+            latency: "standard",
+        },
+        implementation: {
+            profiles: ["worker"],
+            capabilities: ["read", "write", "verify"],
+            tools: ["read", "edit", "bash"],
+            cost: "medium",
+            latency: "standard",
+        },
+        review: {
+            profiles: ["review", "critic"],
+            capabilities: ["read", "review"],
+            tools: ["read", "glob", "grep"],
+            cost: "medium",
+            latency: "standard",
+        },
+    },
 };
 function stable(value) {
     if (value === null || typeof value !== "object")
@@ -17,11 +40,66 @@ function stable(value) {
     if (Array.isArray(value))
         return `[${value.map(stable).join(",")}]`;
     const object = value;
-    return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stable(object[key])}`).join(",")}}`;
+    return `{${Object.keys(object)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stable(object[key])}`)
+        .join(",")}}`;
 }
 function digest(value) {
     return createHash("sha256").update(stable(value), "utf8").digest("hex");
 }
+export function validateRoutingReceipt(value, context) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("routing receipt is not an object");
+    const decision = value;
+    if ("destination" in decision) {
+        const receipt = value;
+        if (receipt.schema_version !== 1 ||
+            !CATEGORIES.includes(receipt.destination) ||
+            !receipt.agent ||
+            !receipt.nonce ||
+            !/^[a-f0-9]{64}$/.test(receipt.host_inventory_revision) ||
+            !/^[a-f0-9]{64}$/.test(receipt.receipt_digest) ||
+            !Number.isFinite(Date.parse(receipt.expires_at)) ||
+            (receipt.card_revision !== null &&
+                (!Number.isInteger(receipt.card_revision) || receipt.card_revision < 1)))
+            throw new Error("routing receipt is malformed");
+        if (Date.parse(receipt.expires_at) < Date.now())
+            throw new Error("routing receipt has expired");
+        const { receipt_digest: _receiptDigest, ...receiptBase } = receipt;
+        if (digest(receiptBase) !== receipt.receipt_digest)
+            throw new Error("routing receipt integrity is invalid");
+        if (context?.category !== undefined && receipt.destination !== context.category)
+            throw new Error("routing receipt destination does not match");
+        if (context?.task !== undefined && receipt.task_digest !== digest(context.task))
+            throw new Error("routing receipt task does not match");
+        if (context?.requirements !== undefined &&
+            receipt.requirements_digest !== digest(context.requirements))
+            throw new Error("routing receipt requirements do not match");
+        if (context?.card !== undefined && receipt.card_digest !== digest(context.card))
+            throw new Error("routing receipt card does not match");
+        return receipt;
+    }
+    if (decision.schema_version !== 1 ||
+        decision.status !== "selected" ||
+        !decision.agent ||
+        !CATEGORIES.includes(decision.category))
+        throw new Error("routing receipt is not selected");
+    if (!decision.matrix_revision ||
+        !decision.decision_digest ||
+        !/^[a-f0-9]{64}$/.test(decision.decision_digest))
+        throw new Error("routing receipt is incomplete");
+    const { decision_digest: _digest, ...base } = decision;
+    if (digest(base) !== decision.decision_digest)
+        throw new Error("routing receipt digest is forged or stale");
+    if (decision.matrix_revision !== digest(MATRIX))
+        throw new Error("routing receipt matrix is stale");
+    if (context?.category !== undefined && decision.category !== context.category)
+        throw new Error("routing receipt category does not match");
+    if (context?.task !== undefined && decision.task_digest !== digest(context.task))
+        throw new Error("routing receipt task does not match");
+    return decision;
+}
 function missing(required, actual) {
     const values = new Set(actual ?? []);
     return required.some((item) => !values.has(item));
@@ -32,10 +110,20 @@ function exceeds(value, limit, order) {
 export function resolveRouting(input) {
     const category = MATRIX.categories[input.category];
     const revision = digest(MATRIX);
+    const hostInventoryRevision = input.inventory_revision ?? digest(input.agents);
     const inventory = new Map(input.agents.map((agent) => [agent.agent, agent]));
     const alternatives = [];
     const eligible = [];
-    for (const profile of category.profiles) {
+    const dynamicCritics = input.category === "review"
+        ? input.agents
+            .map(({ agent }) => agent)
+            .filter((agent) => /^critic-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(agent))
+            .sort()
+        : [];
+    const profiles = input.trusted_override && input.override && !category.profiles.includes(input.override)
+        ? [...category.profiles, ...dynamicCritics, input.override]
+        : [...category.profiles, ...dynamicCritics];
+    for (const profile of profiles) {
         const agent = inventory.get(profile);
         const reasons = [];
         if (!agent)
@@ -57,17 +145,65 @@ export function resolveRouting(input) {
         else if (agent)
             eligible.push(agent);
     }
-    const selected = input.override ? eligible.find((agent) => agent.agent === input.override) : eligible[0];
+    if (input.override &&
+        !input.trusted_override &&
+        !category.profiles.includes(input.override))
+        throw new Error("Unknown or user-owned profile requires a trusted override");
+    const selected = input.override
+        ? eligible.find((agent) => agent.agent === input.override)
+        : eligible[0];
     const card = input.execution_card === undefined ? undefined : validateExecutionCard(input.execution_card);
     if (card && !card.valid)
         throw new Error(`Invalid execution card: ${card.failedField}`);
     const base = selected
-        ? { schema_version: 1, status: "selected", category: input.category, agent: selected.agent, reason_codes: [input.override ? "explicit_override" : selected.agent === category.profiles[0] ? "primary_available" : "fallback_selected", "capabilities_match"], alternatives, matrix_revision: revision, task_digest: digest(input.task ?? ""), requirements_digest: digest(input.requirements), ...(card?.valid ? { execution_card_digest: digest(card.card), execution_card_revision: card.card.revision } : {}) }
-        : { schema_version: 1, status: "escalate", category: input.category, reason_codes: [input.override ? "override_unavailable" : "no_eligible_profile"], alternatives, matrix_revision: revision, task_digest: digest(input.task ?? ""), requirements_digest: digest(input.requirements), ...(card?.valid ? { execution_card_digest: digest(card.card), execution_card_revision: card.card.revision } : {}) };
+        ? {
+            schema_version: 1,
+            status: "selected",
+            category: input.category,
+            agent: selected.agent,
+            reason_codes: [
+                input.override
+                    ? "explicit_override"
+                    : selected.agent === category.profiles[0]
+                        ? "primary_available"
+                        : "fallback_selected",
+                "capabilities_match",
+            ],
+            alternatives,
+            matrix_revision: revision,
+            host_inventory_revision: hostInventoryRevision,
+            task_digest: digest(input.task ?? ""),
+            requirements_digest: digest(input.requirements),
+            ...(card?.valid
+                ? {
+                    execution_card_digest: digest(card.card),
+                    execution_card_revision: card.card.revision,
+                }
+                : {}),
+        }
+        : {
+            schema_version: 1,
+            status: "escalate",
+            category: input.category,
+            reason_codes: [input.override ? "override_unavailable" : "no_eligible_profile"],
+            alternatives,
+            matrix_revision: revision,
+            host_inventory_revision: hostInventoryRevision,
+            task_digest: digest(input.task ?? ""),
+            requirements_digest: digest(input.requirements),
+            ...(card?.valid
+                ? {
+                    execution_card_digest: digest(card.card),
+                    execution_card_revision: card.card.revision,
+                }
+                : {}),
+        };
     return { ...base, decision_digest: digest(base) };
 }
 function isNonEmptyStringArray(value) {
-    return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string" && item.length > 0);
+    return (Array.isArray(value) &&
+        value.length > 0 &&
+        value.every((item) => typeof item === "string" && item.length > 0));
 }
 export function validateExecutionCard(card) {
     if (!card || typeof card !== "object" || Array.isArray(card)) {
@@ -75,12 +211,28 @@ export function validateExecutionCard(card) {
     }
     const c = card;
     const expectedFields = [
-        "status", "card_id", "revision", "objective", "changed_behavior", "risks",
-        "write_set", "control_markers", "decisions", "steps", "acceptance_criteria",
-        "checks", "boundaries",
+        "schema_version",
+        "status",
+        "card_id",
+        "revision",
+        "objective",
+        "evidence",
+        "changed_behavior",
+        "risks",
+        "write_set",
+        "control_markers",
+        "decisions",
+        "steps",
+        "acceptance_criteria",
+        "checks",
+        "operations",
+        "confirmations",
+        "boundaries",
     ];
     if (Object.keys(c).sort().join(",") !== expectedFields.slice().sort().join(","))
         return { valid: false, failedField: "schema" };
+    if (c.schema_version !== 1)
+        return { valid: false, failedField: "schema_version" };
     if (c.status !== "READY")
         return { valid: false, failedField: "status" };
     if (typeof c.card_id !== "string" || !c.card_id)
@@ -89,6 +241,8 @@ export function validateExecutionCard(card) {
         return { valid: false, failedField: "revision" };
     if (typeof c.objective !== "string" || !c.objective)
         return { valid: false, failedField: "objective" };
+    if (!isNonEmptyStringArray(c.evidence))
+        return { valid: false, failedField: "evidence" };
     if (!isNonEmptyStringArray(c.changed_behavior))
         return { valid: false, failedField: "changed_behavior" };
     if (!isNonEmptyStringArray(c.risks))
@@ -131,22 +285,95 @@ export function validateExecutionCard(card) {
         return { valid: false, failedField: "acceptance_criteria" };
     if (!isNonEmptyStringArray(c.checks))
         return { valid: false, failedField: "checks" };
+    if (!Array.isArray(c.operations) || c.operations.length === 0)
+        return { valid: false, failedField: "operations" };
+    const operationKinds = new Set([
+        "write",
+        "check",
+        "commit",
+        "rebase",
+        "push",
+        "merge",
+        "tag",
+        "release",
+    ]);
+    for (const operation of c.operations) {
+        if (!operation || typeof operation !== "object" || Array.isArray(operation))
+            return { valid: false, failedField: "operations" };
+        const item = operation;
+        if (typeof item.kind !== "string" ||
+            !operationKinds.has(item.kind) ||
+            typeof item.command !== "string" ||
+            !item.command)
+            return { valid: false, failedField: "operations" };
+        if (item.path !== undefined && (typeof item.path !== "string" || !item.path))
+            return { valid: false, failedField: "operations" };
+        if (item.confirmation_ref !== undefined &&
+            (typeof item.confirmation_ref !== "string" || !item.confirmation_ref))
+            return { valid: false, failedField: "operations" };
+        if (Object.keys(item).some((key) => !["kind", "command", "path", "confirmation_ref"].includes(key)))
+            return { valid: false, failedField: "operations" };
+        if ((item.kind === "write" || item.kind === "check") && typeof item.path !== "string")
+            return { valid: false, failedField: "operations" };
+    }
+    const operationSet = new Set(c.operations.map(({ kind }) => kind));
+    for (const required of ["commit", "rebase", "push", "merge", "tag", "release"])
+        if (!operationSet.has(required))
+            return { valid: false, failedField: "operations" };
+    if (!c.confirmations || typeof c.confirmations !== "object" || Array.isArray(c.confirmations))
+        return { valid: false, failedField: "confirmations" };
+    const confirmations = c.confirmations;
+    if (typeof confirmations.execution !== "string" || !confirmations.execution)
+        return { valid: false, failedField: "confirmations" };
+    if (operationSet.has("push") ||
+        operationSet.has("merge") ||
+        operationSet.has("tag") ||
+        operationSet.has("release"))
+        if (typeof confirmations.publication !== "string" || !confirmations.publication)
+            return { valid: false, failedField: "confirmations" };
+    if (operationSet.has("rebase"))
+        if (typeof confirmations.history_rewrite !== "string" || !confirmations.history_rewrite)
+            return { valid: false, failedField: "confirmations" };
+    if (Object.keys(confirmations).some((key) => !["execution", "publication", "history_rewrite"].includes(key)))
+        return { valid: false, failedField: "confirmations" };
     if (!c.boundaries || typeof c.boundaries !== "object" || Array.isArray(c.boundaries))
         return { valid: false, failedField: "boundaries" };
     const b = c.boundaries;
-    if (!isNonEmptyStringArray(b.forbidden_paths))
+    if (!isNonEmptyStringArray(b.forbidden_paths) || typeof b.scope !== "string" || !b.scope)
         return { valid: false, failedField: "boundaries" };
-    if (Object.keys(b).some((k) => k !== "forbidden_paths"))
+    if (Object.keys(b).some((k) => k !== "forbidden_paths" && k !== "scope"))
         return { valid: false, failedField: "boundaries" };
     const writeSet = c.write_set;
     const forbiddenPaths = b.forbidden_paths;
+    const safePath = (path) => !path.startsWith("/") &&
+        !path.includes("\\") &&
+        !path.split("/").some((part) => !part || part === "." || part === "..");
+    if (![...writeSet, ...forbiddenPaths].every(safePath))
+        return { valid: false, failedField: "boundaries" };
     const stepPaths = c.steps.map((s) => s.path);
     const markerPaths = c.control_markers.map((m) => m.path);
     const referenced = new Set([...stepPaths, ...markerPaths]);
     if (![...referenced].every((p) => writeSet.includes(p)))
         return { valid: false, failedField: "steps" };
-    if (writeSet.some((p) => forbiddenPaths.includes(p)))
+    const overlaps = (left, right) => left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+    if (writeSet.some((p) => forbiddenPaths.some((forbidden) => overlaps(p, forbidden))))
         return { valid: false, failedField: "boundaries" };
+    if (!writeSet.every((path) => stepPaths.includes(path)))
+        return { valid: false, failedField: "steps" };
+    const operations = c.operations;
+    if (!writeSet.every((path) => operations.some((operation) => operation.kind === "write" && operation.path === path) &&
+        operations.some((operation) => operation.kind === "check" && operation.path === path)))
+        return { valid: false, failedField: "operations" };
+    for (const operation of operations) {
+        if (["commit", "rebase", "push", "merge", "tag", "release"].includes(operation.kind) &&
+            !operation.confirmation_ref)
+            return { valid: false, failedField: "operations" };
+        if (operation.kind === "rebase" && operation.confirmation_ref !== confirmations.history_rewrite)
+            return { valid: false, failedField: "confirmations" };
+        if (["push", "merge", "tag", "release"].includes(operation.kind) &&
+            operation.confirmation_ref !== confirmations.publication)
+            return { valid: false, failedField: "confirmations" };
+    }
     return { valid: true, card: c };
 }
 export class ExecutionCardLifecycle {
@@ -160,9 +387,15 @@ export class ExecutionCardLifecycle {
         this.#cardID = result.card.card_id;
         this.#revision = result.card.revision;
     }
-    get status() { return this.#status; }
-    get card_id() { return this.#cardID; }
-    get revision() { return this.#revision; }
+    get status() {
+        return this.#status;
+    }
+    get card_id() {
+        return this.#cardID;
+    }
+    get revision() {
+        return this.#revision;
+    }
     transition(status, identity) {
         if (identity.card_id !== this.#cardID || identity.revision !== this.#revision)
             throw new Error("Execution card identity is stale");
@@ -170,7 +403,12 @@ export class ExecutionCardLifecycle {
             READY: ["RUNNING", "CANCELLED"],
             RUNNING: ["COMPLETED", "BLOCKED", "FAILED", "REJECTED_PLAN", "CANCELLED"],
             COMPLETED: ["APPROVED", "CHANGES_REQUIRED"],
-            BLOCKED: [], FAILED: [], REJECTED_PLAN: [], APPROVED: [], CHANGES_REQUIRED: [], CANCELLED: [],
+            BLOCKED: [],
+            FAILED: [],
+            REJECTED_PLAN: [],
+            APPROVED: [],
+            CHANGES_REQUIRED: [],
+            CANCELLED: [],
         };
         if (!allowed[this.#status].includes(status))
             throw new Error(`Invalid execution-card transition: ${this.#status} -> ${status}`);
@@ -180,6 +418,7 @@ export class ExecutionCardLifecycle {
 }
 export class RoutingGate {
     #receipts = new Map();
+    #active = new Map();
     #ttlMs = 10 * 60 * 1000;
     preview(input) {
         return resolveRouting(input);
@@ -195,17 +434,38 @@ export class RoutingGate {
     grant(sessionID, decision, context) {
         const now = Date.now();
         const taskDigest = context?.task === undefined ? decision.task_digest : digest(context.task);
-        const requirementsDigest = context?.requirements === undefined ? decision.requirements_digest : digest(context.requirements);
+        const requirementsDigest = context?.requirements === undefined
+            ? decision.requirements_digest
+            : digest(context.requirements);
         const cardDigest = context?.card === undefined ? decision.execution_card_digest : digest(context.card);
+        const receiptBase = {
+            schema_version: 1,
+            task_digest: taskDigest,
+            requirements_digest: requirementsDigest,
+            destination: decision.category,
+            agent: decision.agent,
+            card_digest: cardDigest ?? null,
+            card_revision: decision.execution_card_revision ?? null,
+            host_inventory_revision: decision.host_inventory_revision,
+            expires_at: new Date(now + this.#ttlMs).toISOString(),
+            nonce: createHash("sha256")
+                .update(`${sessionID}:${now}:${decision.decision_digest}`)
+                .digest("hex"),
+        };
+        const receipt = { ...receiptBase, receipt_digest: digest(receiptBase) };
         this.#receipts.set(sessionID, {
             decision,
             taskDigest,
             requirementsDigest,
             cardDigest,
-            expiresAt: now + this.#ttlMs,
+            expiresAt: Date.parse(receipt.expires_at),
         });
+        return receipt;
+    }
+    cancel(sessionID) {
+        this.#receipts.delete(sessionID);
+        this.#active.delete(sessionID);
     }
-    cancel(sessionID) { this.#receipts.delete(sessionID); }
     consume(sessionID, agent, context) {
         const receipt = this.#receipts.get(sessionID);
         if (!receipt)
@@ -226,5 +486,57 @@ export class RoutingGate {
                 throw new Error("Routing receipt execution card does not match the active routing receipt");
         }
         this.#receipts.delete(sessionID);
+        const validatedCard = context?.card === undefined ? undefined : validateExecutionCard(context.card);
+        const card = validatedCard?.valid ? validatedCard.card : undefined;
+        const lifecycle = card ? new ExecutionCardLifecycle(card) : undefined;
+        if (lifecycle)
+            lifecycle.transition("RUNNING", { card_id: card.card_id, revision: card.revision });
+        this.#active.set(sessionID, { agent, card, lifecycle, expiresAt: receipt.expiresAt });
+    }
+    complete(sessionID, agent, output) {
+        const active = this.#active.get(sessionID);
+        if (!active || active.agent !== agent)
+            throw new Error("Task result has no matching active routing receipt");
+        if (Date.now() > active.expiresAt)
+            throw new Error("Task result routing receipt has expired");
+        const report = output && typeof output === "object" ? output : undefined;
+        const value = report?.[agent === "architect" ? "execution_card" : `${agent}_report`] ?? report?.report;
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("Task result is missing a structured agent report");
+        const result = value;
+        validateAgentReport(agent, report, active.card);
+        if (active.card &&
+            (result.card_id !== active.card.card_id || result.revision !== active.card.revision))
+            throw new Error("Task result does not match the active execution card");
+        const status = result.status;
+        const allowed = agent === "worker"
+            ? ["COMPLETED", "BLOCKED", "FAILED", "REJECTED_PLAN"]
+            : agent === "critic"
+                ? ["APPROVED", "CHANGES_REQUIRED"]
+                : undefined;
+        if (allowed && (typeof status !== "string" || !allowed.includes(status)))
+            throw new Error("Task result has an invalid machine transition");
+        if (active.lifecycle && status === "COMPLETED")
+            active.lifecycle.transition("COMPLETED", {
+                card_id: active.card.card_id,
+                revision: active.card.revision,
+            });
+        if (active.lifecycle &&
+            (status === "BLOCKED" || status === "FAILED" || status === "REJECTED_PLAN"))
+            active.lifecycle.transition(status, {
+                card_id: active.card.card_id,
+                revision: active.card.revision,
+            });
+        if (active.lifecycle && (status === "APPROVED" || status === "CHANGES_REQUIRED")) {
+            active.lifecycle.transition("COMPLETED", {
+                card_id: active.card.card_id,
+                revision: active.card.revision,
+            });
+            active.lifecycle.transition(status, {
+                card_id: active.card.card_id,
+                revision: active.card.revision,
+            });
+        }
+        this.#active.delete(sessionID);
     }
 }

package/dist/runtime/worktree.d.ts

@@ -0,0 +1,33 @@
+export type WorktreeStatus = "managed" | "missing" | "blocked" | "unknown";
+export type WorktreeRecord = {
+    schema_version: 1;
+    workspace_id: string;
+    project: string;
+    path: string;
+    branch: string;
+    start_ref: string;
+    repository_fingerprint: string;
+    marker: string;
+    status: WorktreeStatus;
+    created_at: string;
+    updated_at: string;
+};
+export declare function worktreePlan(project: string, workspaceID?: `${string}-${string}-${string}-${string}-${string}`): Promise<Record<string, unknown>>;
+export declare function worktreeCreate(input: {
+    project: string;
+    workspace_id: string;
+    path?: string;
+    branch?: string;
+    start_ref?: string;
+}): Promise<WorktreeRecord>;
+export declare function worktreeStatus(project: string, workspaceID: string): Promise<WorktreeRecord | undefined>;
+export declare function worktreeList(project: string): Promise<WorktreeRecord[]>;
+export declare function worktreeRelease(project: string, workspaceID: string): Promise<{
+    status: "released" | "blocked";
+    workspace_id: string;
+    reason?: string;
+}>;
+export declare function worktreeRecover(project: string): Promise<{
+    recovered: number;
+    blocked: number;
+}>;