@sayknow-cli/coding-agent 0.3.7 → 0.3.8

package/src/workflow/workflow-intent-report-schema.ts

@@ -0,0 +1,129 @@
+import * as z from "zod/v4";
+import { WORKFLOW_ESCALATION_ROUTES, WORKFLOW_INTENT_ROUTES, type WorkflowIntentDiff } from "./workflow-intent-diff";
+
+const WORKFLOW_CLAIM_IDS = ["workflow-route", "root-cause-phase", "escalation-gate"] as const;
+const WORKFLOW_OBSERVERS = ["intent-router", "root-cause-schema", "escalation-gate"] as const;
+
+const WorkflowIntentRouteSchema = z.enum(WORKFLOW_INTENT_ROUTES);
+const WorkflowEscalationRouteSchema = z.enum(WORKFLOW_ESCALATION_ROUTES);
+const WorkflowRootCausePhaseSchema = z.object({
+	status: z.enum(["active", "inactive"]),
+	triggers: z.array(z.string()),
+});
+const WorkflowClaimsLedgerSchema = z.object({
+	version: z.literal(1),
+	claims: z.array(
+		z.object({
+			id: z.enum(WORKFLOW_CLAIM_IDS),
+			statement: z.string(),
+			status: z.literal("confirmed"),
+			confidence: z.literal("high"),
+			evidence: z.array(z.string()),
+		}),
+	),
+});
+const WorkflowConsensusReportSchema = z.object({
+	version: z.literal(1),
+	route: WorkflowIntentRouteSchema,
+	confidence: z.literal("high"),
+	summary: z.string(),
+	observerSignals: z.array(
+		z.object({
+			observer: z.enum(WORKFLOW_OBSERVERS),
+			conclusion: z.string(),
+			evidence: z.array(z.string()),
+		}),
+	),
+	escalationGate: z.object({
+		status: z.enum(["required", "not-required"]),
+		reason: z.string(),
+	}),
+});
+
+const WorkflowIntentDiffSchema = z
+	.object({
+		version: z.literal(1),
+		route: WorkflowIntentRouteSchema,
+		reason: z.string(),
+		directTracking: z.enum(["custom-entry-only", "not-direct"]),
+		recommendedSkill: WorkflowEscalationRouteSchema.optional(),
+		recommendedInvocation: z.string().optional(),
+		triggers: z.array(z.string()),
+		rootCausePhase: WorkflowRootCausePhaseSchema,
+		claimsLedger: WorkflowClaimsLedgerSchema,
+		consensusReport: WorkflowConsensusReportSchema,
+		promptPreview: z.string(),
+	})
+	.superRefine((intent, ctx) => {
+		const direct = intent.route === "direct";
+		const expectedTracking = direct ? "custom-entry-only" : "not-direct";
+		const expectedGateStatus = direct ? "not-required" : "required";
+
+		if (intent.directTracking !== expectedTracking) {
+			ctx.addIssue({
+				code: "custom",
+				path: ["directTracking"],
+				message: `directTracking must be ${expectedTracking} for route ${intent.route}`,
+			});
+		}
+		if (intent.consensusReport.route !== intent.route) {
+			ctx.addIssue({
+				code: "custom",
+				path: ["consensusReport", "route"],
+				message: "consensus route must match the top-level workflow route",
+			});
+		}
+		if (intent.consensusReport.escalationGate.status !== expectedGateStatus) {
+			ctx.addIssue({
+				code: "custom",
+				path: ["consensusReport", "escalationGate", "status"],
+				message: `escalation gate must be ${expectedGateStatus} for route ${intent.route}`,
+			});
+		}
+		if (direct) {
+			if (intent.recommendedSkill !== undefined || intent.recommendedInvocation !== undefined) {
+				ctx.addIssue({
+					code: "custom",
+					path: ["recommendedSkill"],
+					message: "direct workflow reports must not carry escalation recommendations",
+				});
+			}
+		} else {
+			if (intent.recommendedSkill !== intent.route || intent.recommendedInvocation === undefined) {
+				ctx.addIssue({
+					code: "custom",
+					path: ["recommendedSkill"],
+					message: "escalated workflow reports must carry matching recommendations",
+				});
+			}
+		}
+
+		for (const signal of intent.consensusReport.observerSignals) {
+			if (signal.observer === "intent-router" && signal.conclusion !== intent.route) {
+				ctx.addIssue({
+					code: "custom",
+					path: ["consensusReport", "observerSignals"],
+					message: "intent-router signal must match the top-level workflow route",
+				});
+			}
+			if (signal.observer === "root-cause-schema" && signal.conclusion !== intent.rootCausePhase.status) {
+				ctx.addIssue({
+					code: "custom",
+					path: ["consensusReport", "observerSignals"],
+					message: "root-cause-schema signal must match the root-cause phase status",
+				});
+			}
+			if (signal.observer === "escalation-gate" && signal.conclusion !== expectedGateStatus) {
+				ctx.addIssue({
+					code: "custom",
+					path: ["consensusReport", "observerSignals"],
+					message: "escalation-gate signal must match the escalation gate status",
+				});
+			}
+		}
+	});
+
+export function parseWorkflowIntentDiffPayload(value: unknown): WorkflowIntentDiff | undefined {
+	const result = WorkflowIntentDiffSchema.safeParse(value);
+	return result.success ? result.data : undefined;
+}

