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

package/node_modules/@switchboard/projections/node_modules/@switchboard/core/src/gate-state.ts

@@ -0,0 +1,296 @@
+import type {
+  GateState,
+  PressureAssessment,
+  ReconcileReport,
+  ReturnReport,
+} from "./types";
+import { gateStateSchema } from "./types";
+
+/**
+ * Derive an evidence-consistent gate state from reconcile + return data.
+ *
+ * Rules:
+ * - "accepted" requires: reconcile = accept AND (verification > 0 OR evidence > 0)
+ * - "accepted-with-cautions" requires: reconcile = accept-with-warnings AND some evidence exists
+ * - "held-for-review" requires: reconcile = review-required
+ * - "blocked-missing-evidence" requires: claims done but no verification AND no evidence
+ * - "pending" when reconcile hasn't run yet but return exists
+ * - "not-checked" when no return exists
+ *
+ * The `honest` flag is always true when generated by this function.
+ * It would be false only if someone manually overrode the label.
+ */
+export function deriveGateState(input: {
+  reconcile: ReconcileReport | null;
+  latestReturn: ReturnReport | null;
+  phase: string;
+}): GateState {
+  const { reconcile, latestReturn } = input;
+
+  // No return yet — not checked
+  if (!latestReturn) {
+    return gateStateSchema.parse({
+      label: "not-checked",
+      reason: "No execution return has been received yet.",
+      evidence_summary: { verification_count: 0, evidence_count: 0, criteria_met_count: 0, caution_count: 0, blocker_count: 0 },
+      honest: true,
+    });
+  }
+
+  const verificationCount = latestReturn.verification_run.length;
+  const evidenceCount = latestReturn.evidence.length;
+  const criteriaMetCount = latestReturn.success_criteria_met.length;
+  const cautionCount = reconcile?.findings.filter(f => f.severity === "warning").length ?? 0;
+  const blockerCount = reconcile?.findings.filter(f => f.severity === "review-required").length ?? 0;
+
+  const summary = {
+    verification_count: verificationCount,
+    evidence_count: evidenceCount,
+    criteria_met_count: criteriaMetCount,
+    caution_count: cautionCount,
+    blocker_count: blockerCount,
+  };
+
+  // No reconcile yet — pending
+  if (!reconcile) {
+    return gateStateSchema.parse({
+      label: "pending",
+      reason: "Return received but quality check has not run yet.",
+      evidence_summary: summary,
+      honest: true,
+    });
+  }
+
+  // Claims done but zero evidence — blocked
+  const claimsDone = latestReturn.status === "done" || latestReturn.objective_met === "yes";
+  if (claimsDone && verificationCount === 0 && evidenceCount === 0) {
+    return gateStateSchema.parse({
+      label: "blocked-missing-evidence",
+      reason: "Claims completion but has no verification and no evidence.",
+      evidence_summary: summary,
+      honest: true,
+    });
+  }
+
+  // Reconcile review-required — held
+  if (reconcile.recommendation === "review-required") {
+    return gateStateSchema.parse({
+      label: "held-for-review",
+      reason: `${blockerCount} blocker(s) found in quality check.`,
+      evidence_summary: summary,
+      honest: true,
+    });
+  }
+
+  // Cross-check: unresolved blockers in the return force a downgrade
+  const hasBlockers = latestReturn.blockers.filter(Boolean).length > 0;
+  const hasEscalations = latestReturn.escalations.filter(Boolean).length > 0;
+  const objectivePartial = latestReturn.objective_met === "partial" || latestReturn.objective_met === "no";
+  const doneWhenPartial = latestReturn.done_when_met === "partial" || latestReturn.done_when_met === "no";
+  const statusNotDone = latestReturn.status !== "done";
+
+  // Contradiction: "done" status but objective only partial or blockers exist
+  const contradicts = (latestReturn.status === "done" && objectivePartial) ||
+    (latestReturn.status === "done" && hasBlockers);
+
+  if (contradicts) {
+    const reasons: string[] = [];
+    if (objectivePartial) reasons.push(`objective_met=${latestReturn.objective_met}`);
+    if (hasBlockers) reasons.push(`${latestReturn.blockers.length} unresolved blocker(s)`);
+    return gateStateSchema.parse({
+      label: "accepted-with-cautions",
+      reason: `Status "done" but ${reasons.join(", ")}. Review recommended.`,
+      evidence_summary: summary,
+      honest: true,
+    });
+  }
+
+  // Force downgrade when blockers, escalations, partial objective, or partial done-when exist
+  const needsCaution = hasBlockers || hasEscalations || objectivePartial || doneWhenPartial || statusNotDone;
+
+  // Reconcile accept-with-warnings — accepted with cautions
+  if (reconcile.recommendation === "accept-with-warnings") {
+    return gateStateSchema.parse({
+      label: "accepted-with-cautions",
+      reason: `Accepted with ${cautionCount} caution(s). ${verificationCount} verification run(s), ${evidenceCount} evidence item(s).`,
+      evidence_summary: summary,
+      honest: true,
+    });
+  }
+
+  // Reconcile accept — accepted (only if real evidence exists AND no contradicting signals)
+  if (reconcile.recommendation === "accept") {
+    if ((verificationCount > 0 || evidenceCount > 0) && !needsCaution) {
+      return gateStateSchema.parse({
+        label: "accepted",
+        reason: `Accepted. ${verificationCount} verification run(s), ${evidenceCount} evidence item(s), ${criteriaMetCount} criteria met.`,
+        evidence_summary: summary,
+        honest: true,
+      });
+    }
+
+    // Has evidence but has caution signals — downgrade
+    if ((verificationCount > 0 || evidenceCount > 0) && needsCaution) {
+      const reasons: string[] = [];
+      if (hasBlockers) reasons.push(`${latestReturn.blockers.length} blocker(s)`);
+      if (hasEscalations) reasons.push(`${latestReturn.escalations.length} escalation(s)`);
+      if (objectivePartial) reasons.push(`objective ${latestReturn.objective_met} met`);
+      if (doneWhenPartial) reasons.push(`done_when ${latestReturn.done_when_met}`);
+      if (statusNotDone) reasons.push(`status: ${latestReturn.status}`);
+      return gateStateSchema.parse({
+        label: "accepted-with-cautions",
+        reason: `Reconcile passed but ${reasons.join(", ")}.`,
+        evidence_summary: summary,
+        honest: true,
+      });
+    }
+
+    // Accept with no evidence — downgrade to accepted-with-cautions
+    return gateStateSchema.parse({
+      label: "accepted-with-cautions",
+      reason: "Reconcile passed but no verification or evidence was provided.",
+      evidence_summary: summary,
+      honest: true,
+    });
+  }
+
+  // Fallback
+  return gateStateSchema.parse({
+    label: "pending",
+    reason: "State could not be determined.",
+    evidence_summary: summary,
+    honest: true,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Pressure-aware gate tightening
+// ---------------------------------------------------------------------------
+
+/**
+ * Post-process gate state with pressure assessment.
+ * Never loosens a gate — only tightens or preserves.
+ */
+export function tightenGateWithPressure(
+  gate: GateState,
+  pressure: PressureAssessment,
+): GateState {
+  // If already blocked or held, pressure cannot make it worse
+  if (gate.label === "blocked-missing-evidence" || gate.label === "held-for-review") {
+    return gate;
+  }
+
+  // If no pressure detected and evidence sufficient, no tightening needed
+  if (!pressure.pressure_detected && pressure.evidence_sufficiency === "sufficient") {
+    return gate;
+  }
+
+  // Pressure + insufficient evidence → block
+  if (pressure.pressure_detected && pressure.evidence_sufficiency === "insufficient") {
+    return gateStateSchema.parse({
+      ...gate,
+      label: "blocked-missing-evidence",
+      reason: `Pressured run with insufficient evidence. ${pressure.acceptance_decision_reason}`,
+      honest: true,
+    });
+  }
+
+  // Pressure + partial evidence → hold for review
+  if (pressure.pressure_detected && pressure.evidence_sufficiency === "partial") {
+    return gateStateSchema.parse({
+      ...gate,
+      label: "held-for-review",
+      reason: `Pressured run with partial evidence. ${pressure.acceptance_decision_reason}`,
+      honest: true,
+    });
+  }
+
+  // No pressure but insufficient evidence → downgrade to cautions
+  if (!pressure.pressure_detected && pressure.evidence_sufficiency === "insufficient") {
+    if (gate.label === "accepted") {
+      return gateStateSchema.parse({
+        ...gate,
+        label: "accepted-with-cautions",
+        reason: `Evidence insufficient for task type. ${pressure.acceptance_decision_reason}`,
+        honest: true,
+      });
+    }
+  }
+
+  // Pressure + sufficient evidence → downgrade accepted to cautions
+  if (pressure.pressure_detected && pressure.evidence_sufficiency === "sufficient") {
+    if (gate.label === "accepted") {
+      return gateStateSchema.parse({
+        ...gate,
+        label: "accepted-with-cautions",
+        reason: `Pressure signals present despite sufficient evidence. ${pressure.acceptance_decision_reason}`,
+        honest: true,
+      });
+    }
+  }
+
+  return gate;
+}
+
+// ---------------------------------------------------------------------------
+// Audit-aware gate tightening
+// ---------------------------------------------------------------------------
+
+/**
+ * Post-process gate state with audit result.
+ * Audit blockers prevent promotion. Audit cautions downgrade.
+ * Never loosens a gate.
+ */
+export function tightenGateWithAudit(
+  gate: GateState,
+  audit: { outcome: string; blocker_count: number; caution_count: number; audit_required: boolean },
+): GateState {
+  if (!audit.audit_required || audit.outcome === "not_required" || audit.outcome === "skipped") {
+    return gate;
+  }
+
+  if (gate.label === "blocked-missing-evidence" || gate.label === "held-for-review") {
+    return gate;
+  }
+
+  if (audit.outcome === "blocker") {
+    return gateStateSchema.parse({
+      ...gate,
+      label: "held-for-review",
+      reason: `Audit blocker: ${audit.blocker_count} audit finding(s) block promotion. ${gate.reason}`,
+      honest: true,
+    });
+  }
+
+  if (audit.outcome === "pass_with_cautions" && gate.label === "accepted") {
+    return gateStateSchema.parse({
+      ...gate,
+      label: "accepted-with-cautions",
+      reason: `Audit caution: ${audit.caution_count} audit finding(s). ${gate.reason}`,
+      honest: true,
+    });
+  }
+
+  return gate;
+}
+
+/**
+ * Human-facing label for gate states.
+ * No decorative trust language — only evidence-backed labels.
+ */
+export function gateLabel(state: GateState): { text: string; tone: string } {
+  switch (state.label) {
+    case "accepted":
+      return { text: `Accepted — ${state.evidence_summary.verification_count} check(s), ${state.evidence_summary.evidence_count} evidence`, tone: "ok" };
+    case "accepted-with-cautions":
+      return { text: `${state.evidence_summary.caution_count} caution(s)`, tone: "warn" };
+    case "held-for-review":
+      return { text: "Held for review", tone: "error" };
+    case "blocked-missing-evidence":
+      return { text: "Blocked — missing evidence", tone: "error" };
+    case "pending":
+      return { text: "Pending check", tone: "neutral" };
+    case "not-checked":
+      return { text: "Not yet checked", tone: "neutral" };
+  }
+}

package/node_modules/@switchboard/projections/node_modules/@switchboard/core/src/gates.ts

@@ -0,0 +1,198 @@
+import type {
+  ApprovalGate,
+  DriftDiff,
+  GateReason,
+  HoldState,
+  ProjectLedger,
+  ReconcileV2Result,
+  ReturnReport,
+  ReviewPacket,
+} from "./types";
+import { holdStateSchema, reviewPacketSchema } from "./types";
+import { decisions, constraints } from "./ledger";
+
+let _gateCtr = 0;
+function gateId(): string { return `gate-${++_gateCtr}-${Date.now().toString(36)}`; }
+
+// ---------------------------------------------------------------------------
+// Gate evaluation
+// ---------------------------------------------------------------------------
+
+export function evaluateGates(input: {
+  diff: DriftDiff;
+  ledger: ProjectLedger;
+  reconcile: ReconcileV2Result;
+  report: ReturnReport;
+}): ApprovalGate[] {
+  const gates: ApprovalGate[] = [];
+  const now = new Date().toISOString();
+
+  // 1. Major scope change — requirements removed
+  const removed = input.diff.entries.filter(d => d.action === "removed");
+  if (removed.length > 0) {
+    gates.push(createGate("requirement-removal",
+      `${removed.length} requirement(s) removed: ${removed.map(r => r.old_text?.slice(0, 40)).join(", ")}.`,
+      ["Explicit approval for each removal.", "Scope change record with reason."],
+      "Approve the removal or restore the requirement.", now,
+    ));
+  }
+
+  // 2. Unparented high-impact decisions
+  const decs = decisions(input.ledger);
+  const unparented = decs.filter(d =>
+    d.evidence_type === "weak-inference" && d.evidence_refs.length === 0 && d.risk_level !== "low",
+  );
+  if (unparented.length > 0) {
+    gates.push(createGate("unparented-high-impact-decision",
+      `${unparented.length} decision(s) without evidence: ${unparented.map(d => d.text.slice(0, 40)).join(", ")}.`,
+      ["Evidence reference for each decision.", "Parent requirement linkage."],
+      "Add evidence or downgrade risk level.", now,
+    ));
+  }
+
+  // 3. Weak evidence + high risk
+  const highRisk = input.ledger.entries.filter(e => e.risk_level === "high" && e.evidence_type === "weak-inference");
+  if (highRisk.length > 0) {
+    gates.push(createGate("weak-evidence-high-risk",
+      `${highRisk.length} high-risk entry(ies) with only weak inference: ${highRisk.map(e => e.text.slice(0, 40)).join(", ")}.`,
+      ["Stronger evidence (user-backed or research-backed).", "Explicit risk acceptance."],
+      "Strengthen evidence or explicitly accept the risk.", now,
+    ));
+  }
+
+  // 4. Destructive rewrite — many modifications + large scope change
+  const modified = input.diff.entries.filter(d => d.action === "modified");
+  const added = input.diff.entries.filter(d => d.action === "added");
+  if (modified.length >= 3 || (modified.length >= 2 && added.length >= 2)) {
+    gates.push(createGate("destructive-rewrite",
+      `Large-scale changes: ${modified.length} modified, ${added.length} added, ${removed.length} removed.`,
+      ["Review of all modifications.", "Confirmation that intent is preserved."],
+      "Review the diff and confirm no silent intent change.", now,
+    ));
+  }
+
+  // 5. Trust boundary change — execution return mentions multi-user/team without prior constraint
+  const returnText = `${input.report.summary} ${input.report.decisions_made.join(" ")}`.toLowerCase();
+  const hasTeamMention = /\b(team|multi.?user|admin|permission|role|workspace)\b/.test(returnText);
+  const hadTeamConstraint = constraints(input.ledger).some(c => /\b(team|multi.?user|admin|workspace)\b/i.test(c.text));
+  if (hasTeamMention && !hadTeamConstraint) {
+    gates.push(createGate("trust-boundary-change",
+      "Execution introduced multi-user/team/admin concepts not in original constraints.",
+      ["Explicit approval for trust boundary expansion."],
+      "Approve the boundary change or reject the scope expansion.", now,
+    ));
+  }
+
+  return gates;
+}
+
+function createGate(
+  reason: GateReason,
+  detail: string,
+  evidence_missing: string[],
+  resolution_path: string,
+  timestamp: string,
+): ApprovalGate {
+  return { id: gateId(), reason, detail, triggered_by: "reconcile-v2", evidence_missing, resolution_path, created_at: timestamp };
+}
+
+// ---------------------------------------------------------------------------
+// Hold state
+// ---------------------------------------------------------------------------
+
+export function buildHoldState(gates: ApprovalGate[]): HoldState {
+  if (gates.length === 0) {
+    return holdStateSchema.parse({ held: false, gates: [], summary: "No gates triggered." });
+  }
+
+  const actions = gates.map(g => g.resolution_path).filter(Boolean);
+  return holdStateSchema.parse({
+    held: true,
+    gates,
+    held_since: new Date().toISOString(),
+    summary: `${gates.length} gate(s): ${gates.map(g => g.reason).join(", ")}.`,
+    resolution_actions: actions,
+  });
+}
+
+export function resolveGate(hold: HoldState, gateId: string): HoldState {
+  const remaining = hold.gates.filter(g => g.id !== gateId);
+  if (remaining.length === 0) {
+    return holdStateSchema.parse({ held: false, gates: [], summary: "All gates resolved." });
+  }
+  return holdStateSchema.parse({
+    ...hold,
+    gates: remaining,
+    summary: `${remaining.length} gate(s) remaining: ${remaining.map(g => g.reason).join(", ")}.`,
+    resolution_actions: remaining.map(g => g.resolution_path).filter(Boolean),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Review packet generation
+// ---------------------------------------------------------------------------
+
+export function generateReviewPacket(input: {
+  project_id: string;
+  spec_generation: number;
+  diff: DriftDiff;
+  ledger: ProjectLedger;
+  reconcile: ReconcileV2Result;
+  report: ReturnReport;
+  gates: ApprovalGate[];
+}): ReviewPacket {
+  const decs = decisions(input.ledger);
+  const decisionsWithEvidence = decs.map(d => ({
+    text: d.text,
+    evidence_type: d.evidence_type,
+    has_refs: d.evidence_refs.length > 0,
+    ...(d.risk_level ? { risk_level: d.risk_level } : {}),
+  }));
+
+  const changedConstraints = input.diff.entries
+    .filter(d => d.kind === "constraint")
+    .map(d => `${d.action}: ${(d.new_text || d.old_text || "").slice(0, 60)}`);
+
+  const warnings = input.reconcile.checks
+    .filter(c => !c.passed && c.severity === "warning")
+    .map(c => `${c.check}: ${c.detail}`);
+
+  const missingEvidence = input.reconcile.checks
+    .filter(c => !c.passed)
+    .flatMap(c => {
+      if (c.check === "provenance-minimums") return [c.detail];
+      if (c.check === "decision-evidence") return [c.detail];
+      if (c.check === "execution-evidence") return [c.detail];
+      return [];
+    });
+
+  const recommendation = input.gates.length > 0
+    ? "review-required" as const
+    : input.reconcile.recommendation;
+
+  const summaryParts: string[] = [];
+  if (input.gates.length > 0) summaryParts.push(`${input.gates.length} approval gate(s) triggered.`);
+  if (input.reconcile.blockers > 0) summaryParts.push(`${input.reconcile.blockers} reconcile blocker(s).`);
+  if (input.reconcile.warnings > 0) summaryParts.push(`${input.reconcile.warnings} reconcile warning(s).`);
+  if (changedConstraints.length > 0) summaryParts.push(`${changedConstraints.length} constraint change(s).`);
+  if (summaryParts.length === 0) summaryParts.push("Clean return. No gates triggered.");
+
+  return reviewPacketSchema.parse({
+    project_id: input.project_id,
+    spec_generation: input.spec_generation,
+    requirement_diff_summary: input.diff.summary,
+    changed_constraints: changedConstraints,
+    decisions_with_evidence: decisionsWithEvidence,
+    execution_proof: {
+      verification_count: input.report.verification_run.length,
+      evidence_count: input.report.evidence.length,
+      criteria_met_count: input.report.success_criteria_met.length,
+      summary: `${input.report.verification_run.length} verification(s), ${input.report.evidence.length} evidence, ${input.report.success_criteria_met.length} criteria met.`,
+    },
+    warnings,
+    missing_evidence: missingEvidence,
+    gates: input.gates,
+    recommendation,
+    human_summary: summaryParts.join(" "),
+  });
+}