sembl-stack 0.1.0__py3-none-any.whl

sembl_stack/tracing.py

@@ -0,0 +1,51 @@
+"""L6 observability: Langfuse tracing, with a no-op fallback.
+
+`span(name)` is a context manager around each loop node. If Langfuse isn't enabled or
+installed, it's a no-op — the loop runs identically, just untraced.
+"""
+from __future__ import annotations
+
+from contextlib import contextmanager
+
+
+class _NoopTracer:
+    enabled = False
+
+    @contextmanager
+    def span(self, name: str, **meta):
+        yield None
+
+    def flush(self):
+        pass
+
+
+class _LangfuseTracer:
+    enabled = True
+
+    def __init__(self):
+        from langfuse import Langfuse
+        self._lf = Langfuse()
+        self._trace = self._lf.trace(name="sembl-stack-loop")
+
+    @contextmanager
+    def span(self, name: str, **meta):
+        span = self._trace.span(name=name, metadata=meta or None)
+        try:
+            yield span
+        finally:
+            span.end()
+
+    def flush(self):
+        try:
+            self._lf.flush()
+        except Exception:
+            pass
+
+
+def get_tracer(langfuse: bool):
+    if not langfuse:
+        return _NoopTracer()
+    try:
+        return _LangfuseTracer()
+    except Exception:
+        return _NoopTracer()

sembl_stack/transport/mcp_client.py

@@ -0,0 +1,58 @@
+"""L0 protocol backbone: a tiny synchronous MCP stdio client.
+
+The platform's north star is "every layer speaks MCP." This helper spawns an MCP
+server over stdio, calls one tool, and returns the parsed JSON result — synchronously,
+so adapters don't have to be async.
+
+If the `mcp` SDK isn't installed, `available()` returns False and adapters fall back
+to their CLI path. That keeps the loop bootable with zero extra installs while MCP
+remains the default, dogfooded transport.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def available() -> bool:
+    try:
+        import mcp  # noqa: F401
+        return True
+    except Exception:
+        return False
+
+
+def call_tool(server_cmd: list[str], tool: str, arguments: dict) -> Any:
+    """Spawn `server_cmd` as a stdio MCP server, call `tool(arguments)`, return JSON.
+
+    Raises if the SDK is missing — callers should gate on `available()` first.
+    """
+    import anyio
+    from mcp import ClientSession, StdioServerParameters
+    from mcp.client.stdio import stdio_client
+
+    async def _run() -> Any:
+        params = StdioServerParameters(command=server_cmd[0], args=server_cmd[1:])
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                result = await session.call_tool(tool, arguments)
+                return _parse(result)
+
+    return anyio.run(_run)
+
+
+def _parse(result: Any) -> Any:
+    """Pull the JSON payload out of an MCP CallToolResult."""
+    content = getattr(result, "content", None) or []
+    for block in content:
+        text = getattr(block, "text", None)
+        if text:
+            try:
+                return json.loads(text)
+            except json.JSONDecodeError:
+                return {"text": text}
+    sc = getattr(result, "structuredContent", None)
+    if sc:
+        return sc
+    return {}

sembl_stack/tui.py

@@ -0,0 +1,86 @@
+"""O6 — the in-terminal run dashboard (CI-run-page UX), built on Textual.
+
+Optional by design: Textual is an extra (`pip install "sembl-stack[tui]"`). If it isn't
+installed, `available()` is False and the CLI prints an actionable hint instead of crashing —
+the same degrade-don't-fail stance as the LangGraph fallback. The data comes from the shared
+`views` layer, so the dashboard shows exactly what `sembl-stack runs` shows, live-refreshed.
+"""
+from __future__ import annotations
+
+from . import views
+
+try:
+    from textual.app import App, ComposeResult
+    from textual.containers import Horizontal
+    from textual.widgets import DataTable, Footer, Header, Static
+    _HAVE_TEXTUAL = True
+except ImportError:                      # textual not installed — degrade gracefully
+    _HAVE_TEXTUAL = False
+
+
+def available() -> bool:
+    return _HAVE_TEXTUAL
+
+
+def run_dashboard(store, refresh_s: float = 3.0) -> None:
+    """Launch the live dashboard. Caller must check `available()` first."""
+    if not _HAVE_TEXTUAL:
+        raise RuntimeError("textual not installed — `pip install \"sembl-stack[tui]\"`")
+    RunsDashboard(store, refresh_s).run()
+
+
+if _HAVE_TEXTUAL:
+
+    class RunsDashboard(App):
+        """A two-pane dashboard: a table of runs + the highlighted run's detail."""
+
+        TITLE = "sembl-stack — runs"
+        BINDINGS = [("q", "quit", "Quit"), ("r", "reload", "Reload")]
+        CSS = """
+        DataTable { width: 60%; }
+        #detail { width: 40%; padding: 0 1; border-left: solid $accent; }
+        """
+
+        def __init__(self, store, refresh_s: float = 3.0):
+            super().__init__()
+            self._store = store
+            self._refresh_s = refresh_s
+
+        def compose(self) -> "ComposeResult":
+            yield Header()
+            with Horizontal():
+                yield DataTable(id="runs", cursor_type="row")
+                yield Static("select a run", id="detail")
+            yield Footer()
+
+        def on_mount(self) -> None:
+            table = self.query_one("#runs", DataTable)
+            table.add_columns("run", "status", "att", "latency", "task")
+            self._reload()
+            if self._refresh_s:
+                self.set_interval(self._refresh_s, self._reload)
+
+        def action_reload(self) -> None:
+            self._reload()
+
+        def _reload(self) -> None:
+            table = self.query_one("#runs", DataTable)
+            keep = table.cursor_row
+            table.clear()
+            for r in views.list_rows(self._store):
+                task = (r["task"][:48] + "…") if len(r["task"]) > 49 else r["task"]
+                table.add_row(r["id"], r["status"], str(r["attempts"]),
+                              r["latency"], task, key=r["id"])
+            if table.row_count:
+                table.move_cursor(row=min(keep, table.row_count - 1))
+                self._show(table.coordinate_to_cell_key((table.cursor_row, 0)).row_key.value)
+
+        def on_data_table_row_highlighted(self, event) -> None:
+            self._show(event.row_key.value)
+
+        def _show(self, run_id) -> None:
+            if not run_id:
+                return
+            lines = views.detail_lines(self._store, run_id)
+            self.query_one("#detail", Static).update(
+                "\n".join(lines) if lines else "no detail")