package/src/workflow/workflow-intent-report.ts

@@ -0,0 +1,135 @@
+import type { RootCausePhaseStatus, WorkflowIntentRoute } from "./workflow-intent-diff";
+
+export type WorkflowConfidence = "high";
+export type WorkflowClaimStatus = "confirmed";
+export type WorkflowEscalationGateStatus = "required" | "not-required";
+export type WorkflowSignalObserver = "intent-router" | "root-cause-schema" | "escalation-gate";
+
+export interface WorkflowClaim {
+	readonly id: "workflow-route" | "root-cause-phase" | "escalation-gate";
+	readonly statement: string;
+	readonly status: WorkflowClaimStatus;
+	readonly confidence: WorkflowConfidence;
+	readonly evidence: readonly string[];
+}
+
+export interface WorkflowClaimsLedger {
+	readonly version: 1;
+	readonly claims: readonly WorkflowClaim[];
+}
+
+export interface WorkflowObserverSignal {
+	readonly observer: WorkflowSignalObserver;
+	readonly conclusion: string;
+	readonly evidence: readonly string[];
+}
+
+export interface WorkflowConsensusReport {
+	readonly version: 1;
+	readonly route: WorkflowIntentRoute;
+	readonly confidence: WorkflowConfidence;
+	readonly summary: string;
+	readonly observerSignals: readonly WorkflowObserverSignal[];
+	readonly escalationGate: {
+		readonly status: WorkflowEscalationGateStatus;
+		readonly reason: string;
+	};
+}
+
+export interface WorkflowIntentReport {
+	readonly claimsLedger: WorkflowClaimsLedger;
+	readonly consensusReport: WorkflowConsensusReport;
+}
+
+export interface WorkflowIntentReportInput {
+	readonly route: WorkflowIntentRoute;
+	readonly reason: string;
+	readonly direct: boolean;
+	readonly recommendedInvocation?: string;
+	readonly triggers: readonly string[];
+	readonly rootCausePhase: {
+		readonly status: RootCausePhaseStatus;
+		readonly triggers: readonly string[];
+	};
+}
+
+function triggerEvidence(triggers: readonly string[]): readonly string[] {
+	return triggers.map(trigger => `trigger: ${trigger}`);
+}
+
+function rootCauseEvidence(input: WorkflowIntentReportInput): readonly string[] {
+	if (input.rootCausePhase.status === "inactive") return ["root-cause: inactive"];
+	return ["root-cause: active", ...input.rootCausePhase.triggers.map(trigger => `root-cause-trigger: ${trigger}`)];
+}
+
+function escalationEvidence(input: WorkflowIntentReportInput): readonly string[] {
+	if (input.direct) return ["escalation: not-required", `reason: ${input.reason}`];
+	return ["escalation: required", `invocation: ${input.recommendedInvocation ?? input.route}`];
+}
+
+function escalationGate(input: WorkflowIntentReportInput): WorkflowConsensusReport["escalationGate"] {
+	if (input.direct) {
+		return {
+			status: "not-required",
+			reason: input.reason,
+		};
+	}
+	return {
+		status: "required",
+		reason: input.recommendedInvocation ?? input.route,
+	};
+}
+
+function consensusSummary(input: WorkflowIntentReportInput): string {
+	if (input.direct) return "Consensus: direct implementation with CustomEntry-only workflow traceability.";
+	return `Consensus: route through ${input.recommendedInvocation ?? input.route} because ${input.reason}.`;
+}
+
+export function buildWorkflowIntentReport(input: WorkflowIntentReportInput): WorkflowIntentReport {
+	const confidence: WorkflowConfidence = "high";
+	const gate = escalationGate(input);
+	const routeEvidence = [`route: ${input.route}`, `reason: ${input.reason}`, ...triggerEvidence(input.triggers)];
+	const causeEvidence = rootCauseEvidence(input);
+	const gateEvidence = escalationEvidence(input);
+
+	return {
+		claimsLedger: {
+			version: 1,
+			claims: [
+				{
+					id: "workflow-route",
+					statement: `Prompt should follow the ${input.route} workflow route.`,
+					status: "confirmed",
+					confidence,
+					evidence: routeEvidence,
+				},
+				{
+					id: "root-cause-phase",
+					statement: `Root-cause phase is ${input.rootCausePhase.status}.`,
+					status: "confirmed",
+					confidence,
+					evidence: causeEvidence,
+				},
+				{
+					id: "escalation-gate",
+					statement: `Escalation gate is ${gate.status}.`,
+					status: "confirmed",
+					confidence,
+					evidence: gateEvidence,
+				},
+			],
+		},
+		consensusReport: {
+			version: 1,
+			route: input.route,
+			confidence,
+			summary: consensusSummary(input),
+			observerSignals: [
+				{ observer: "intent-router", conclusion: input.route, evidence: routeEvidence },
+				{ observer: "root-cause-schema", conclusion: input.rootCausePhase.status, evidence: causeEvidence },
+				{ observer: "escalation-gate", conclusion: gate.status, evidence: gateEvidence },
+			],
+			escalationGate: gate,
+		},
+	};
+}