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

package/node_modules/@switchboard/core/src/run-snapshot.ts

@@ -0,0 +1,405 @@
+import type {
+  ComplexityClassification,
+  GateState,
+  HomeBucket,
+  NextSlice,
+  ReconcileReport,
+  ReturnReport,
+  RunPhase,
+  RunSnapshot,
+  SynthesizedSeed,
+} from "./types";
+import { runSnapshotSchema } from "./types";
+import { deriveGateState, tightenGateWithPressure, tightenGateWithAudit } from "./gate-state";
+import { assessPressure, deriveEffectiveTaskType, checkEvidenceSufficiency } from "./pressure-assessment";
+import { shouldRequireAudit, computeAuditResult, noAuditRequired } from "./codex-audit";
+import type { EvidenceProof } from "./types";
+import { evidenceProofSchema } from "./types";
+
+// ---------------------------------------------------------------------------
+// System detection from file paths — imports shared patterns from canonical-delta
+// ---------------------------------------------------------------------------
+
+import { SYSTEM_PATTERNS } from "./canonical-delta";
+
+function detectSystemsFromPaths(files: string[]): string[] {
+  const systems = new Set<string>();
+  for (const file of files) {
+    for (const [pattern, label] of SYSTEM_PATTERNS) {
+      if (pattern.test(file)) systems.add(label);
+    }
+  }
+  return [...systems];
+}
+
+// ---------------------------------------------------------------------------
+// Canonical cautions + unresolved — ONE derivation, used everywhere
+// ---------------------------------------------------------------------------
+
+export function deriveCanonicalCautions(input: {
+  reconcile: ReconcileReport | null;
+  latestReturn: ReturnReport | null;
+}): string[] {
+  const cautions: string[] = [];
+  if (input.reconcile) {
+    for (const f of input.reconcile.findings) {
+      if (f.severity === "warning") {
+        cautions.push(`[reconcile] ${f.description}`);
+      }
+    }
+  }
+  if (input.latestReturn) {
+    for (const e of input.latestReturn.escalations.filter(Boolean)) {
+      cautions.push(`[return] ${e}`);
+    }
+  }
+  return cautions;
+}
+
+export function deriveCanonicalUnresolved(input: {
+  latestReturn: ReturnReport | null;
+}): string[] {
+  const unresolved: string[] = [];
+  if (input.latestReturn) {
+    for (const b of input.latestReturn.blockers.filter(Boolean)) unresolved.push(b);
+    for (const e of input.latestReturn.escalations.filter(Boolean)) unresolved.push(e);
+    if (input.latestReturn.objective_met === "partial") {
+      unresolved.push("Objective only partially met.");
+    }
+    if (input.latestReturn.objective_met === "no") {
+      unresolved.push("Objective not met.");
+    }
+  }
+  return unresolved;
+}
+
+// ---------------------------------------------------------------------------
+// Phase derivation — from activation + gate + closure state
+// ---------------------------------------------------------------------------
+
+function derivePhase(input: {
+  hasProject: boolean;
+  isClosed: boolean;
+  hasReturn: boolean;
+  hasActiveHandoff: boolean;
+  activationBlocked: boolean;
+  activationHeld: boolean;
+  gateLabel: string;
+  stage: string;
+}): RunPhase {
+  if (!input.hasProject) return "no_project";
+  if (input.isClosed) return "closed";
+
+  // Return + gate always wins over activation narrowing (governance mode, etc.)
+  if (input.hasReturn) {
+    switch (input.gateLabel) {
+      case "accepted": return "accepted";
+      case "accepted-with-cautions": return "accepted_with_cautions";
+      case "held-for-review": return "held_for_review";
+      case "blocked-missing-evidence": return "blocked";
+      case "pending": return "return_received";
+      default: return "absorbed";
+    }
+  }
+
+  if (input.hasActiveHandoff) return "dispatched";
+
+  if (input.activationBlocked) return "activation_blocked";
+  if (input.activationHeld) return "activation_held";
+
+  if (input.stage === "activation-needs-narrowing") return "activation_held";
+
+  // Has project, no return, no handoff — ready or locked
+  if (input.stage === "activation-compiled" || input.stage === "activation-shaping") {
+    return "ready_to_lock";
+  }
+
+  return "ready_to_lock";
+}
+
+// ---------------------------------------------------------------------------
+// Home bucket — deterministic from phase + unresolved
+// ---------------------------------------------------------------------------
+
+function deriveHomeBucket(phase: RunPhase, unresolvedCount: number): HomeBucket {
+  switch (phase) {
+    case "no_project": return "idle";
+    case "closed": return "recently_closed";
+    case "activation_blocked": return "needs_attention";
+    case "activation_held": return "needs_attention";
+    case "held_for_review": return "held_or_blocked";
+    case "blocked": return "held_or_blocked";
+    case "dispatched": return "ready_to_execute";
+    case "return_received": return "recently_changed";
+    case "absorbed": return "recently_changed";
+    case "accepted": return unresolvedCount > 0 ? "needs_attention" : "feedback_pending";
+    case "accepted_with_cautions": return "needs_attention";
+    case "ready_to_lock": return "ready_to_execute";
+    case "locked": return "ready_to_execute";
+    default: return "idle";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Control flags — shared by RunSnapshot AND GovernanceEnvelope
+// ---------------------------------------------------------------------------
+
+export function deriveControlFlags(phase: RunPhase, hasReturn: boolean): {
+  stateAdvanceAllowed: boolean;
+  closureAllowed: boolean;
+} {
+  const stateAdvanceAllowed = phase === "accepted" || phase === "accepted_with_cautions";
+  // Closure requires: has a return AND gate passed (accepted or accepted_with_cautions)
+  // held_for_review → closed is ILLEGAL — operator must resolve the hold first
+  // blocked → closed is ILLEGAL — new evidence required
+  const closureAllowed = hasReturn && stateAdvanceAllowed;
+  return { stateAdvanceAllowed, closureAllowed };
+}
+
+// ---------------------------------------------------------------------------
+// Derive canonical run snapshot — ONE call, all surfaces read from it
+// ---------------------------------------------------------------------------
+
+export function deriveRunSnapshot(input: {
+  // Project state
+  hasProject: boolean;
+  isClosed: boolean;
+  stage: string;
+  hasActiveHandoff: boolean;
+
+  // Seed
+  seed: SynthesizedSeed | null;
+  complexity: ComplexityClassification | null;
+
+  // Return + reconcile
+  reconcile: ReconcileReport | null;
+  latestReturn: ReturnReport | null;
+
+  // Next slice (if derived)
+  nextSlice: NextSlice | null;
+
+  // Activation state (from governance envelope)
+  activationBlocked: boolean;
+  activationHeld: boolean;
+  repoExists?: boolean;
+  /** Whether the return's changed_files actually exist in the repo. Default true. */
+  repoGrounded?: boolean;
+  /** Proof provenance counts from the proof manifest, if available. */
+  proofProvenance?: {
+    captured_count: number;
+    reconstructed_count: number;
+    derived_count: number;
+    has_execution_transcript: boolean;
+    proof_folder?: string;
+  };
+}): RunSnapshot {
+  const {
+    hasProject, isClosed, stage, hasActiveHandoff,
+    seed, reconcile, latestReturn,
+    nextSlice, activationBlocked, activationHeld,
+  } = input;
+  const repoExists = input.repoExists ?? false;
+
+  const seedTaskType = seed?.task_type ?? "unknown";
+
+  // Effective task type — reclassified from actual return evidence, not just seed
+  const effectiveTaskType = latestReturn
+    ? deriveEffectiveTaskType(seedTaskType, latestReturn, repoExists)
+    : seedTaskType;
+
+  // Gate state — derived ONCE with pressure + audit tightening
+  let gateState: GateState = deriveGateState({
+    reconcile, latestReturn, phase: stage,
+  });
+  let holdSource: "none" | "reconcile" | "pressure" | "audit" = "none";
+
+  // Track if reconcile itself held
+  if (gateState.label === "held-for-review" || gateState.label === "blocked-missing-evidence") {
+    holdSource = "reconcile";
+  }
+
+  // Pressure tightening — applied ONCE, same result for all surfaces
+  const prePresssureLabel = gateState.label;
+  if (latestReturn && seed) {
+    // Use effectiveTaskType (reclassified from actual return evidence), NOT seedTaskType
+    const pressure = assessPressure({ report: latestReturn, taskType: effectiveTaskType, reconcile, repoExists });
+    gateState = tightenGateWithPressure(gateState, pressure);
+    if (gateState.label !== prePresssureLabel) {
+      holdSource = "pressure";
+    }
+  }
+
+  // Audit tightening — code-touching work must pass audit before promotion
+  let auditCautions: string[] = [];
+  if (latestReturn) {
+    const auditCheck = shouldRequireAudit({
+      report: latestReturn,
+      complexityMode: input.complexity?.mode ?? null,
+      taskType: effectiveTaskType,
+    });
+    if (auditCheck.required) {
+      const auditResult = computeAuditResult({
+        report: latestReturn,
+        triggers: auditCheck.triggers,
+        returnId: latestReturn.handoff_id,
+      });
+      const preAuditLabel = gateState.label;
+      gateState = tightenGateWithAudit(gateState, auditResult);
+      if (gateState.label !== preAuditLabel) {
+        holdSource = "audit";
+      }
+
+      // Feed audit findings into the caution model so all surfaces see them
+      for (const f of auditResult.findings) {
+        if (f.severity === "caution") {
+          auditCautions.push(`[audit] ${f.detail}`);
+        } else if (f.severity === "blocker") {
+          auditCautions.push(`[audit-blocker] ${f.detail}`);
+        }
+      }
+    }
+  }
+
+  // Canonical cautions + unresolved — ONE derivation, includes audit findings
+  const cautions = [...deriveCanonicalCautions({ reconcile, latestReturn }), ...auditCautions];
+  const unresolved = deriveCanonicalUnresolved({ latestReturn });
+
+  // Phase
+  const phase = derivePhase({
+    hasProject,
+    isClosed,
+    hasReturn: !!latestReturn,
+    hasActiveHandoff,
+    activationBlocked,
+    activationHeld,
+    gateLabel: gateState.label,
+    stage,
+  });
+
+  // Home bucket
+  const homeBucket = deriveHomeBucket(phase, unresolved.length);
+
+  // Next slice readiness
+  const nextSliceReady = nextSlice?.dispatch_ready ?? nextSlice?.ready_for_dispatch ?? false;
+  const nextSliceStatus = nextSlice?.status ?? "";
+  const nextSliceBlockingReason = nextSlice?.blocking_reason ?? nextSlice?.review_reason ?? "";
+
+  // Control flags — shared logic, used by both RunSnapshot and GovernanceEnvelope
+  const { stateAdvanceAllowed, closureAllowed } = deriveControlFlags(phase, !!latestReturn);
+
+  return runSnapshotSchema.parse({
+    phase,
+    gate_label: gateState.label,
+    gate_reason: gateState.reason,
+    hold_source: holdSource,
+    cautions_on_record: cautions,
+    unresolved_on_record: unresolved,
+    next_slice_ready: nextSliceReady,
+    next_slice_status: nextSliceStatus,
+    next_slice_blocking_reason: nextSliceBlockingReason,
+    task_type_basis: effectiveTaskType,
+    home_bucket: homeBucket,
+    is_closed: isClosed,
+    closure_allowed: closureAllowed,
+    state_advance_allowed: stateAdvanceAllowed,
+    verification_run_count: latestReturn?.verification_run.length ?? 0,
+    evidence_item_count: latestReturn?.evidence.length ?? 0,
+    caution_count: cautions.length,
+    unresolved_count: unresolved.length,
+
+    // Evidence proof — semantically layered, derived from one chain
+    evidence_proof: latestReturn ? (() => {
+      const sufficiency = checkEvidenceSufficiency({
+        report: latestReturn,
+        taskType: effectiveTaskType,
+        pressureSignals: [],
+      });
+      return evidenceProofSchema.parse({
+        // Layer 1: Structured proof rows
+        structured_paths: latestReturn.changed_files.length,
+        structured_artifacts: latestReturn.artifacts_created.filter(Boolean).length,
+        structured_verification_lines: latestReturn.verification_run.length,
+        structured_evidence_lines: latestReturn.evidence.length,
+        structured_criteria_met: latestReturn.success_criteria_met.length,
+        // Layer 2: Policy evaluation
+        policy_task_type: effectiveTaskType,
+        policy_requirements: sufficiency.requirements,
+        policy_satisfied: sufficiency.present,
+        policy_missing: sufficiency.missing,
+        policy_outcome: sufficiency.outcome,
+        // Layer 3: Canonical advancement
+        state_fields_advanced: [
+          ...(latestReturn.changed_files.length > 0 ? [
+            (input.repoGrounded ?? true)
+              ? `${latestReturn.changed_files.length} file(s) in repo`
+              : `${latestReturn.changed_files.length} file(s) claimed (simulated — not repo-grounded)`
+          ] : []),
+          ...(latestReturn.decisions_made.length > 0 ? [`${latestReturn.decisions_made.length} decision(s) recorded`] : []),
+          ...(latestReturn.evidence.length > 0 ? [`${latestReturn.evidence.length} evidence item(s) added`] : []),
+          ...(latestReturn.status === "done" ? ["stage → return-ingested → closed (on seal)"] : []),
+        ],
+        consequence_type: latestReturn.changed_files.length > 0 ? "code-change"
+          : latestReturn.decisions_made.length > 0 ? "contract-clarification"
+          : latestReturn.status === "done" ? "absorbed-return"
+          : "no-change",
+        consequence_label: latestReturn.changed_files.length > 0 ? `${latestReturn.changed_files.length} file(s) changed.`
+          : latestReturn.decisions_made.length > 0 ? `${latestReturn.decisions_made.length} decision(s) recorded. No files changed.`
+          : latestReturn.status === "done" ? "Return absorbed. No files changed."
+          : "No measurable change.",
+        // Layer 4: Provenance
+        provenance_captured_count: input.proofProvenance?.captured_count ?? 0,
+        provenance_reconstructed_count: input.proofProvenance?.reconstructed_count ?? 0,
+        provenance_derived_count: input.proofProvenance?.derived_count ?? 0,
+        has_execution_transcript: input.proofProvenance?.has_execution_transcript ?? false,
+        proof_folder: input.proofProvenance?.proof_folder,
+      });
+    })() : undefined,
+
+    // --- Strict status schema ---
+    merge_outcome: (() => {
+      switch (gateState.label) {
+        case "accepted": return "accepted";
+        case "accepted-with-cautions": return "accepted_with_cautions";
+        case "held-for-review": return "held";
+        case "blocked-missing-evidence": return "blocked";
+        default: return "not_evaluated";
+      }
+    })(),
+    run_outcome: latestReturn
+      ? (latestReturn.status === "done" && latestReturn.objective_met === "yes" ? "done"
+        : latestReturn.status === "done" && latestReturn.objective_met === "partial" ? "partial"
+        : latestReturn.status === "partial" ? "partial"
+        : latestReturn.status === "blocked" ? "blocked"
+        : "partial")
+      : "not_started",
+    closure_posture: isClosed ? "sealed"
+      : !latestReturn ? "open"
+      : closureAllowed && cautions.length === 0 && unresolved.length === 0 ? "closable"
+      : closureAllowed ? "closable_with_cautions"
+      : "not_closable",
+    seal_integrity: isClosed ? "verified" : "not_sealed",
+    next_slice_posture: !nextSlice ? "none"
+      : nextSliceReady ? "ready"
+      : nextSliceStatus === "blocked" ? "blocked"
+      : nextSliceStatus === "held" ? "held"
+      : "draft",
+    // Systems touched — derived from return file paths, not text inference
+    systems_touched: latestReturn ? detectSystemsFromPaths(latestReturn.changed_files) : [],
+
+    derived_at: new Date().toISOString(),
+  });
+}
+
+/**
+ * True when Layer 4 fields reflect a loaded proof manifest (store passes
+ * `proofProvenance`). When false, counts are schema defaults only — not an
+ * assertion that the run had zero proof artifacts.
+ */
+export function evidenceProofLayer4IsManifestBacked(ep: EvidenceProof): boolean {
+  const cap = ep.provenance_captured_count ?? 0;
+  const recon = ep.provenance_reconstructed_count ?? 0;
+  const der = ep.provenance_derived_count ?? 0;
+  const transcript = ep.has_execution_transcript ?? false;
+  const folder = ep.proof_folder?.trim();
+  return Boolean(folder) || cap > 0 || recon > 0 || der > 0 || transcript;
+}

package/node_modules/@switchboard/core/src/surface-playbooks.ts

@@ -0,0 +1,36 @@
+import type { Surface, SurfacePlaybook } from "./types";
+import { surfacePlaybookSchema } from "./types";
+
+const PLAYBOOKS: Record<Surface, string[]> = {
+  chatgpt: [
+    "Resolve ambiguity before more repo work starts.",
+    "Return with one crisp recommendation, not multiple branches.",
+    "Escalate immediately if the decision is still unclear after one pass.",
+  ],
+  "claude-code": [
+    "Prefer continuing existing repo work when the active slice clearly matches in-flight changes.",
+    "Treat the launch pack as the active mission boundary.",
+    "Use subagents only when bounded decomposition is genuinely useful.",
+    "Compact long sessions before context gets muddy.",
+    "Return when done, blocked, scope expands, or product decisions become unclear.",
+  ],
+  cursor: [
+    "Keep the work close to the targeted files and interaction slice.",
+    "Use tight human-in-the-loop control for UI and taste-heavy edits.",
+    "Return when the slice is coherent or taste decisions need escalation.",
+  ],
+  codex: [
+    "Use for autonomous, sandboxed execution of well-scoped implementation tasks.",
+    "Codex runs in an isolated environment — keep scope narrow and self-contained.",
+    "Prefer Codex over Claude Code when the task is a clean, bounded code change with clear done-when criteria.",
+    "Return is async — expect a callback, not a synchronous response.",
+    "Return when the bounded slice is complete or the task cannot be finished without repo context beyond the sandbox.",
+  ],
+};
+
+export function getSurfacePlaybook(surface: Surface): SurfacePlaybook {
+  return surfacePlaybookSchema.parse({
+    surface,
+    notes: PLAYBOOKS[surface],
+  });
+}

package/node_modules/@switchboard/core/src/surface-profiles.ts

@@ -0,0 +1,166 @@
+/**
+ * Execution Surface Profiles
+ *
+ * Concrete profiles for each surface Switchboard routes to.
+ * These describe what the control plane can expect — not what the
+ * surface does internally.
+ *
+ * Switchboard is the layer above. It does not assume uniform API access.
+ */
+import type { SurfaceProfile } from "./types";
+import { surfaceProfileSchema } from "./types";
+
+// ---------------------------------------------------------------------------
+// Current surfaces (V1)
+// ---------------------------------------------------------------------------
+
+export const CLAUDE_CODE_PROFILE: SurfaceProfile = surfaceProfileSchema.parse({
+  surface_id: "claude-code",
+  surface_class: "api",
+  display_name: "Claude Code",
+  capabilities: {
+    can_dispatch_programmatically: true,
+    can_acknowledge: true,
+    can_return_structured: true,
+    can_stream: true,
+    requires_human_in_loop: false,
+    supports_working_directory: true,
+  },
+  receipt_model: "synchronous",
+  packet_format: "sdk_prompt",
+});
+
+export const CHATGPT_PROFILE: SurfaceProfile = surfaceProfileSchema.parse({
+  surface_id: "chatgpt",
+  surface_class: "api",
+  display_name: "ChatGPT (OpenAI)",
+  capabilities: {
+    can_dispatch_programmatically: true,
+    can_acknowledge: true,
+    can_return_structured: true,
+    can_stream: false,
+    requires_human_in_loop: false,
+    supports_working_directory: false,
+  },
+  receipt_model: "synchronous",
+  packet_format: "sdk_prompt",
+});
+
+/** @deprecated Use CHATGPT_PROFILE — ChatGPT is now auto-dispatched via OpenAI API. */
+export const CHATGPT_MANUAL_PROFILE = CHATGPT_PROFILE;
+
+export const CURSOR_PROFILE: SurfaceProfile = surfaceProfileSchema.parse({
+  surface_id: "cursor",
+  surface_class: "ide",
+  display_name: "Cursor",
+  capabilities: {
+    can_dispatch_programmatically: false,
+    can_acknowledge: false,
+    can_return_structured: false,
+    can_stream: false,
+    requires_human_in_loop: true,
+    supports_working_directory: true,
+  },
+  receipt_model: "human_return",
+  packet_format: "clipboard",
+});
+
+export const CODEX_PROFILE: SurfaceProfile = surfaceProfileSchema.parse({
+  surface_id: "codex",
+  surface_class: "cli",
+  display_name: "Codex",
+  capabilities: {
+    can_dispatch_programmatically: true,
+    can_acknowledge: true,
+    can_return_structured: true,
+    can_stream: false,
+    requires_human_in_loop: false,
+    supports_working_directory: true,
+  },
+  receipt_model: "async_callback",
+  packet_format: "sdk_prompt",
+});
+
+// ---------------------------------------------------------------------------
+// Future surfaces (defined now for routing clarity)
+// ---------------------------------------------------------------------------
+
+export const GEMINI_API_PROFILE: SurfaceProfile = surfaceProfileSchema.parse({
+  surface_id: "gemini-api",
+  surface_class: "api",
+  display_name: "Gemini",
+  capabilities: {
+    can_dispatch_programmatically: true,
+    can_acknowledge: true,
+    can_return_structured: true,
+    can_stream: true,
+    requires_human_in_loop: false,
+    supports_working_directory: false,
+  },
+  receipt_model: "synchronous",
+  packet_format: "sdk_prompt",
+});
+
+export const FILE_EXPORT_PROFILE: SurfaceProfile = surfaceProfileSchema.parse({
+  surface_id: "file-export",
+  surface_class: "file_based",
+  display_name: "File Export",
+  capabilities: {
+    can_dispatch_programmatically: false,
+    can_acknowledge: false,
+    can_return_structured: true,
+    can_stream: false,
+    requires_human_in_loop: true,
+    supports_working_directory: true,
+  },
+  receipt_model: "file_watch",
+  packet_format: "file_drop",
+});
+
+export const OPENAI_AUDIT_PROFILE: SurfaceProfile = surfaceProfileSchema.parse({
+  surface_id: "openai-audit",
+  surface_class: "audit_only",
+  display_name: "OpenAI Audit (read-only)",
+  capabilities: {
+    can_dispatch_programmatically: true,
+    can_acknowledge: true,
+    can_return_structured: true,
+    can_stream: false,
+    requires_human_in_loop: false,
+    supports_working_directory: false,
+  },
+  receipt_model: "synchronous",
+  packet_format: "sdk_prompt",
+});
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+const ALL_PROFILES: SurfaceProfile[] = [
+  CLAUDE_CODE_PROFILE,
+  CHATGPT_PROFILE,
+  CURSOR_PROFILE,
+  CODEX_PROFILE,
+  GEMINI_API_PROFILE,
+  FILE_EXPORT_PROFILE,
+  OPENAI_AUDIT_PROFILE,
+];
+
+export function getSurfaceProfile(surfaceId: string): SurfaceProfile | null {
+  return ALL_PROFILES.find(p => p.surface_id === surfaceId) ?? null;
+}
+
+export function getSurfacesByClass(surfaceClass: string): SurfaceProfile[] {
+  return ALL_PROFILES.filter(p => p.surface_class === surfaceClass);
+}
+
+export function canDispatchProgrammatically(surfaceId: string): boolean {
+  const profile = getSurfaceProfile(surfaceId);
+  return profile?.capabilities.can_dispatch_programmatically ?? false;
+}
+
+export function requiresHumanReturn(surfaceId: string): boolean {
+  const profile = getSurfaceProfile(surfaceId);
+  return profile?.receipt_model === "human_return" || false;
+}