sembl_stack/views.py

@@ -0,0 +1,74 @@
+"""Run-store presentation layer — pure functions shared by the CLI and the TUI (O6).
+
+Keeping the "what to show" logic here (no click, no textual) means the run list and the
+single-run detail render identically whether you type `sembl-stack runs` or watch the live
+dashboard, and the formatting is unit-testable without spinning up either UI.
+"""
+from __future__ import annotations
+
+
+def list_rows(store) -> list[dict]:
+    """One summary row per recorded run, newest first."""
+    rows = []
+    for rid in store.list_runs():
+        m = store.open(rid).manifest()
+        lat = m.get("total_latency_s")
+        rows.append({
+            "id": rid,
+            "status": m.get("status", "?"),
+            "attempts": m.get("attempts", "-"),
+            "latency": f"{lat:.2f}s" if isinstance(lat, (int, float)) else "-",
+            "task": (m.get("task", {}) or {}).get("text", ""),
+        })
+    return rows
+
+
+def detail_lines(store, run_id: str) -> list[str] | None:
+    """Plain-text detail for one run (task, bounds, per-attempt verdicts, final), or None."""
+    run = store.open(run_id)
+    m = run.manifest()
+    if not m:
+        return None
+    lat = m.get("total_latency_s")
+    lat_s = f"{lat:.2f}s" if isinstance(lat, (int, float)) else "-"
+    out = [
+        f"run {run_id}",
+        f"  status:  {m.get('status','?')}   attempts={m.get('attempts','-')}   "
+        f"engine={m.get('engine','-')}   latency={lat_s}",
+    ]
+    task = m.get("task", {}) or {}
+    if task:
+        out.append(f"  task:    {task.get('text','')}")
+        out.append(f"  repo:    {task.get('repo','')}")
+    bounds = run.get("bounds")
+    if bounds is not None:
+        out.append(f"  bounds:  editable={bounds.editable_paths}  "
+                   f"forbidden={bounds.forbidden_areas}  churn={bounds.churn_budget}")
+
+    log = {e.get("attempt"): e for e in m.get("attempts_log", [])}
+    n = m.get("attempts") or 0
+    if n:
+        out.append("  attempts:")
+    for i in range(1, n + 1):
+        v = run.get(f"verdict-{i}")
+        meta = log.get(i, {})
+        status = v.status if v else "?"
+        extra = f"  model={meta['model']}" if meta.get("model") else ""
+        out.append(f"    {i}: [{status}]  latency={meta.get('latency_s','-')}s{extra}")
+        out += [f"         - {r}" for r in (v.reasons if v else [])]
+
+    fv = run.get("verdict")
+    if fv is not None:
+        out.append(f"  final:   {fv.status}")
+    change = run.get("change")
+    if change is None and n:
+        change = run.get(f"change-{n}")
+    if change is not None:
+        files = (getattr(change, "report", {}) or {}).get("files_modified") or []
+        suffix = f"  files={files}" if files else ""
+        out.append(f"  patch:   change.json{suffix}")
+        if fv is not None and fv.status in ("PASS", "WARN"):
+            warn = " --allow-warn" if fv.status == "WARN" else ""
+            out.append(f"  apply:   sembl-stack apply {run_id} --repo {task.get('repo','.')}{warn}")
+    out.append(f"  artifacts: {run.dir}")
+    return out

