Bridge

Bridge is a command-line tool that coordinates codebase verification. It reports evidence obligations across code, specifications, and tests as the system changes.

Bridge does not implement the underlying verifiers. It maps changed files to project subsystems, determines which project-owned checks are required by policy, runs configured commands when asked, and tracks their results.

---

Installation & Setup

Bridge 0.3.0 intentionally breaks older phase-bearing profiles and one library API entry point. Consumers upgrading from 0.2.x should read the 0.3 migration notes.

Bridge uses the com.blockether/bridge coordinate and can be run from Babashka or the Clojure CLI.

Babashka

Install Babashka, then register Bridge in your project's bb.edn:

{:deps {com.blockether/bridge {:mvn/version "0.3.0"}}
 :tasks
 {bridge {:doc "Run Bridge"
          :requires ([bridge.cli :as cli])
          :task (apply cli/-main *command-line-args*)}}}

Clojure CLI

Add the same coordinate to deps.edn:

{:deps {com.blockether/bridge {:mvn/version "0.3.0"}}
 :aliases {:bridge {:main-opts ["-m" "bridge.cli"]}}}

Use clojure -M:bridge in place of bb bridge below.

Initialize the Configuration

Run the initializer from your repository root:

bb bridge init

This creates:

• .bridge/profile.yaml (project profile defining subsystems and evidence commands)
• .bridge/verification-policy.yaml (rules outlining what evidence is required)
• .bridge/ephemeral/evidence/ (runtime evidence receipts and captures)

Install Git Hooks (Optional)

To gate the exact index before commit and recheck exact pushed trees:

bb bridge install-hooks

---

Core Concepts & Gradual Workflow

Bridge is designed for gradual adoption. You do not need to configure everything at once; you can start by tracking simple tests and add more verification checks as needed.

Step 1: Define Your Profile & Policy

The workflow relies on two core configuration files:

• Project Profile (profile.yaml): Maps directory structures and file paths to project subsystems, and registers the shell commands (e.g. unit tests, integration tests) used to verify them.
• Verification Policy (verification-policy.yaml): Defines what evidence is required for changes to specific subsystems before they are considered ready to merge. It may also declare access to Bridge-owned paths for an external capability-enforcing operator such as Vis. Bridge validates that declaration but does not enforce filesystem access itself.

Step 2: Check Status and Find Next Steps

When files change, Bridge uses your profile and policy to evaluate what needs to be verified.

• Check Status:

  bb bridge check --format json
  

  Bare check is iterative: it analyzes the current working snapshot, including staged, unstaged, and untracked files. It never silently becomes a commit gate.

• Find Next Step:

  bb bridge next
  

  This inspects outstanding obligations and suggests the immediate next action to take (e.g., pointing you to the exact test command to run).

Step 3: Run Evidence Commands

To view and run verification commands registered in your profile:

# List all registered commands
bb bridge list-evidence

# Run a specific command (e.g., unit tests)
bb bridge run-evidence --id unit

Executing a command via run-evidence generates an evidence-run receipt in .bridge/ephemeral/evidence/. When you run bb bridge check --format json again, Bridge considers fresh receipts of the required normalized evidence kind. A parsed passing result can complete an obligation; failed or partial results cannot. For commands without a decisive parser, the current check projection treats a fresh, executed zero-exit unknown receipt as passed, so configure a result parser when exit zero does not establish verification truth. Candidate-mode receipts must also match the exact candidate, frontier, and governance digests. Receipt subjects determine grouping and the content fingerprint used for freshness. The canonical loop is check → run-evidence → check; repeat it until the status is clear.

Step 4: Verify an Exact Commit Candidate

Candidate mode is explicit:

# One-time trust bootstrap for an already trusted, configured HEAD.
bb bridge check --tree HEAD --frontier HEAD --approve --format json

# Plan obligations for exactly what is staged.
bb bridge check --index --format json

# Run the pinned action returned by next_action (example values shown).
bb bridge run-evidence --id unit --tree <candidate-tree> --frontier <frontier-tree>

