@sayknow-cli/coding-agent 0.3.7 → 0.3.9

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

@@ -0,0 +1,221 @@
+import type { SessionEntry } from "../session/session-manager";
+import {
+	WORKFLOW_INTENT_DIFF_CUSTOM_TYPE,
+	WORKFLOW_INTENT_ROUTES,
+	type WorkflowIntentDiff,
+	type WorkflowIntentRoute,
+} from "./workflow-intent-diff";
+import type { WorkflowSignalObserver } from "./workflow-intent-report";
+import { parseWorkflowIntentDiffPayload } from "./workflow-intent-report-schema";
+
+export type WorkflowConsumerConfidence = "none" | "low" | "medium" | "high";
+
+export interface WorkflowRouteCounts {
+	readonly direct: number;
+	readonly "deep-interview": number;
+	readonly ralplan: number;
+	readonly ultragoal: number;
+	readonly team: number;
+}
+
+export interface WorkflowIntentReportEntry {
+	readonly entryId: string;
+	readonly timestamp: string;
+	readonly intent: WorkflowIntentDiff;
+}
+
+export interface WorkflowIntentReportTotals {
+	readonly total: number;
+	readonly byRoute: WorkflowRouteCounts;
+	readonly escalationRequired: number;
+	readonly rootCauseActive: number;
+}
+
+export interface WorkflowIntentReportCollection {
+	readonly entries: readonly WorkflowIntentReportEntry[];
+	readonly latest: WorkflowIntentReportEntry | undefined;
+	readonly totals: WorkflowIntentReportTotals;
+}
+
+export interface WorkflowObserverSignalSummary {
+	readonly observer: WorkflowSignalObserver;
+	readonly conclusion: string;
+	readonly count: number;
+}
+
+export interface WorkflowConsensusSummary {
+	readonly total: number;
+	readonly dominantRoute: WorkflowIntentRoute | undefined;
+	readonly confidence: WorkflowConsumerConfidence;
+	readonly escalationGate: {
+		readonly required: boolean;
+		readonly count: number;
+		readonly latestReason: string | undefined;
+	};
+	readonly rootCausePhase: {
+		readonly active: boolean;
+		readonly count: number;
+		readonly triggers: readonly string[];
+	};
+	readonly observerSignals: readonly WorkflowObserverSignalSummary[];
+}
+
+function emptyRouteCounts(): WorkflowRouteCounts {
+	return {
+		direct: 0,
+		"deep-interview": 0,
+		ralplan: 0,
+		ultragoal: 0,
+		team: 0,
+	};
+}
+
+function parseWorkflowIntentDiffEntry(entry: SessionEntry): WorkflowIntentReportEntry | undefined {
+	if (entry.type !== "custom" || entry.customType !== WORKFLOW_INTENT_DIFF_CUSTOM_TYPE) return undefined;
+	const intent = parseWorkflowIntentDiffPayload(entry.data);
+	if (!intent) return undefined;
+	return { entryId: entry.id, timestamp: entry.timestamp, intent };
+}
+
+function incrementRoute(counts: WorkflowRouteCounts, route: WorkflowIntentRoute): WorkflowRouteCounts {
+	switch (route) {
+		case "direct":
+			return { ...counts, direct: counts.direct + 1 };
+		case "deep-interview":
+			return { ...counts, "deep-interview": counts["deep-interview"] + 1 };
+		case "ralplan":
+			return { ...counts, ralplan: counts.ralplan + 1 };
+		case "ultragoal":
+			return { ...counts, ultragoal: counts.ultragoal + 1 };
+		case "team":
+			return { ...counts, team: counts.team + 1 };
+	}
+}
+
+function routeCount(counts: WorkflowRouteCounts, route: WorkflowIntentRoute): number {
+	switch (route) {
+		case "direct":
+			return counts.direct;
+		case "deep-interview":
+			return counts["deep-interview"];
+		case "ralplan":
+			return counts.ralplan;
+		case "ultragoal":
+			return counts.ultragoal;
+		case "team":
+			return counts.team;
+	}
+}
+
+export function collectWorkflowIntentReports(entries: readonly SessionEntry[]): WorkflowIntentReportCollection {
+	const reports: WorkflowIntentReportEntry[] = [];
+	let byRoute = emptyRouteCounts();
+	let escalationRequired = 0;
+	let rootCauseActive = 0;
+
+	for (const entry of entries) {
+		const report = parseWorkflowIntentDiffEntry(entry);
+		if (!report) continue;
+		reports.push(report);
+		byRoute = incrementRoute(byRoute, report.intent.route);
+		if (report.intent.consensusReport.escalationGate.status === "required") escalationRequired += 1;
+		if (report.intent.rootCausePhase.status === "active") rootCauseActive += 1;
+	}
+
+	return {
+		entries: reports,
+		latest: reports[reports.length - 1],
+		totals: {
+			total: reports.length,
+			byRoute,
+			escalationRequired,
+			rootCauseActive,
+		},
+	};
+}
+
+function dominantRouteFor(counts: WorkflowRouteCounts, total: number): WorkflowIntentRoute | undefined {
+	if (total === 0) return undefined;
+	let dominant: WorkflowIntentRoute | undefined;
+	let dominantCount = 0;
+	let tied = false;
+
+	for (const route of WORKFLOW_INTENT_ROUTES) {
+		const count = routeCount(counts, route);
+		if (count > dominantCount) {
+			dominant = route;
+			dominantCount = count;
+			tied = false;
+			continue;
+		}
+		if (count === dominantCount && count > 0) tied = true;
+	}
+
+	return tied ? undefined : dominant;
+}
+
+function confidenceFor(
+	total: number,
+	dominantCount: number,
+	dominantRoute: WorkflowIntentRoute | undefined,
+): WorkflowConsumerConfidence {
+	if (total === 0) return "none";
+	if (!dominantRoute) return "low";
+	const ratio = dominantCount / total;
+	if (ratio === 1) return "high";
+	if (ratio >= 0.5) return "medium";
+	return "low";
+}
+
+export function summarizeWorkflowConsensus(intents: readonly WorkflowIntentDiff[]): WorkflowConsensusSummary {
+	let byRoute = emptyRouteCounts();
+	let escalationCount = 0;
+	let latestEscalationReason: string | undefined;
+	let activeRootCauseCount = 0;
+	const rootCauseTriggers: string[] = [];
+	const observerSignalCounts = new Map<string, WorkflowObserverSignalSummary>();
+
+	for (const intent of intents) {
+		byRoute = incrementRoute(byRoute, intent.route);
+		if (intent.consensusReport.escalationGate.status === "required") {
+			escalationCount += 1;
+			latestEscalationReason = intent.consensusReport.escalationGate.reason;
+		}
+		if (intent.rootCausePhase.status === "active") {
+			activeRootCauseCount += 1;
+			for (const trigger of intent.rootCausePhase.triggers) {
+				if (!rootCauseTriggers.includes(trigger)) rootCauseTriggers.push(trigger);
+			}
+		}
+		for (const signal of intent.consensusReport.observerSignals) {
+			const key = `${signal.observer}\u0000${signal.conclusion}`;
+			const existing = observerSignalCounts.get(key);
+			observerSignalCounts.set(key, {
+				observer: signal.observer,
+				conclusion: signal.conclusion,
+				count: existing ? existing.count + 1 : 1,
+			});
+		}
+	}
+
+	const total = intents.length;
+	const dominantRoute = dominantRouteFor(byRoute, total);
+	const dominantCount = dominantRoute ? routeCount(byRoute, dominantRoute) : 0;
+
+	return {
+		total,
+		dominantRoute,
+		confidence: confidenceFor(total, dominantCount, dominantRoute),
+		escalationGate: {
+			required: escalationCount > 0,
+			count: escalationCount,
+			latestReason: latestEscalationReason,
+		},
+		rootCausePhase: {
+			active: activeRootCauseCount > 0,
+			count: activeRootCauseCount,
+			triggers: rootCauseTriggers,
+		},
+		observerSignals: Array.from(observerSignalCounts.values()),
+	};
+}

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,
+		},
+	};
+}