switchboard-cli 0.1.0-alpha.4 → 0.1.0-alpha.5

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0-alpha.5
+
+- First installable release: `npm install -g switchboard-cli` now works standalone.
+- `@switchboard/core` and `@switchboard/projections` are compiled into the published
+  bundle (`dist/index.cjs`) — no unpublished workspace dependencies in the manifest.
+- Runs as plain JavaScript; `tsx` is no longer a runtime dependency.
+- Runtime dependencies reduced to `commander`, `yaml`, `zod`.
+- Prior published versions (alpha.1–alpha.4) were uninstallable outside the monorepo
+  (raw `workspace:*` or unpublished `@switchboard/*` dependencies).
+
+## 0.1.0-alpha.4
+
+- Positions `switchboard-cli` as the primary CLI-first package for the portable governance substrate.
+- Includes the governed pipeline: `init`, `compile`, `packet`, `run`, `ingest`, `audit`, `receipt`, and `evaluate`.
+- Documents the calibration harness for blind, replay, and adversarial trust-machinery checks.
+- Documents AutoAgent local, hybrid, cloud, parallel, and adaptive-governance modes as alpha surfaces.
+- Aligns publish metadata so the CLI no longer advertises stale `workspace:*` dependencies.

package/README.md

@@ -1,121 +1,177 @@
-# @switchboard/cli
+# switchboard-cli
 
 Portable governance substrate for AI workflows.
 
-Compile specs, dispatch to Claude/ChatGPT/Cursor/Codex, ingest structured returns, issue trust receipts, evaluate independently, and calibrate your pipeline.
+Switchboard keeps project intent, dispatch context, returns, audits, receipts, and evaluation evidence in a repo-local `.switchboard/` tree. The CLI is the primary interface; any web surface is only another view over the same governance state.
 
