sembl-stack

A swappable, spec-driven software factory. A task becomes declared bounds, an agent writes the change inside a disposable sandbox, the Sembl gate judges the real diff against those bounds, a PASS merges and deploys, and a post-deploy gate confirms it's healthy — or rolls it back. Every stage is an interchangeable adapter behind one typed artifact contract, and every run is recorded.

We sell process correctness — the change did what the spec declared, stayed in bounds, is honestly evidenced, and reached production accountably — never "the model writes better code." The stack takes no side in the agent wars: swap the executor, the sandbox, or the deploy target with one line of config and the rest of the pipeline doesn't notice.

Website · The gate (Sembl) · Architecture & plan

task ─▶ bounds ─▶ execute ─▶ sandbox ─▶ SEMBL GATE ─▶ merge ─▶ deploy ─▶ verify-in-prod
        (L2)       (L3)        (L4)       (L5)         (L6.5)    (L7)       (L8)
                                          every arrow is a typed artifact on disk

Quickstart

pip install sembl-stack
cd your-repo
sembl-stack

That's the whole quickstart. Bare sembl-stack launches the guided run — an OpenCode-style TUI that walks you through, one screen at a time:

1. repo — confirms the repo it detected (a fresh non-git directory is offered a safe demo scaffold instead)
2. agent & keys — every way to run AI work, with live status: is Claude Code installed and logged in, which API-key env vars are set, is OpenCode on PATH — and exactly what to do for any option you're missing (mock always works, zero keys)
3. task — describe the change in plain English and pick which paths the agent may touch (suggested from your repo); the tool writes task.yaml/bounds.json, you never do
4. run — the live stage rail (BLOCK → feedback → retry → PASS), then the verdict with its receipt and the one next command

Everything the guide does is also a scriptable command (same machinery, byte-identical runs — that's the point):

sembl-stack init                  # scaffold config + starter task + demo repo
sembl-stack doctor                # config-aware preflight
sembl-stack loop task.yaml        # plan → execute → gate → retry-on-BLOCK
sembl-stack runs [<id>]           # list / inspect runs
sembl-stack apply <id>            # apply the accepted patch (a BLOCK is never applied)

Presets (sembl-stack init --preset …):

Swap any layer in sembl.stack.yaml — e.g. execute: opencode, execute: aider — with no code change.

The stage map (L0–L8)

Each stage consumes and produces typed artifacts; that hand-off is the whole interface, which is what makes every stage swappable.

We own exactly three things: the artifact contract + stage Protocol, the gate (L5 + the post-deploy L8), and the glue + layer-replacement protocol. Everything else is deliberately a best-in-class tool behind an interface.

The accountable spine

A verdict is bound to the change it judged — most agent pipelines stop at "the check passed"; this one guarantees a verdict can only ship the exact change it was issued for:

• Verdicts carry their subject. Every verdict is stamped with the SHA-256 and file set of the diff it judged. apply recomputes the patch hash and refuses a verdict issued for a different patch; merge refuses if the merge would ship files the verdict never saw.
• BLOCK means blocked. A BLOCK verdict is never applied and never merged — the loop retries the executor instead. Overrides (--skip-binding-check) exist but are recorded permanently in the MergeRecord.
• Production is gated too. After deploy, the L8 gate checks the live delivery (health + payload, deterministically) and triggers a rollback when it fails.

Every run leaves a complete paper trail in .sembl/runs/<id>/:

.sembl/runs/2ca41f/
├─ task.json          # what was asked
├─ bounds.json        # the declared contract
├─ change.json        # the actual diff
├─ verdict.json       # the gate's judgement + subject binding
├─ merge-record.json  # what shipped, and under whose PASS
└─ trace.json         # the timeline

The guided TUI

The guide is the default surface (see Quickstart) and a core dependency — no extra install. It streams the real loop live under your configured profile and is byte-identical to a headless sembl-stack loop, because it drives the same adapters. Re-run the agent & keys step anytime with sembl-stack --reconfigure.

The full picture

→ docs/PROCESS-ACTION-PLAN.md is the single source of truth: architecture, the L0–L8 stage map with build status, the eval metric, locked decisions, the guided-TUI vision, and the remaining-work plan.

Reference: process-self-improvement.md (north-star theory) · eval-metric-O3.md (the metric) · memory-plane-hypothesis.md.

Local development

uv sync --extra all
uv pip install -e ../sembl          # or: pip install sembl
.venv/Scripts/python -m pytest -q   # run from the repo root (corpus paths are cwd-relative)

Releasing

Publishing uses GitHub Actions + PyPI Trusted Publishing (OIDC); no tokens are stored. .github/workflows/release.yml builds and publishes when you publish a GitHub Release whose tag (vX.Y.Z) matches pyproject.toml and sembl_stack/__init__.py.

Agents write the code. sembl-stack makes the whole pipeline accountable.