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

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

@@ -0,0 +1,238 @@
+import type {
+  BudgetPosture,
+  DispatchRecord,
+  EvaluationResult,
+  LiveEvent,
+  LiveEventKind,
+  LiveProvenanceLevel,
+  RunSnapshot,
+  Surface,
+} from "./types";
+import {
+  liveEventSchema,
+  SURFACE_LABELS,
+} from "./types";
+
+// ---------------------------------------------------------------------------
+// Operator action derivation — deterministic from snapshot state
+// ---------------------------------------------------------------------------
+
+function deriveOperatorAction(snapshot: RunSnapshot): {
+  required: boolean;
+  action: string;
+} {
+  switch (snapshot.phase) {
+    case "held_for_review":
+      return { required: true, action: "Review gate hold and resolve before advancing." };
+    case "blocked":
+      return { required: true, action: "Provide missing evidence to unblock." };
+    case "activation_blocked":
+      return { required: true, action: "Resolve activation blockers." };
+    case "activation_held":
+      return { required: true, action: "Narrow activation scope to proceed." };
+    case "accepted_with_cautions":
+      return { required: true, action: "Review cautions before closing or advancing." };
+    default:
+      break;
+  }
+
+  if (snapshot.home_bucket === "feedback_pending") {
+    return { required: true, action: "Provide operator feedback." };
+  }
+
+  if (snapshot.unresolved_count > 0 && snapshot.phase === "accepted") {
+    return { required: true, action: "Resolve unresolved items before proceeding." };
+  }
+
+  return { required: false, action: "" };
+}
+
+// ---------------------------------------------------------------------------
+// Provenance level derivation — from evidence proof if available
+// ---------------------------------------------------------------------------
+
+function deriveProvenanceLevel(snapshot: RunSnapshot): LiveProvenanceLevel {
+  const proof = snapshot.evidence_proof;
+  if (!proof) return "unknown";
+
+  if (proof.provenance_captured_count > 0) return "captured";
+  if (proof.provenance_reconstructed_count > 0) return "reconstructed";
+  if (proof.provenance_derived_count > 0) return "derived";
+
+  // Has proof structure but no provenance counts → synthetic (e.g. simulated return)
+  if (proof.policy_task_type) return "synthetic";
+
+  return "unknown";
+}
+
+// ---------------------------------------------------------------------------
+// projectLiveEvent — maps DispatchRecord + RunSnapshot → LiveEvent
+// ---------------------------------------------------------------------------
+
+let _eventCounter = 0;
+
+function generateEventId(): string {
+  _eventCounter += 1;
+  const ts = Date.now().toString(36);
+  const seq = _eventCounter.toString(36).padStart(4, "0");
+  return `lev-${ts}-${seq}`;
+}
+
+export function projectLiveEvent(input: {
+  kind: LiveEventKind;
+  snapshot: RunSnapshot;
+  project_id: string;
+  dispatch?: DispatchRecord | null;
+  loop_ordinal?: number;
+  detail?: string;
+  budget_posture?: BudgetPosture;
+}): LiveEvent {
+  const { kind, snapshot, project_id, detail } = input;
+  const dispatch = input.dispatch ?? null;
+  const loop_ordinal = input.loop_ordinal ?? -1;
+
+  // Surface identity — from dispatch if available
+  const surface: Surface | undefined = dispatch?.route_surface ?? undefined;
+  const surface_label: string = surface ? (SURFACE_LABELS[surface] ?? surface) : "";
+  const surface_fallback: Surface | undefined = dispatch?.route_fallback ?? undefined;
+  const route_rationale: string = dispatch?.route_rationale ?? "";
+
+  // Role — dispatch exists means agent is acting; operator actions have no dispatch
+  const role: "agent" | "operator" = dispatch ? "agent" : "operator";
+
+  // Operator action
+  const operatorSignal = deriveOperatorAction(snapshot);
+
+  // Provenance
+  const provenance_level = deriveProvenanceLevel(snapshot);
+
+  return liveEventSchema.parse({
+    event_id: generateEventId(),
+    kind,
+    timestamp: new Date().toISOString(),
+
+    project_id,
+    dispatch_id: dispatch?.dispatch_id ?? "",
+    slice_id: dispatch?.slice_id ?? "",
+    loop_ordinal,
+
+    surface,
+    surface_label,
+    surface_fallback,
+    route_rationale,
+    role,
+
+    phase: snapshot.phase,
+    home_bucket: snapshot.home_bucket,
+    gate_label: snapshot.gate_label,
+    hold_source: snapshot.hold_source,
+
+    operator_action_required: operatorSignal.required,
+    operator_action: operatorSignal.action,
+
+    budget_posture: input.budget_posture ?? "unknown",
+    provenance_level,
+
+    merge_outcome: snapshot.merge_outcome,
+    run_outcome: snapshot.run_outcome,
+    closure_posture: snapshot.closure_posture,
+
+    caution_count: snapshot.caution_count,
+    unresolved_count: snapshot.unresolved_count,
+
+    detail: detail ?? "",
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Convenience projectors for common lifecycle transitions
+// ---------------------------------------------------------------------------
+
+export function projectDispatchEvent(input: {
+  dispatch: DispatchRecord;
+  snapshot: RunSnapshot;
+  project_id: string;
+  loop_ordinal?: number;
+}): LiveEvent {
+  return projectLiveEvent({
+    kind: "dispatched",
+    snapshot: input.snapshot,
+    project_id: input.project_id,
+    dispatch: input.dispatch,
+    loop_ordinal: input.loop_ordinal ?? -1,
+    detail: `Dispatched to ${input.dispatch.provider_label}: ${input.dispatch.packet_summary}`,
+  });
+}
+
+export function projectReturnEvent(input: {
+  dispatch: DispatchRecord;
+  snapshot: RunSnapshot;
+  project_id: string;
+  loop_ordinal?: number;
+  budget_posture?: BudgetPosture;
+}): LiveEvent {
+  return projectLiveEvent({
+    kind: "return-received",
+    snapshot: input.snapshot,
+    project_id: input.project_id,
+    dispatch: input.dispatch,
+    loop_ordinal: input.loop_ordinal ?? -1,
+    detail: `Return from ${input.dispatch.provider_label}: ${input.dispatch.return_status}`,
+    ...(input.budget_posture != null && { budget_posture: input.budget_posture }),
+  });
+}
+
+export function projectGateEvent(input: {
+  dispatch: DispatchRecord;
+  snapshot: RunSnapshot;
+  project_id: string;
+  loop_ordinal?: number;
+  budget_posture?: BudgetPosture;
+}): LiveEvent {
+  return projectLiveEvent({
+    kind: "gate-resolved",
+    snapshot: input.snapshot,
+    project_id: input.project_id,
+    dispatch: input.dispatch,
+    loop_ordinal: input.loop_ordinal ?? -1,
+    detail: `Gate: ${input.snapshot.gate_label} (${input.snapshot.gate_reason})`,
+    ...(input.budget_posture != null && { budget_posture: input.budget_posture }),
+  });
+}
+
+export function projectStatusChange(input: {
+  snapshot: RunSnapshot;
+  project_id: string;
+  dispatch?: DispatchRecord | null;
+  loop_ordinal?: number;
+  detail?: string;
+}): LiveEvent {
+  return projectLiveEvent({
+    kind: "status-changed",
+    snapshot: input.snapshot,
+    project_id: input.project_id,
+    dispatch: input.dispatch ?? null,
+    loop_ordinal: input.loop_ordinal ?? -1,
+    detail: input.detail ?? `Phase: ${input.snapshot.phase}, bucket: ${input.snapshot.home_bucket}`,
+  });
+}
+
+export function projectEvaluationEvent(input: {
+  evaluation: EvaluationResult;
+  snapshot: RunSnapshot;
+  project_id: string;
+  dispatch?: DispatchRecord | null;
+  loop_ordinal?: number;
+  budget_posture?: BudgetPosture;
+}): LiveEvent {
+  const { evaluation } = input;
+  return projectLiveEvent({
+    kind: "evaluation-completed",
+    snapshot: input.snapshot,
+    project_id: input.project_id,
+    dispatch: input.dispatch ?? null,
+    loop_ordinal: input.loop_ordinal ?? -1,
+    detail: `Evaluation ${evaluation.evaluation_id}: ${evaluation.verdict} (${evaluation.finding_count} findings, reentry: ${evaluation.reentry_signal})`,
+    ...(input.budget_posture != null && { budget_posture: input.budget_posture }),
+  });
+}

package/node_modules/@switchboard/core/src/lock-readiness.ts

@@ -0,0 +1,242 @@
+import type {
+  LockFinding,
+  LockFindingCategory,
+  LockFindingSeverity,
+  LockReadiness,
+  ProjectContract,
+  SynthesizedSeed,
+} from "./types";
+import { lockReadinessSchema } from "./types";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function finding(
+  category: LockFindingCategory,
+  severity: LockFindingSeverity,
+  field: string,
+  detail: string,
+): LockFinding {
+  return { category, severity, field, detail };
+}
+
+const GENERIC_BOUNDARY_MARKERS = [
+  "not a generic",
+  "not a chat wrapper",
+  "not a pm tool",
+  "not a workspace",
+  "not an emotional",
+  "not a sentiment",
+];
+
+function isProductGuardrailOnly(nonGoal: string): boolean {
+  const lower = nonGoal.toLowerCase();
+  return GENERIC_BOUNDARY_MARKERS.some(m => lower.includes(m));
+}
+
+// ---------------------------------------------------------------------------
+// Core checks
+// ---------------------------------------------------------------------------
+
+function checkRequiredInputs(seed: SynthesizedSeed): LockFinding[] {
+  const findings: LockFinding[] = [];
+
+  if (!seed.target_user || seed.target_user === "Solo builders shipping software.") {
+    findings.push(finding("missing_required_input", "blocking", "target_user", "Target user not specified."));
+  }
+
+  if (!seed.proposed_solution || seed.proposed_solution === "Needs further shaping.") {
+    findings.push(finding("missing_required_input", "blocking", "proposed_solution", "No clear solution approach — describe what ships."));
+  }
+
+  for (const m of seed.missing_inputs.filter(Boolean)) {
+    findings.push(finding("missing_required_input", "blocking", "missing_inputs", m));
+  }
+
+  return findings;
+}
+
+function checkScopeForImplTask(
+  seed: SynthesizedSeed,
+  contract: ProjectContract,
+): LockFinding[] {
+  const findings: LockFinding[] = [];
+
+  // First bounded slice
+  if (!seed.first_build_slice || seed.first_build_slice.length < 10) {
+    findings.push(finding(
+      "missing_scope",
+      "blocking",
+      "first_build_slice",
+      "First bounded slice is missing or too vague — define what ships in this slice before locking.",
+    ));
+  }
+
+  // Scope in — must exist for impl tasks
+  const scopeIn = contract.task_clauses?.scope_in ?? [];
+  if (scopeIn.length === 0) {
+    findings.push(finding(
+      "missing_scope",
+      "blocking",
+      "task_clauses.scope_in",
+      "No in-scope lines defined — implementation tasks need bounded scope before lock.",
+    ));
+  }
+
+  // Scope out / non-goals
+  const scopeOut = contract.task_clauses?.scope_out ?? [];
+  if (scopeOut.length === 0 && contract.non_goals.length === 0) {
+    findings.push(finding(
+      "missing_scope",
+      "blocking",
+      "task_clauses.scope_out",
+      "No out-of-scope lines or non-goals — implementation tasks need at least one explicit boundary.",
+    ));
+  }
+
+  return findings;
+}
+
+function checkTaskBoundaries(
+  contract: ProjectContract,
+  taskType: string,
+): LockFinding[] {
+  const findings: LockFinding[] = [];
+
+  if (taskType !== "implementation-request") return findings;
+
+  // Distinguish product guardrails from task-specific boundaries
+  const nonGoals = contract.non_goals;
+  const taskSpecific = nonGoals.filter(ng => !isProductGuardrailOnly(ng));
+  const productOnly = nonGoals.filter(ng => isProductGuardrailOnly(ng));
+
+  if (taskSpecific.length === 0) {
+    findings.push(finding(
+      "missing_task_boundary",
+      "blocking",
+      "non_goals",
+      `Contract has ${productOnly.length} product-level guardrail(s) but no task-specific boundaries. Implementation tasks need boundaries relevant to THIS build (e.g. "no billing", "single file only").`,
+    ));
+  }
+
+  // Build constraints
+  const buildConstraints = contract.task_clauses?.build_constraints ?? [];
+  if (buildConstraints.length === 0) {
+    findings.push(finding(
+      "missing_task_boundary",
+      "caution",
+      "task_clauses.build_constraints",
+      "No build constraints stated — consider adding boundaries for this specific implementation.",
+    ));
+  }
+
+  return findings;
+}
+
+function checkSystemsAndRepo(
+  contract: ProjectContract,
+  taskType: string,
+): LockFinding[] {
+  const findings: LockFinding[] = [];
+
+  if (taskType !== "implementation-request") return findings;
+
+  // Systems in play
+  const systems = contract.task_clauses?.systems_expected ?? [];
+  if (systems.length === 0) {
+    findings.push(finding(
+      "missing_systems",
+      "caution",
+      "task_clauses.systems_expected",
+      "No systems-in-play detected — consider confirming which systems this slice touches.",
+    ));
+  }
+
+  // Repo binding for implementation tasks
+  if (contract.repo_status === "repo-not-present") {
+    findings.push(finding(
+      "missing_repo_binding",
+      "caution",
+      "repo_status",
+      "No repository bound — first execution will create one.",
+    ));
+  }
+
+  return findings;
+}
+
+function checkIntent(seed: SynthesizedSeed): LockFinding[] {
+  const findings: LockFinding[] = [];
+
+  if (seed.confidence === "low") {
+    findings.push(finding(
+      "vague_intent",
+      "blocking",
+      "confidence",
+      "Low confidence in extracted intent — clarify before locking.",
+    ));
+  }
+
+  if (seed.confidence === "medium" && seed.open_questions.filter(Boolean).length > 2) {
+    findings.push(finding(
+      "vague_intent",
+      "caution",
+      "confidence",
+      "Medium confidence with multiple open questions — lock is allowed but review recommended.",
+    ));
+  }
+
+  for (const q of seed.open_questions.filter(Boolean)) {
+    findings.push(finding(
+      "unresolved_assumption",
+      "caution",
+      "open_questions",
+      q,
+    ));
+  }
+
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Main function
+// ---------------------------------------------------------------------------
+
+export function checkLockReadiness(input: {
+  seed: SynthesizedSeed;
+  contract: ProjectContract;
+  taskType: string;
+}): LockReadiness {
+  const { seed, contract, taskType } = input;
+  const isImpl = taskType === "implementation-request";
+
+  const allFindings: LockFinding[] = [
+    ...checkRequiredInputs(seed),
+    ...(isImpl ? checkScopeForImplTask(seed, contract) : []),
+    ...checkTaskBoundaries(contract, taskType),
+    ...checkSystemsAndRepo(contract, taskType),
+    ...checkIntent(seed),
+  ];
+
+  const blocking = allFindings.filter(f => f.severity === "blocking").length;
+  const cautions = allFindings.filter(f => f.severity === "caution").length;
+
+  let outcome: "lock_allowed" | "lock_allowed_with_cautions" | "lock_blocked";
+  if (blocking > 0) {
+    outcome = "lock_blocked";
+  } else if (cautions > 0) {
+    outcome = "lock_allowed_with_cautions";
+  } else {
+    outcome = "lock_allowed";
+  }
+
+  return lockReadinessSchema.parse({
+    outcome,
+    findings: allFindings,
+    blocking_count: blocking,
+    caution_count: cautions,
+    task_type_basis: taskType,
+    checked_at: new Date().toISOString(),
+  });
+}

package/node_modules/@switchboard/core/src/loop-compiler.ts

@@ -0,0 +1,152 @@
+import type { LoopContract, ProjectContract, RoutingResult, WorkingState } from "./types";
+import { loopContractSchema } from "./types";
+
+type LoopCompilerInput = {
+  contract: ProjectContract;
+  current: WorkingState;
+  route: RoutingResult;
+  objective?: string;
+  scope_in?: string[];
+  scope_out?: string[];
+  done_when?: string[];
+  success_criteria?: string[];
+  verify_with?: string[];
+};
+
+function compact(text: string) {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function dedupe(values: string[]) {
+  return Array.from(new Set(values.map((value) => compact(value)).filter(Boolean)));
+}
+
+function inferExecutionShape(route: RoutingResult, objective: string): LoopContract["execution_shape"] {
+  const normalized = objective.toLowerCase();
+
+  if (route.primary_recommendation === "chatgpt" && /(research|compare|investigate|discover|map)/.test(normalized)) {
+    return "bounded_parallel_research";
+  }
+
+  if (route.primary_recommendation === "claude-code" && /(across|multi-file|multiple|parallel|several|web app|bundle|api)/.test(normalized)) {
+    return "bounded_parallel_implementation";
+  }
+
+  return "single";
+}
+
+function defaultScopeIn(input: LoopCompilerInput, objective: string) {
+  return [
+    objective,
+    `Keep ${input.current.primary_artifact_ref} aligned only if the product meaning changes.`,
+    "Touch only files and artifacts that directly support the active slice.",
+  ];
+}
+
+function defaultScopeOut() {
+  return [
+    "No new execution surfaces, orchestration controls, or runtime platform features.",
+    "No remote execution, workers, schedulers, or graph-building UX.",
+    "No broad refactor outside the active slice.",
+  ];
+}
+
+function defaultDoneWhen(route: RoutingResult) {
+  if (route.primary_recommendation === "chatgpt") {
+    return [
+      "The blocking product decision is resolved.",
+      "The next repo-ready slice is explicit.",
+      "Any changed scope boundary is called out clearly.",
+    ];
+  }
+
+  if (route.primary_recommendation === "cursor") {
+    return [
+      "The targeted UI or interaction slice is coherent.",
+      "Changed files are listed explicitly.",
+      "Any taste-sensitive decisions are captured in the return.",
+    ];
+  }
+
+  return [
+    "The requested repo slice is complete across the required files.",
+    "Relevant verification has been run or skipped with explicit reason.",
+    "Follow-up blockers are captured before return.",
+  ];
+}
+
+function defaultSuccessCriteria(route: RoutingResult, objective: string) {
+  if (route.primary_recommendation === "chatgpt") {
+    return [
+      `The clarified recommendation directly resolves this objective: ${objective}`,
+      "The recommendation narrows the next slice rather than widening scope.",
+    ];
+  }
+
+  if (route.primary_recommendation === "cursor") {
+    return [
+      "The edited experience feels coherent in the targeted area.",
+      "The changes stay within the active UI or taste-heavy slice.",
+    ];
+  }
+
+  return [
+    "The repo implementation matches the stated objective without adding platform sprawl.",
+    "Verification evidence exists for the touched slice.",
+  ];
+}
+
+function defaultVerifyWith(input: LoopCompilerInput) {
+  if (input.route.primary_recommendation === "chatgpt") {
+    return [
+      `Cross-check the recommendation against ${input.current.primary_artifact_ref}.`,
+      "Make any unresolved ambiguity explicit in the return.",
+    ];
+  }
+
+  if (input.route.primary_recommendation === "cursor") {
+    return [
+      "Visually verify the targeted interaction or layout change.",
+      "List any unverified assumptions before returning.",
+    ];
+  }
+
+  return [
+    "Run the smallest relevant checks for touched files.",
+    "Document any skipped verification with reason.",
+  ];
+}
+
+function defaultBlockerEscalation() {
+  return [
+    "Return immediately if the product decision becomes unclear.",
+    "Return immediately if implementation expands unexpectedly.",
+    "Return immediately if the work becomes mostly visual or taste-heavy.",
+  ];
+}
+
+function defaultExpectedArtifacts(input: LoopCompilerInput) {
+  if (input.route.primary_recommendation === "chatgpt") {
+    return [input.current.primary_artifact_ref, "Structured return report"];
+  }
+
+  return ["Repo changes for the active slice", "Structured return report"];
+}
+
+export function compileLoopContract(input: LoopCompilerInput): LoopContract {
+  const objective = compact(input.objective ?? input.current.next_objective ?? input.route.next_objective);
+
+  return loopContractSchema.parse({
+    objective,
+    scope_in: dedupe(input.scope_in ?? defaultScopeIn(input, objective)),
+    scope_out: dedupe(input.scope_out ?? defaultScopeOut()),
+    done_when: dedupe(input.done_when ?? defaultDoneWhen(input.route)),
+    success_criteria: dedupe(input.success_criteria ?? defaultSuccessCriteria(input.route, objective)),
+    verify_with: dedupe(input.verify_with ?? defaultVerifyWith(input)),
+    return_when: input.route.return_condition,
+    blocker_escalation: dedupe(defaultBlockerEscalation()),
+    expected_artifacts: dedupe(defaultExpectedArtifacts(input)),
+    fallback_surface: input.route.fallback_surface,
+    execution_shape: inferExecutionShape(input.route, objective),
+  });
+}

package/node_modules/@switchboard/core/src/loop-validator.ts

@@ -0,0 +1,55 @@
+import type { LaunchReadiness, LoopContract } from "./types";
+import { launchReadinessSchema } from "./types";
+
+const VAGUE_MARKERS = ["good", "better", "clean up", "stuff", "things", "some", "maybe", "nice", "improve"];
+const TESTABLE_MARKERS = ["run", "pass", "update", "list", "create", "capture", "document", "explicit", "complete", "verify", "return"];
+
+function compact(text: string) {
+  return text.replace(/\s+/g, " ").trim().toLowerCase();
+}
+
+function looksVague(text: string) {
+  const normalized = compact(text);
+  return normalized.split(" ").length < 4 || VAGUE_MARKERS.some((marker) => normalized.includes(marker));
+}
+
+function looksConcrete(items: string[]) {
+  return items.every((item) => item.length >= 12 && TESTABLE_MARKERS.some((marker) => compact(item).includes(marker)));
+}
+
+export function validateLoopReadiness(loop: LoopContract): LaunchReadiness {
+  const missingIssues: string[] = [];
+  const clarificationIssues: string[] = [];
+
+  if (!loop.objective) missingIssues.push("Objective is missing.");
+  if (loop.scope_in.length === 0) missingIssues.push("Scope in is empty.");
+  if (loop.scope_out.length === 0) missingIssues.push("Scope out is empty.");
+  if (loop.done_when.length === 0) missingIssues.push("Done-when is empty.");
+  if (loop.success_criteria.length === 0) missingIssues.push("Success criteria are empty.");
+  if (loop.verify_with.length === 0) missingIssues.push("Verify-with is empty.");
+  if (!loop.return_when) missingIssues.push("Return-when is missing.");
+  if (!loop.fallback_surface) missingIssues.push("Fallback surface is missing.");
+
+  if (missingIssues.length > 0) {
+    return launchReadinessSchema.parse({
+      status: "missing required boundary info",
+      issues: missingIssues,
+    });
+  }
+
+  if (looksVague(loop.objective)) clarificationIssues.push("Objective needs to be more specific.");
+  if (!looksConcrete(loop.done_when)) clarificationIssues.push("Done-when needs more testable language.");
+  if (!looksConcrete(loop.success_criteria)) clarificationIssues.push("Success criteria need to be more concrete.");
+
+  if (clarificationIssues.length > 0) {
+    return launchReadinessSchema.parse({
+      status: "needs clarification",
+      issues: clarificationIssues,
+    });
+  }
+
+  return launchReadinessSchema.parse({
+    status: "ready",
+    issues: [],
+  });
+}