-> **Alpha release.** Expect breaking changes. [Report issues](https://github.com/switchboard-foundation/switchboard/issues).
+> Alpha release: `0.1.0-alpha.4`. Expect rough edges and breaking changes. Use it for governed experiments, demos, and research workflows before depending on it as production infrastructure.
 
 ## Install
 
 ```bash
-npm install -g @switchboard/cli
+npm install -g switchboard-cli
+sb --version
 ```
 
-Requires Node >= 18.
+Requires Node.js 18 or newer.
+
+## What it does
+
+Switchboard is not a chat wrapper or vendor gateway. It is a file-based governance layer around AI-assisted work:
+
+- compile canonical project state into an execution contract
+- generate SBX packets for Claude, ChatGPT, Cursor, or Codex-style surfaces
+- ingest structured returns and reconcile them against the contract
+- issue receipts that describe what was actually verified
+- run independent evaluation against the latest receipt
+- calibrate the trust machinery with blind, replay, and adversarial seeds
+- run AutoAgent improvement loops with local, hybrid, cloud, parallel, and adaptive-governance modes
+
+The core design goal is deterministic, inspectable workflow state rather than clever orchestration.
 
 ## Quick start
 
 ```bash
-# Initialize a governed project
+# Scaffold repo-local governance state
 sb init
 
-# Compile project contract + spec from canonical state
+# Compile the current project contract and objective
 sb compile
 
-# Generate a dispatch packet for a surface
-sb packet claude    # or: chatgpt, cursor, codex
+# Generate a packet for a target surface
+sb packet claude
+sb packet chatgpt
+sb packet cursor
+sb packet codex
 
-# Launch governed dispatch to Claude Code
+# Dispatch to Claude Code, then ingest the structured return
 sb run claude
-
-# Ingest the structured return
 sb ingest
 
-# Issue an immutable trust receipt
+# Generate independent review context and issue a receipt
+sb audit codex
 sb receipt
 
-# Export receipt as standalone JSON
-sb receipt --export json
-
-# Run independent evaluation
+# Evaluate the receipt independently
 sb evaluate
-
-# Run the two-layer calibration harness
-sb calibrate
 ```
 
-## Pipeline
+The normal path is:
 
-```
-init -> compile -> packet -> run -> ingest -> receipt -> evaluate
-                                                            |
-                                                        calibrate
+```text
+init -> compile -> packet -> run -> ingest -> audit -> receipt -> evaluate
 ```
 
-Each step reads from and writes to `.switchboard/` in your project root. All state is file-based (YAML + Markdown). No database, no hosted service.
+Every step reads from or writes to `.switchboard/` in the current project root.
 
 ## Commands
 
-| Command | What it does |
-|---------|-------------|
-| `sb init` | Scaffold `.switchboard/` directory with contract, working state, and spec |
-| `sb compile` | Compile a loop contract from canonical state |
-| `sb packet <surface>` | Generate a governed dispatch packet (SBX bundle) |
-| `sb run claude` | Dispatch to Claude Code via Agent SDK with proof capture |
-| `sb ingest` | Ingest structured SB_RETURN.yaml, run reconciliation + gates |
-| `sb receipt` | Build immutable ReceiptIssuedV2 from persisted ingest artifacts |
-| `sb receipt --export json` | Export receipt as standalone JSON file |
-| `sb receipt --export yaml` | Export receipt as standalone YAML file |
-| `sb evaluate` | Run independent evaluation on the latest receipt |
-| `sb audit codex` | Generate Codex audit packet for independent review |
-| `sb calibrate` | Run two-layer calibration harness |
+| Command | Purpose |
+| --- | --- |
+| `sb init` | Scaffold `.switchboard/` with project, working, routing, export, and return state |
+| `sb compile` | Compile the current canonical state into a governed loop contract |
+| `sb compile --objective "<text>"` | Override the loop objective for the next compile |
+| `sb compile --surface <surface>` | Force a target surface: `claude-code`, `chatgpt`, `cursor`, or `codex` |
+| `sb packet <surface>` | Generate an SBX dispatch bundle for `claude`, `chatgpt`, `cursor`, or `codex` |
+| `sb packet <surface> --force` | Generate a packet despite blocking integrity findings |
+| `sb run claude` | Dispatch the latest governed packet to Claude Code through the local transport |
+| `sb run claude --dry-run` | Prepare dispatch metadata without executing |
+| `sb ingest` | Ingest the expected structured return and persist reconciliation, gate, and audit inputs |
+| `sb ingest --file <path>` | Ingest a specific return YAML file |
+| `sb audit codex` | Generate and optionally execute Codex audit context for independent review |
+| `sb receipt` | Build a receipt from the latest persisted ingest artifacts |
+| `sb receipt --export json` | Export the receipt as standalone JSON |
+| `sb receipt --export yaml` | Export the receipt as standalone YAML |
+| `sb evaluate` | Run the independent evaluation lane against the latest audited receipt |
+| `sb calibrate` | Run the two-layer calibration harness |
+| `sb autoagent` | Run the governed autonomous improvement loop |
+
+## Receipts and evaluation
+
+Receipts are intended to be honest evidence artifacts, not certificates. A receipt records the dispatch, ingest result, reconciliation findings, audit status, gate posture, and what the system can defensibly say about the run.
+
+`sb evaluate` is deliberately separate from receipt generation. It reads the latest receipt and writes an independent assessment so that execution, receipt issuance, and evaluation do not collapse into one self-affirming step.
 
 ## Calibration
 
-The calibration harness tests the trust machinery itself:
-
-- **Layer A** (internal): Runs seeds through the real governance pipeline with full trace access
-- **Layer B** (external): Scores independently with zero imports from core — only sees raw output
-- **Blind seeds**: Fresh ideas the system has never seen
-- **Adversarial seeds**: Designed to break the machinery (scope traps, non-goal evasion, evidence gaps)
-- **Living ledger**: Every run appends to an auditable history with trends
+`sb calibrate` tests the trust machinery itself.
 
 ```bash
-# Default run: 5 blind + 3 adversarial seeds
+# Default mix
 sb calibrate
 
-# Custom mix
+# Custom seed counts
 sb calibrate --blind 10 --adversarial 5
 
-# Stress test only
+# Adversarial-only run
 sb calibrate --adversarial-only 8
 
-# Review pending escalations
-sb calibrate --review
+# Replay-only run
+sb calibrate --replay-only
 
-# Show calibration trends
+# Review pending escalations and trends
+sb calibrate --review
 sb calibrate --trends
 ```
 
-## Trust machinery
+The harness compares an internal pipeline verdict with an external scorer that has no imports from the core implementation. Disagreements become calibration evidence rather than hidden failures.
+
+## AutoAgent
+
+AutoAgent is an alpha improvement loop for governed projects. It expects:
+
+- `.switchboard/autoagent/program.md`: what the loop should improve
+- `.switchboard/autoagent/score.ts`: a score function that returns a numeric result
+
+Common modes:
+
+```bash
+# Local loop; defaults to adaptive governance
+sb autoagent --tier code --max-iterations 5
+
+# Harness or full autonomy tiers
+sb autoagent --tier harness
+sb autoagent --tier full
+
+# Explicit governance mode
+sb autoagent --governance full
+sb autoagent --governance light
+sb autoagent --governance none
+sb autoagent --governance adaptive
+
+# Cloud coordinator or hybrid coordinator/local-worker modes
+sb autoagent --cloud --tier code
+sb autoagent --hybrid --tier code
+
+# Cloud parallel mode: three workers test hypotheses concurrently
+sb autoagent --cloud --parallel --tier code
+
+# Inspect or control a cloud session
+sb autoagent --status
+sb autoagent --stream
+sb autoagent --steer "focus on the highest-scoring hypothesis"
+sb autoagent --stop
+
+# Review or restore results
+sb autoagent --results
+sb autoagent --rollback
+```
+
+Adaptive governance starts with low overhead, then escalates when score jumps, boundaries are crossed, research pivots occur, or enough kept iterations accumulate. Dangerous-project keywords such as financial, live, credential, deploy, and production force full governance.
 
-The governance pipeline enforces:
+Cloud, hybrid, and parallel modes are included for showcase and research use. They may require local credentials, available vendor CLIs, and operator supervision.
 
-- **Honesty guardrails**: Banned terms ("certified", "guaranteed", "no issues") in receipts
-- **Reconciliation**: Six drift checks (scope inflation, non-goal violation, goal drift, target-user shift, untracked decisions, evidence contradiction)
-- **Gates**: Approval gates for scope changes, unparented decisions, weak evidence, trust boundary changes
-- **Claim spread**: Deterministic measurement of how far executor claims drift from proven evidence
-- **Receipts**: Immutable trust artifacts with claim assessments, verification results, and closure basis
+## Alpha boundaries
 
-## What this is NOT
+Switchboard currently optimizes for a clear CLI-first research/showcase path:
 
-- Not a chat wrapper
-- Not an LLM gateway
-- Not an eval platform
-- Not an autonomous agent
+- canonical state lives in `.switchboard/`
+- package internals are TypeScript source run through `tsx`
+- receipts and evaluation are evidence records, not guarantees
+- cloud and managed-agent paths are experimental
+- public npm publication requires the internal packages to be published before the CLI
 
-It is a governance substrate. It preserves project coherence while you bounce work across AI surfaces.
+It intentionally does not try to be an enterprise control plane, observability product, generic eval platform, or vendor-sprawl abstraction.
 
 ## License
 

package/bin/switchboard.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+/**
+ * Switchboard CLI bin shim (CommonJS).
+ *
+ * CJS on purpose: npm 11.7+'s bin validation rejects .mjs bin targets
+ * ("script name ... was invalid") and silently strips them at publish,
+ * shipping a package with no executables. This package is CJS-default,
+ * so a .js shim is both valid and runnable.
+ *
+ * Published package: ships no src/, only the bundled CJS build at
+ * ../dist/index.cjs (plain JS — no tsx, no TypeScript toolchain at runtime).
+ *
+ * Monorepo dev: src/ is present, so the shim spawns tsx on the TypeScript
+ * entrypoint — live source always wins over a possibly stale dist/ build.
+ * Works from any cwd — resolves paths relative to this file, not the caller.
+ */
+
+const { existsSync } = require("node:fs");
+const { execFileSync } = require("node:child_process");
+const { resolve } = require("node:path");
+
+const sourceEntry = resolve(__dirname, "..", "src", "index.ts");
+const bundled = resolve(__dirname, "..", "dist", "index.cjs");
+
+function runBundled() {
+  // Bundled entrypoint parses process.argv itself (commander).
+  require(bundled);
+}
+
+if (!existsSync(sourceEntry)) {
+  // Published install: no src/ in the tarball — run the bundle.
+  if (!existsSync(bundled)) {
+    console.error("switchboard: corrupted install — dist/index.cjs is missing. Reinstall switchboard-cli.");
+    process.exit(1);
+  }
+  runBundled();
+} else {
+  // Monorepo dev: run from TypeScript source via tsx.
+  const tsxPaths = [
+    resolve(__dirname, "..", "node_modules", ".bin", "tsx"),
+    "tsx",
+  ];
+
+  let tsxBin;
+  for (const candidate of tsxPaths) {
+    try {
+      execFileSync(candidate, ["--version"], { stdio: "ignore" });
+      tsxBin = candidate;
+      break;
+    } catch {
+      // try next
+    }
+  }
+
+  if (!tsxBin) {
+    if (existsSync(bundled)) {
+      // No tsx available but a build exists — better than failing.
+      runBundled();
+    } else {
+      console.error("switchboard: could not find tsx. Run `pnpm install` in the monorepo root.");
+      process.exit(1);
+    }
+  } else {
+    try {
+      execFileSync(tsxBin, [sourceEntry, ...process.argv.slice(2)], {
+        stdio: "inherit",
+        cwd: process.cwd(),
+      });
+    } catch (err) {
+      // execFileSync throws on non-zero exit; the child already printed output
+      process.exit(err.status !== undefined && err.status !== null ? err.status : 1);
+    }
+  }
+}