# Recheck the unchanged index and record an explicit local approval.
bb bridge check --index --approve --format json

--index resolves the index with git write-tree; --tree pins any commit or tree object. Bridge compares that candidate with the nearest approved ancestor, checks it in a disposable linked worktree, and binds receipts to the candidate tree, frontier tree, and governance digests. It does not copy ambient untracked files into the candidate. Put reproducible setup in tracked evidence scripts so the same preparation can run in a clean CI checkout.

A commit is not verified merely because it exists. A tree becomes a verified frontier only through an explicit clear approval (which may have fresh receipts, reused exact-tree receipts, or no evidence obligations). Approvals are Git-private local state. When project policy includes CI, CI should rerun candidate verification for the exact pushed SHA and publish its result; Bridge itself does not require a particular hook or CI flow.

Step 5: Gradual Expansion

Keep agent prompts and non-executable semantic and governance knowledge in ordinary version-controlled documents. Bridge does not treat prose as runtime state or evidence. See observable semantics and omission decisions for guidance.

---

CLI Command Reference

Common commands for everyday development:

# Initialize configuration files
bb bridge init

# Verify current status and list missing evidence
bb bridge check --format json

# Evaluate the last committed patch instead of the live working tree
bb bridge check --git-diff HEAD^1 --format json

# Verify the exact staged candidate
bb bridge check --index --format json

# Verify an exact CI checkout against an explicitly trusted base
bb bridge check --tree "$GITHUB_SHA" --frontier "$BASE_SHA" --format json

# Show the recommended next verification step
bb bridge next

# List registered verification commands
bb bridge list-evidence

# Run an evidence command with a dry run (shows the shell command without executing)
bb bridge run-evidence --id unit --dry-run

# Run an evidence command and record the receipt
bb bridge run-evidence --id unit

# Validate the schema of an individual artifact file
bb bridge validate-artifact .bridge/verification-policy.yaml

# Validate Bridge policy and receipt files in a directory
bb bridge validate-dir .bridge/ephemeral/evidence

Commands listed under Stable commands in bb bridge help follow the 0.3.x compatibility contract.

The stable command names are init, migrate-profile, install-hooks, validate-artifact, validate-dir, check, next, auto, list-evidence, and run-evidence. Use init for complete repository bootstrap and check --format summary or check --format json for status. debug-profile remains available as an experimental diagnostic.

---

Authoritative State

Bridge has two schema-validated artifact kinds:

• verification-policy configures evidence obligations and may carry a declarative path-access policy for an external operator.
• evidence-run is the canonical runtime receipt written by run-evidence.

Bridge derives current status, obligations, receipt freshness, convergence, and the next action from the project profile, policy, selected change, and fresh receipts. These are views, not manually maintained artifacts. Design rationale, plans, coverage arguments, and reports belong in ordinary documentation.

Evidence receipts are grouped only by their exact subject. Consumers can read receipt fields directly with ordinary map access such as get-in.

Direct validators define the three accepted data shapes—the project profile and the two artifact kinds above—and report errors with their exact nested field paths.

---

Subsystem Categories

Subsystem categories are labels available to policy rules through scope.system_categories. They do not add obligations by themselves; only a matching policy rule changes verification requirements. Accepted labels include:

• distributed, actor-message, shared-memory, lock-free, and async-runtime
• api, business-rule, data-pipeline, legacy, and other

---

Library API

Bridge can be consumed as a library (the Vis bridge extension is the reference consumer). The only supported entry point is the bridge.api namespace; every public var there is part of the stable 0.3.x source contract, and (bridge.api/contract) returns the inventory as data. All other bridge.* namespaces are internal. See docs/api.md for the full contract and change policy, and CHANGELOG.md for contract-level changes.

---

Repo Layout

• src/bridge/ — CLI and verification engine implementation.
• examples/ — Sample profiles and policy setups (e.g., examples/generic/).
• docs/ — Public API, workflow guidance, and design-document examples.
• test/ — Core automated test suite.

---

Examples

• Generic Example: See examples/generic/ for a simple profile and policy.
• Design documentation: See observable semantics and omission decisions.