switchboard-cli 0.1.0-alpha.1 → 0.1.0-alpha.3

package/node_modules/@switchboard/core/src/ingest.ts

@@ -0,0 +1,128 @@
+import YAML from "yaml";
+import { reconcileReturn } from "./reconcile";
+import { chooseRecommendedSurface } from "./router";
+import type { HandoffRecord, ProjectContract, ReconcileReport, ReturnReport, RoutingResult, WorkingState } from "./types";
+import { returnReportSchema, workingStateSchema } from "./types";
+
+function compact(text: string) {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function buildOpenQuestions(report: ReturnReport) {
+  if (report.status === "blocked" && report.blockers.length > 0) {
+    return report.blockers.map((blocker) => `How should we resolve this blocker: ${compact(blocker)}`);
+  }
+
+  if (report.status === "partial") {
+    return ["What is the smallest follow-up slice needed to finish the objective cleanly?"];
+  }
+
+  return ["What is the next narrow slice worth dispatching from the updated state?"];
+}
+
+export function parseStructuredReturn(rawYaml: string): ReturnReport {
+  const parsed = (YAML.parse(rawYaml) ?? {}) as Record<string, unknown>;
+
+  return returnReportSchema.parse({
+    ...parsed,
+    verification_run: parsed.verification_run ?? parsed.checks_run ?? [],
+  });
+}
+
+export function validateReturnForIngest(report: ReturnReport, activeHandoffId: string, handoff: HandoffRecord) {
+  if (!activeHandoffId) {
+    throw new Error("There is no active handoff to ingest against.");
+  }
+
+  if (report.handoff_id !== activeHandoffId) {
+    throw new Error("Return does not match the active handoff.");
+  }
+
+  if (compact(report.objective_attempted) !== compact(handoff.loop.objective)) {
+    throw new Error("Return objective does not match the active loop.");
+  }
+
+  if (report.done_when_met === "yes" && report.success_criteria_met.length === 0) {
+    throw new Error("Returns that claim done-when was met must list met success criteria.");
+  }
+
+  if ((report.status === "done" || report.objective_met === "yes") && report.verification_run.length === 0 && report.evidence.length === 0) {
+    throw new Error("Completed returns require verification or evidence.");
+  }
+}
+
+export function ingestReturnReport(input: {
+  current: WorkingState;
+  handoff: HandoffRecord;
+  report: ReturnReport;
+  repo_present: boolean;
+  contract?: ProjectContract;
+  spec_markdown?: string;
+}): { current: WorkingState; route: RoutingResult; reconcile: ReconcileReport | null } {
+  validateReturnForIngest(input.report, input.current.active_handoff_id, input.handoff);
+
+  // Run reconcile when contract is available
+  let reconcileReport: ReconcileReport | null = null;
+  if (input.contract) {
+    reconcileReport = reconcileReturn({
+      report: input.report,
+      contract: input.contract,
+      handoff: input.handoff,
+      ...(input.spec_markdown ? { spec_markdown: input.spec_markdown } : {}),
+    });
+  }
+
+  const route = chooseRecommendedSurface({
+    repo_present: input.repo_present,
+    task: input.report.recommended_next_step,
+    last_return_status: input.report.status === "done" ? undefined : input.report.status,
+    last_return_reason: `${input.report.summary} ${input.report.blockers.join(" ")} ${input.report.escalations.join(" ")}`,
+  });
+
+  // Determine stage based on return status + reconcile findings
+  let stage: string;
+  if (reconcileReport?.recommendation === "review-required") {
+    stage = "return-review-required";
+  } else if (input.report.status === "done") {
+    stage = "return-ingested";
+  } else if (input.report.status === "partial") {
+    stage = "return-partial";
+  } else {
+    stage = "blocked";
+  }
+
+  // Build open questions from return + reconcile findings
+  const baseQuestions = buildOpenQuestions(input.report);
+  const reconcileQuestions =
+    reconcileReport?.recommendation === "accept-with-warnings"
+      ? reconcileReport.findings.map((f) => f.description)
+      : [];
+
+  // Build blockers from return + review-required reconcile findings
+  const baseBlockers = [...input.report.blockers, ...input.report.escalations].filter(Boolean);
+  const reconcileBlockers =
+    reconcileReport?.recommendation === "review-required"
+      ? reconcileReport.findings.map((f) => `[drift] ${f.description}`)
+      : [];
+
+  const current = workingStateSchema.parse({
+    ...input.current,
+    stage,
+    current_objective: route.next_objective,
+    dominant_uncertainty:
+      reconcileReport?.recommendation === "review-required"
+        ? "Return shows potential drift from original intent — review required before proceeding."
+        : input.report.status === "blocked"
+          ? compact(input.report.blockers[0] ?? "The next slice is blocked and needs a clearer path forward.")
+          : `What is the next narrow move after ${input.handoff.objective.toLowerCase()}?`,
+    open_questions: [...baseQuestions, ...reconcileQuestions].slice(0, 5),
+    active_handoff_id: "",
+    last_return_status: input.report.status,
+    latest_decisions: input.report.decisions_made.filter(Boolean),
+    latest_blockers: [...baseBlockers, ...reconcileBlockers].filter(Boolean),
+    next_recommended_surface: route.primary_recommendation,
+    next_objective: route.next_objective,
+  });
+
+  return { current, route, reconcile: reconcileReport };
+}

package/node_modules/@switchboard/core/src/launch-block-payload.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { preflightResultSchema } from "./preflight";
+import { parallelConflictResultSchema } from "./parallel-conflict";
+
+/** Minimal next-slice fields surfaced on launch-blocked API responses (transport contract). */
+export const launchBlockedNextSliceSummarySchema = z.object({
+  status: z.string(),
+  title: z.string(),
+  blocking_reason: z.string(),
+  review_reason: z.string(),
+  required_inputs: z.array(z.string()),
+  open_dependencies: z.array(z.string()),
+});
+
+export const launchBlockedPreflightFailedSchema = z.object({
+  status: z.literal("launch-blocked"),
+  block: z.literal("preflight-failed"),
+  preflight: preflightResultSchema,
+  systems_in_play: z.array(z.string()),
+  message: z.string(),
+});
+
+export const launchBlockedNextSliceGateSchema = z.object({
+  status: z.literal("launch-blocked"),
+  block: z.enum(["next-slice-held", "next-slice-blocked"]),
+  next_slice: launchBlockedNextSliceSummarySchema,
+  message: z.string(),
+});
+
+export const launchBlockedGroundingSchema = z.object({
+  status: z.literal("launch-blocked"),
+  block: z.literal("prior-return-not-grounded"),
+  missing_paths: z.array(z.string()),
+  message: z.string(),
+});
+
+export const launchBlockedParallelConflictSchema = z.object({
+  status: z.literal("launch-blocked"),
+  block: z.literal("parallel-conflict"),
+  conflict: parallelConflictResultSchema,
+  message: z.string(),
+});
+
+export const launchBlockedPayloadSchema = z.discriminatedUnion("block", [
+  launchBlockedPreflightFailedSchema,
+  launchBlockedNextSliceGateSchema,
+  launchBlockedGroundingSchema,
+  launchBlockedParallelConflictSchema,
+]);
+
+export type LaunchBlockedPayload = z.infer<typeof launchBlockedPayloadSchema>;

package/node_modules/@switchboard/core/src/ledger.ts

@@ -0,0 +1,313 @@
+import type {
+  DiffEntry,
+  DriftDiff,
+  EvidenceType,
+  LedgerEntry,
+  LedgerEntryKind,
+  ProjectLedger,
+  RiskLevel,
+  ScopeChange,
+  SynthesizedSeed,
+} from "./types";
+import { driftDiffSchema, projectLedgerSchema } from "./types";
+
+// ---------------------------------------------------------------------------
+// Ledger creation
+// ---------------------------------------------------------------------------
+
+let _counter = 0;
+function entryId(kind: string): string {
+  return `${kind}-${++_counter}-${Date.now().toString(36)}`;
+}
+
+export function createEntry(input: {
+  kind: LedgerEntryKind;
+  text: string;
+  evidence_type?: EvidenceType;
+  evidence_refs?: string[];
+  parent_ids?: string[];
+  risk_level?: RiskLevel;
+  downstream_artifacts?: string[];
+}): LedgerEntry {
+  return {
+    id: entryId(input.kind),
+    kind: input.kind,
+    text: input.text,
+    evidence_type: input.evidence_type ?? "weak-inference",
+    evidence_refs: input.evidence_refs ?? [],
+    parent_ids: input.parent_ids ?? [],
+    risk_level: input.risk_level,
+    downstream_artifacts: input.downstream_artifacts ?? [],
+    created_at: new Date().toISOString(),
+  };
+}
+
+export function createLedgerFromSeed(seed: SynthesizedSeed, constraints: string): ProjectLedger {
+  const entries: LedgerEntry[] = [];
+
+  // Goals from V1 outcome
+  if (seed.v1_outcome) {
+    entries.push(createEntry({
+      kind: "goal",
+      text: seed.v1_outcome,
+      evidence_type: "user-backed",
+    }));
+  }
+
+  // Constraints / non-goals
+  for (const ng of seed.non_goals) {
+    entries.push(createEntry({
+      kind: "constraint",
+      text: ng,
+      evidence_type: "user-backed",
+    }));
+  }
+
+  if (constraints) {
+    entries.push(createEntry({
+      kind: "constraint",
+      text: constraints,
+      evidence_type: "user-backed",
+    }));
+  }
+
+  // Open questions become assumptions until resolved
+  for (const q of seed.open_questions) {
+    entries.push(createEntry({
+      kind: "assumption",
+      text: q,
+      evidence_type: "weak-inference",
+      risk_level: "medium",
+    }));
+  }
+
+  // First build slice as acceptance criterion
+  if (seed.first_build_slice) {
+    entries.push(createEntry({
+      kind: "acceptance-criterion",
+      text: seed.first_build_slice,
+      evidence_type: "user-backed",
+    }));
+  }
+
+  return projectLedgerSchema.parse({ entries, version: 1 });
+}
+
+// ---------------------------------------------------------------------------
+// Ledger mutations
+// ---------------------------------------------------------------------------
+
+export function addEntry(ledger: ProjectLedger, entry: LedgerEntry): ProjectLedger {
+  return projectLedgerSchema.parse({
+    ...ledger,
+    entries: [...ledger.entries, entry],
+    version: ledger.version + 1,
+  });
+}
+
+export function removeEntry(ledger: ProjectLedger, entryId: string): ProjectLedger {
+  return projectLedgerSchema.parse({
+    ...ledger,
+    entries: ledger.entries.filter((e) => e.id !== entryId),
+    version: ledger.version + 1,
+  });
+}
+
+export function modifyEntry(ledger: ProjectLedger, entryId: string, changes: Partial<LedgerEntry>): ProjectLedger {
+  return projectLedgerSchema.parse({
+    ...ledger,
+    entries: ledger.entries.map((e) =>
+      e.id === entryId ? { ...e, ...changes } : e,
+    ),
+    version: ledger.version + 1,
+  });
+}
+
+export function addDecision(
+  ledger: ProjectLedger,
+  text: string,
+  evidence_type: EvidenceType,
+  parent_ids?: string[],
+  evidence_refs?: string[],
+  risk_level?: RiskLevel,
+): ProjectLedger {
+  const opts: Parameters<typeof createEntry>[0] = { kind: "decision", text, evidence_type };
+  if (parent_ids) opts.parent_ids = parent_ids;
+  if (evidence_refs) opts.evidence_refs = evidence_refs;
+  if (risk_level) opts.risk_level = risk_level;
+  return addEntry(ledger, createEntry(opts));
+}
+
+export function addScopeChange(
+  ledger: ProjectLedger,
+  description: string,
+  reason: string,
+  entriesAdded: string[] = [],
+  entriesRemoved: string[] = [],
+  entriesModified: string[] = [],
+): ProjectLedger {
+  const sc: ScopeChange = {
+    id: entryId("scope-change"),
+    description,
+    entries_added: entriesAdded,
+    entries_removed: entriesRemoved,
+    entries_modified: entriesModified,
+    approved_at: new Date().toISOString(),
+    reason,
+  };
+  return projectLedgerSchema.parse({
+    ...ledger,
+    scope_changes: [...ledger.scope_changes, sc],
+    version: ledger.version + 1,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+export function entriesByKind(ledger: ProjectLedger, kind: LedgerEntryKind): LedgerEntry[] {
+  return ledger.entries.filter((e) => e.kind === kind && !e.superseded_by);
+}
+
+export function goals(ledger: ProjectLedger): LedgerEntry[] { return entriesByKind(ledger, "goal"); }
+export function constraints(ledger: ProjectLedger): LedgerEntry[] { return entriesByKind(ledger, "constraint"); }
+export function assumptions(ledger: ProjectLedger): LedgerEntry[] { return entriesByKind(ledger, "assumption"); }
+export function decisions(ledger: ProjectLedger): LedgerEntry[] { return entriesByKind(ledger, "decision"); }
+export function acceptanceCriteria(ledger: ProjectLedger): LedgerEntry[] { return entriesByKind(ledger, "acceptance-criterion"); }
+
+export function highRiskEntries(ledger: ProjectLedger): LedgerEntry[] {
+  return ledger.entries.filter((e) => e.risk_level === "high" && !e.superseded_by);
+}
+
+export function entriesByEvidence(ledger: ProjectLedger, type: EvidenceType): LedgerEntry[] {
+  return ledger.entries.filter((e) => e.evidence_type === type && !e.superseded_by);
+}
+
+// ---------------------------------------------------------------------------
+// Drift Diff Engine
+// ---------------------------------------------------------------------------
+
+export function diffLedgers(before: ProjectLedger, after: ProjectLedger): DriftDiff {
+  const diffs: DiffEntry[] = [];
+
+  const beforeMap = new Map(before.entries.map((e) => [e.id, e]));
+  const afterMap = new Map(after.entries.map((e) => [e.id, e]));
+
+  // Added entries
+  for (const [id, entry] of afterMap) {
+    if (!beforeMap.has(id)) {
+      diffs.push({
+        action: "added",
+        kind: entry.kind,
+        entry_id: id,
+        new_text: entry.text,
+        summary: `Added ${entry.kind}: "${entry.text.slice(0, 60)}"`,
+      });
+    }
+  }
+
+  // Removed entries
+  for (const [id, entry] of beforeMap) {
+    if (!afterMap.has(id)) {
+      diffs.push({
+        action: "removed",
+        kind: entry.kind,
+        entry_id: id,
+        old_text: entry.text,
+        summary: `Removed ${entry.kind}: "${entry.text.slice(0, 60)}"`,
+      });
+    }
+  }
+
+  // Modified entries
+  for (const [id, afterEntry] of afterMap) {
+    const beforeEntry = beforeMap.get(id);
+    if (beforeEntry && beforeEntry.text !== afterEntry.text) {
+      diffs.push({
+        action: "modified",
+        kind: afterEntry.kind,
+        entry_id: id,
+        old_text: beforeEntry.text,
+        new_text: afterEntry.text,
+        summary: `Changed ${afterEntry.kind}: "${beforeEntry.text.slice(0, 30)}…" → "${afterEntry.text.slice(0, 30)}…"`,
+      });
+    }
+  }
+
+  const hasDrift = diffs.length > 0;
+  const summary = hasDrift
+    ? renderDiffSummary(diffs)
+    : "No changes detected.";
+
+  return driftDiffSchema.parse({ entries: diffs, has_drift: hasDrift, summary });
+}
+
+function renderDiffSummary(diffs: DiffEntry[]): string {
+  const added = diffs.filter((d) => d.action === "added");
+  const removed = diffs.filter((d) => d.action === "removed");
+  const modified = diffs.filter((d) => d.action === "modified");
+  const parts: string[] = [];
+
+  if (added.length > 0) {
+    const kinds = [...new Set(added.map((d) => d.kind))];
+    parts.push(`${added.length} added (${kinds.join(", ")})`);
+  }
+  if (removed.length > 0) {
+    const kinds = [...new Set(removed.map((d) => d.kind))];
+    parts.push(`${removed.length} removed (${kinds.join(", ")})`);
+  }
+  if (modified.length > 0) {
+    const kinds = [...new Set(modified.map((d) => d.kind))];
+    parts.push(`${modified.length} modified (${kinds.join(", ")})`);
+  }
+
+  return parts.join(". ") + ".";
+}
+
+// ---------------------------------------------------------------------------
+// Diff from spec comparison (for external returns)
+// ---------------------------------------------------------------------------
+
+export function diffFromReturn(
+  ledger: ProjectLedger,
+  returnDecisions: string[],
+  returnArtifacts: string[],
+): DriftDiff {
+  const diffs: DiffEntry[] = [];
+  const existingDecisionTexts = new Set(decisions(ledger).map((d) => d.text.toLowerCase()));
+  const existingGoalTexts = new Set(goals(ledger).map((g) => g.text.toLowerCase()));
+
+  // New decisions from the return that aren't in the ledger
+  for (const dec of returnDecisions) {
+    if (dec && !existingDecisionTexts.has(dec.toLowerCase())) {
+      diffs.push({
+        action: "added",
+        kind: "decision",
+        entry_id: `return-${Date.now().toString(36)}`,
+        new_text: dec,
+        summary: `New decision from execution: "${dec.slice(0, 60)}"`,
+      });
+    }
+  }
+
+  // New artifacts that might represent scope growth
+  for (const art of returnArtifacts) {
+    if (art && !existingGoalTexts.has(art.toLowerCase())) {
+      diffs.push({
+        action: "added",
+        kind: "acceptance-criterion",
+        entry_id: `artifact-${Date.now().toString(36)}`,
+        new_text: art,
+        summary: `New artifact from execution: "${art.slice(0, 60)}"`,
+      });
+    }
+  }
+
+  const hasDrift = diffs.length > 0;
+  return driftDiffSchema.parse({
+    entries: diffs,
+    has_drift: hasDrift,
+    summary: hasDrift ? renderDiffSummary(diffs) : "Return aligned with ledger.",
+  });
+}

package/node_modules/@switchboard/core/src/live-event-bus.ts

@@ -0,0 +1,37 @@
+import type { LiveEvent } from "./types";
+import { z } from "zod";
+import { liveEventSchema } from "./types";
+
+// ---------------------------------------------------------------------------
+// LiveEvent log — append-only, typed event feed for the live board
+// ---------------------------------------------------------------------------
+
+export const liveEventLogSchema = z.object({
+  project_id: z.string(),
+  events: z.array(liveEventSchema),
+  created_at: z.string(),
+  last_event_at: z.string().default(""),
+});
+
+export type LiveEventLog = z.infer<typeof liveEventLogSchema>;
+
+export function createLiveEventLog(projectId: string): LiveEventLog {
+  return liveEventLogSchema.parse({
+    project_id: projectId,
+    events: [],
+    created_at: new Date().toISOString(),
+    last_event_at: "",
+  });
+}
+
+export function appendLiveEvent(log: LiveEventLog, event: LiveEvent): LiveEventLog {
+  return liveEventLogSchema.parse({
+    ...log,
+    events: [...log.events, event],
+    last_event_at: event.timestamp,
+  });
+}
+
+export function liveEventCount(log: LiveEventLog): number {
+  return log.events.length;
+}