sembl_stack/wizard.py

@@ -0,0 +1,233 @@
+"""Guided surface — the bare-`sembl-stack` Textual wizard (O6, elevates C4).
+
+Phase 0: a New/Existing choice, a stage rail (CI-run-page UX), and leave/continue-anywhere
+resume via the `session.json` pointer (see `session.py`).
+
+Phase 2: the stage rail actually RUNS the loop under the configured profile — press `r`
+and the real `loop.run` (plan -> execute -> verify, retry-on-BLOCK) executes in a worker
+thread against the repo's `task.yaml`, streaming per-stage status (pending/running/pass/
+fail) into the rail and showing the final verdict panel. The orchestration glue is
+`runner.py` (pure, headless); the wizard only renders its events — it adds NO core/gate
+logic, so a TUI run and a headless `sembl-stack loop` run are byte-identical.
+
+Deliberately NOT in Phase 2 (see docs/PROCESS-ACTION-PLAN.md §9 Track 2 item 5):
+  TODO(plan §9.5): CBM `index_repository` trigger on the Existing-repo path.
+  TODO(plan §9.5): reconcile (S9) advisory panel.
+  TODO(plan §9.5): live deploy/postdeploy panels + MurphyScan readiness screen.
+
+Textual is an extra (`pip install "sembl-stack[tui]"`); if it isn't installed,
+`available()` is False and the caller prints an actionable hint instead of crashing.
+"""
+from __future__ import annotations
+
+from . import runner
+from .session import STAGES, Session, resume_or_new, save
+
+try:
+    from textual.app import App, ComposeResult
+    from textual.containers import Horizontal, Vertical
+    from textual.widgets import Button, Footer, Header, Static
+    _HAVE_TEXTUAL = True
+except ImportError:                      # textual not installed — degrade gracefully
+    _HAVE_TEXTUAL = False
+
+
+def available() -> bool:
+    return _HAVE_TEXTUAL
+
+
+def launch(repo: str = ".") -> None:
+    """Launch the guided wizard. Caller must check `available()` first."""
+    if not _HAVE_TEXTUAL:
+        raise RuntimeError("textual not installed — `pip install \"sembl-stack[tui]\"`")
+    StackWizard(repo=repo).run()
+
+
+# Live-run stage marks (Phase 2), layered over the session marks (Phase 0).
+_LIVE_MARK = {"running": "~", "done": "x", "fail": "!"}
+
+
+def _rail_text(s: Session, live: dict | None = None) -> str:
+    """The stage rail as plain text: [x] done, [>] current, [ ] pending;
+    live-run states win: [~] running, [!] failed."""
+    live = live or {}
+    lines = [f"repo: {s.repo}", f"mode: {s.mode}", ""]
+    for stage in STAGES:
+        if stage in live:
+            mark = _LIVE_MARK.get(live[stage]["state"], "?")
+            detail = live[stage].get("detail", "")
+            suffix = f"  ({detail})" if detail else ""
+        else:
+            mark = "x" if stage in s.completed else (">" if stage == s.current_stage else " ")
+            suffix = ""
+        lines.append(f"  [{mark}] {stage}{suffix}")
+    if s.done:
+        lines.append("\n  all stages complete.")
+    return "\n".join(lines)
+
+
+def _verdict_text(result) -> str:
+    """The final-verdict panel line(s) for a finished live run."""
+    v = result.verdict
+    lines = [f"FINAL: {v.status}  (after {result.attempts} attempt(s))"]
+    for r in getattr(v, "reasons", []) or []:
+        lines.append(f"  - {r}")
+    if result.run_id:
+        lines.append(f"run: {result.run_id}  (.sembl/runs/{result.run_id}/)")
+    return "\n".join(lines)
+
+
+if _HAVE_TEXTUAL:
+
+    class StackWizard(App):
+        """Bare-`sembl-stack` guided wizard: New/Existing + stage rail + session resume
+        + Phase-2 live run (`r` runs task.yaml through the real loop)."""
+
+        TITLE = "sembl-stack"
+        SUB_TITLE = "guided run"
+        BINDINGS = [
+            ("q", "quit", "Quit"),
+            ("n", "mode_new", "New repo"),
+            ("e", "mode_existing", "Existing repo"),
+            ("space", "advance", "Advance stage"),
+            ("r", "run_loop", "Run task.yaml"),
+        ]
+        CSS = """
+        #mode { width: 30%; padding: 1; border-right: solid $accent; }
+        #right { width: 70%; }
+        #rail { padding: 1; height: auto; }
+        #verdict { padding: 1; height: auto; color: $text-muted; }
+        Button { width: 100%; margin: 0 0 1 0; }
+        """
+
+        def __init__(self, repo: str = ".", session: "Session | None" = None):
+            super().__init__()
+            self._session = session or resume_or_new(repo)
+            self._live: dict = {}          # stage -> {"state", "detail"} during a live run
+            self._loop_running = False
+
+        def compose(self) -> "ComposeResult":
+            yield Header()
+            with Horizontal():
+                with Vertical(id="mode"):
+                    yield Static("New or existing?", id="mode-label")
+                    yield Button("New repo", id="mode-new", variant="primary")
+                    yield Button("Existing repo", id="mode-existing")
+                with Vertical(id="right"):
+                    yield Static(_rail_text(self._session), id="rail")
+                    yield Static("", id="verdict")
+            yield Footer()
+
+        # -- actions ------------------------------------------------------------
+        def _set_mode(self, mode: str) -> None:
+            self._session.mode = mode
+            save(self._session)
+            self._refresh()
+
+        def action_mode_new(self) -> None:
+            self._set_mode("new")
+
+        def action_mode_existing(self) -> None:
+            self._set_mode("existing")
+
+        def action_advance(self) -> None:
+            self._session.advance()
+            save(self._session)
+            self._refresh()
+
+        def on_button_pressed(self, event) -> None:
+            if event.button.id == "mode-new":
+                self._set_mode("new")
+            elif event.button.id == "mode-existing":
+                self._set_mode("existing")
+
+        # -- Phase 2: run the real loop under the profile ------------------------
+        def action_run_loop(self) -> None:
+            if self._loop_running:
+                self._note("a run is already in progress…")
+                return
+            task = runner.load_task(self._session.repo)
+            if task is None:
+                self._note(f"no task.yaml in {self._session.repo} — "
+                           "`sembl-stack init` scaffolds one.")
+                return
+            cfg = runner.resolve_config(self._session.repo)
+            self._loop_running = True
+            self._live = {}
+            self._note("running…  (plan -> execute -> verify)")
+            self._refresh()
+            self.run_worker(self._run_loop_async(cfg, task), exclusive=True)
+
+        async def _run_loop_async(self, cfg, task) -> None:
+            """Run the blocking loop in an executor; drain stage events on the app's
+            own event loop via a thread-safe queue.
+
+            The loop's stage functions call `emit` from the executor thread, so `emit`
+            only enqueues (thread-safe, non-blocking) — every UI mutation happens here,
+            on the app thread. This deliberately avoids `call_from_thread`, whose
+            blocking round-trip deadlocks a threaded worker under Textual's `run_test`
+            harness (the pilot drives the loop, so the worker's blocked wait never
+            resolves)."""
+            import asyncio
+            import queue as _queue
+
+            events: "_queue.Queue" = _queue.Queue()
+
+            def emit(ev) -> None:
+                events.put(("event", ev))
+
+            def blocking() -> None:
+                try:
+                    events.put(("done", runner.run_stages(cfg, task, emit)))
+                except Exception as exc:          # loop crash (plan/verify raised)
+                    events.put(("crash", exc))
+
+            loop = asyncio.get_running_loop()
+            fut = loop.run_in_executor(None, blocking)
+            terminal = None
+            while terminal is None:
+                try:
+                    kind, payload = events.get_nowait()
+                except _queue.Empty:
+                    await asyncio.sleep(0.02)
+                    continue
+                if kind == "event":
+                    self._on_stage_event(payload)
+                else:
+                    terminal = (kind, payload)
+            await fut                             # surface any executor teardown error
+            if terminal[0] == "done":
+                self._on_run_done(terminal[1])
+            else:
+                self._on_run_crashed(terminal[1])
+
+        def _on_stage_event(self, ev) -> None:
+            self._live[ev.stage] = {"state": ev.state, "detail": ev.detail}
+            self._refresh()
+
+        def _on_run_done(self, result) -> None:
+            self._loop_running = False
+            if result.verdict.status in ("PASS", "WARN"):
+                # The loop-backed stages are genuinely complete — record the resume
+                # pointer just past them (leave/continue-anywhere, Phase 0 semantics).
+                for stage in ("bounds", "loop", "verify"):
+                    if stage not in self._session.completed:
+                        self._session.completed.append(stage)
+                self._session.current_stage = "merge"
+                self._session.run_id = result.run_id
+                save(self._session)
+            self._note(_verdict_text(result))
+            self._refresh()
+
+        def _on_run_crashed(self, exc: Exception) -> None:
+            self._loop_running = False
+            self._note(f"run crashed: {exc!r}")
+            self._refresh()
+
+        # -- rendering ------------------------------------------------------------
+        def _note(self, text: str) -> None:
+            self.query_one("#verdict", Static).update(text)
+
+        def _refresh(self) -> None:
+            self.query_one("#rail", Static).update(
+                _rail_text(self._session, self._live))

sembl_stack-0.1.0.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: sembl-stack
+Version: 0.1.0
+Summary: A swappable, spec-driven software factory: task to bounds, an agent writes in a sandbox, the Sembl gate judges the diff, PASS merges, deploys, and a post-deploy gate confirms or rolls back. Every stage an adapter behind one typed contract.
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: langgraph>=0.2
+Requires-Dist: mcp>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: sembl>=0.1.20
+Provides-Extra: all
+Requires-Dist: langfuse>=2.0; extra == 'all'
+Requires-Dist: langgraph>=0.2; extra == 'all'
+Requires-Dist: mcp>=1.0; extra == 'all'
+Requires-Dist: sembl>=0.1.20; extra == 'all'
+Requires-Dist: textual>=0.50; extra == 'all'
+Provides-Extra: gate
+Requires-Dist: sembl>=0.1.20; extra == 'gate'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: orchestrate
+Requires-Dist: langgraph>=0.2; extra == 'orchestrate'
+Provides-Extra: trace
+Requires-Dist: langfuse>=2.0; extra == 'trace'
+Provides-Extra: tui
+Requires-Dist: textual>=0.50; extra == 'tui'
+Description-Content-Type: text/markdown
+
+# sembl-stack
+
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Built around Sembl](https://img.shields.io/badge/gate-Sembl-ccff00.svg)](https://github.com/speedvibecode/sembl)
+
+**A swappable, spec-driven software factory.** A task becomes declared bounds, an
+agent writes the change inside a disposable sandbox, the **[Sembl](https://github.com/speedvibecode/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](https://sembl-stack.vercel.app) · [The gate (Sembl)](https://sembl.vercel.app) · [Architecture & plan](docs/PROCESS-ACTION-PLAN.md)
+
+```text
+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
+
+```bash
+pip install sembl-stack sembl     # the stack + the gate it runs at its core
+sembl-stack init                  # scaffold sembl.stack.yaml + task.yaml from a preset
+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 …`):
+
+| Preset | What runs | Needs |
+|--------|-----------|-------|
+| `just-gate` | gate any diff, nothing else | only `sembl` |
+| `gate+sandbox` | the whole loop with a mock executor | no API keys |
+| `full-loop` | real agent + sandbox + gate | an executor key |
+
+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.
+
+| Stage | Does | Artifact flow | Who owns it |
+|-------|------|---------------|-------------|
+| **L0** Protocol & hub | one wire between stages | — | **we own** (the contract) |
+| **L1** Repo intel | code-graph context | `Task → Context` | adapter |
+| **L2** Spec → bounds | scope the change | `Task → Bounds` | **we own** (`sembl`) |
+| **L3** Execute | write the change | `Task + Bounds → Change` | adapter (claude / aider / opencode) |
+| **L4** Sandbox | contain a bad diff | `Change → Change` | adapter (disposable clone) |
+| **L5** Verify | gate the diff | `Change + Bounds → Verdict` | **the gate** (`sembl`) |
+| **L5.5** Review (advisory) | code-quality signal | `diff → findings` | adapter (`llm` — BYO agent-CLI reviewer; CodeRabbit optional) |
+| **L6** Orchestrate | loop, retry, trace | wiring + `* → Trace` | **we own** (LangGraph) |
+| **L6.5** Merge | gated merge | `Verdict(PASS) → MergeRecord` | **we own** |
+| **L7** Deploy | ship | `Verdict(PASS) → Delivery` | adapter |
+| **L8** Verify-in-prod | gate production | `Delivery → Verdict` | **the gate** (health + rollback) |
+
+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>/`:
+
+```text
+.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 (optional)
+
+`pip install "sembl-stack[tui]"` adds a Textual wizard. Run bare `sembl-stack` and
+press `r`: the stage rail runs the real loop under your configured profile,
+streaming per-stage status (pending/running/pass/fail) live and showing the final
+verdict — byte-identical to a headless `sembl-stack loop`, because it drives the
+same adapters.
+
+## The full picture
+
+**→ [`docs/PROCESS-ACTION-PLAN.md`](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`](docs/process-self-improvement.md)
+(north-star theory) · [`eval-metric-O3.md`](docs/eval-metric-O3.md) (the metric) ·
+[`memory-plane-hypothesis.md`](docs/memory-plane-hypothesis.md).
+
+## Local development
+
+```bash
+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.**