sembl-stack 0.1.1__tar.gz → 0.2.0__tar.gz

{sembl_stack-0.1.1 → sembl_stack-0.2.0}/.gitignore

@@ -1,16 +1,16 @@
-# Example target repos are git-inited locally for demos; don't nest their .git
-examples/**/repo/.git/
-# Local-only tests (kept off the repo by request)
-tests/local/
-# Run artifacts (the run store) are local-only
-.sembl/
-examples/**/repo/.sembl/
-__pycache__/
-*.egg-info/
-.pytest_cache/
-.test-tmp/
-build/
-dist/
-.venv/
+# Example target repos are git-inited locally for demos; don't nest their .git
+examples/**/repo/.git/
+# Local-only tests (kept off the repo by request)
+tests/local/
+# Run artifacts (the run store) are local-only
+.sembl/
+examples/**/repo/.sembl/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.test-tmp/
+build/
+dist/
+.venv/
 eval/.checkpoint-*.json
 eval/.result-*

{sembl_stack-0.1.1 → sembl_stack-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sembl-stack
-Version: 0.1.1
+Version: 0.2.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
@@ -9,6 +9,7 @@ Requires-Dist: click>=8.1
 Requires-Dist: langgraph>=0.2
 Requires-Dist: mcp>=1.0
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.0
 Requires-Dist: sembl>=0.1.20
 Provides-Extra: all
 Requires-Dist: langfuse>=2.0; extra == 'all'
@@ -57,8 +58,30 @@ task ─▶ bounds ─▶ execute ─▶ sandbox ─▶ SEMBL GATE ─▶ merge
 ## 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
+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):
+
+```bash
+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
@@ -127,13 +150,12 @@ Every run leaves a complete paper trail in `.sembl/runs/<id>/`:
 └─ trace.json         # the timeline
 ```
 
-## The guided TUI (optional)
+## The guided TUI
 
-`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 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
 

{sembl_stack-0.1.1 → sembl_stack-0.2.0}/README.md

@@ -27,8 +27,30 @@ task ─▶ bounds ─▶ execute ─▶ sandbox ─▶ SEMBL GATE ─▶ merge
 ## 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
+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):
+
+```bash
+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
@@ -97,13 +119,12 @@ Every run leaves a complete paper trail in `.sembl/runs/<id>/`:
 └─ trace.json         # the timeline
 ```
 
-## The guided TUI (optional)
+## The guided TUI
 
-`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 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
 

{sembl_stack-0.1.1 → sembl_stack-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sembl-stack"
-version = "0.1.1"
+version = "0.2.0"
 description = "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."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -17,6 +17,9 @@ dependencies = [
                       # default install runs it, not the built-in fallback runner.
   "sembl>=0.1.20",    # L5 gate + L2 spec engine. Core because the DEFAULT config gates
   "mcp>=1.0",         # with sembl over MCP — a bare install must run the default stack.
+  "questionary>=2.0", # the guided run IS the product surface: bare `sembl-stack` must
+                      # always launch the inline step-by-step guide (owner UX decision
+                      # 2026-07-04: Claude Code-style inline prompts, NOT a full-screen app).
 ]
 
 [project.optional-dependencies]
@@ -34,3 +37,17 @@ sembl-stack = "sembl_stack.cli:main"
 
 [tool.hatch.build.targets.wheel]
 packages = ["sembl_stack"]
+
+[tool.hatch.build.targets.sdist]
+# Explicit allowlist, not "everything minus .gitignore": hatchling's default sdist
+# packed the whole working tree, including examples/flagship-feedback-board's
+# node_modules/.next build output/.vercel/.env.local (a real Next.js app checked out
+# for local dev, not part of this package) — a 61MB sdist. Only what installs/builds
+# the CLI belongs here.
+include = [
+  "/sembl_stack",
+  "/tests",
+  "/README.md",
+  "/LICENSE",
+  "/SECURITY.md",
+]

{sembl_stack-0.1.1 → sembl_stack-0.2.0}/sembl_stack/__init__.py

@@ -1,3 +1,3 @@
 """sembl-stack — an open, swappable spec-driven coding factory."""
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"

{sembl_stack-0.1.1 → sembl_stack-0.2.0}/sembl_stack/adapters/_redact.py

@@ -1,19 +1,19 @@
-"""Redaction helper for adapter artifacts.
-
-Third-party process output (HTTP health bodies, CLI stdout/stderr, reviewer output) can carry
-debug pages, stack traces, env-shaped values, diff snippets, or auth errors. Persisting it raw
-into `.sembl/runs/<id>/` would violate the no-secrets-in-artifacts invariant. We keep only a
-non-reversible fingerprint: byte count + sha256. That preserves "output existed / did it change"
-signal without ever serializing the content.
-"""
-from __future__ import annotations
-
-import hashlib
-
-
-def summarize(text) -> dict:
-    """Reduce arbitrary third-party text to {bytes, sha256} — never the content itself."""
-    if text is None:
-        return {"bytes": 0, "sha256": None}
-    raw = text if isinstance(text, bytes) else str(text).encode("utf-8", "replace")
-    return {"bytes": len(raw), "sha256": hashlib.sha256(raw).hexdigest()}
+"""Redaction helper for adapter artifacts.
+
+Third-party process output (HTTP health bodies, CLI stdout/stderr, reviewer output) can carry
+debug pages, stack traces, env-shaped values, diff snippets, or auth errors. Persisting it raw
+into `.sembl/runs/<id>/` would violate the no-secrets-in-artifacts invariant. We keep only a
+non-reversible fingerprint: byte count + sha256. That preserves "output existed / did it change"
+signal without ever serializing the content.
+"""
+from __future__ import annotations
+
+import hashlib
+
+
+def summarize(text) -> dict:
+    """Reduce arbitrary third-party text to {bytes, sha256} — never the content itself."""
+    if text is None:
+        return {"bytes": 0, "sha256": None}
+    raw = text if isinstance(text, bytes) else str(text).encode("utf-8", "replace")
+    return {"bytes": len(raw), "sha256": hashlib.sha256(raw).hexdigest()}

{sembl_stack-0.1.1 → sembl_stack-0.2.0}/sembl_stack/adapters/base.py

@@ -1,179 +1,185 @@
-"""The platform contract.
-
-The data types are the canonical artifacts (see `sembl_stack/artifacts.py`); the
-Protocols below are what an adapter must satisfy to be swappable into a layer. Re-exported
-here so adapters import everything they need from one place.
-"""
-from __future__ import annotations
-
-import os
-import re
-import subprocess
-from typing import Protocol, runtime_checkable
-
-from ..artifacts import (  # noqa: F401  (re-exported for adapters)
-    Bounds,
-    Change,
-    Context,
-    Delivery,
-    ExecutionResult,
-    MergeRecord,
-    ReconciliationReport,
-    ReviewReport,
-    SpecGraph,
-    Task,
-    Trace,
-    Verdict,
-)
-
-
-# --- Shared adapter helpers ---------------------------------------------------
-
-def changed_files_from_diff(diff: str) -> list[str]:
-    """Files touched by a unified git diff, order-preserved and de-duplicated.
-
-    Reads BOTH the `diff --git a/… b/…` headers and the `+++ b/…` markers, unioned:
-      * the `diff --git` header names a file even when it has no `+++` hunk — e.g. an
-        EMPTY new file an errored agent created. A `+++`-only parser silently drops it,
-        and the gate then flags a spurious "unreported change";
-      * the `+++ b/` marker is the fallback for a diff fragment that arrives without a
-        full header.
-    `/dev/null` (the add/delete sentinel) is skipped. Every executor adapter uses this
-    one parser so Claude/OpenCode/Aider report changed files consistently.
-    """
-    seen: set[str] = set()
-    out: list[str] = []
-
-    def add(path: str) -> None:
-        path = path.strip()
-        if path and path != "/dev/null" and path not in seen:
-            seen.add(path)
-            out.append(path)
-
-    for line in diff.splitlines():
-        if line.startswith("diff --git "):
-            _, _, tail = line.partition(" b/")
-            if tail:
-                add(tail)
-        elif line.startswith("+++ "):
-            marker = line[4:]
-            if marker.startswith("b/"):
-                marker = marker[2:]
-            add(marker.split("\t", 1)[0])     # drop a trailing tab-timestamp if present
-    return out
-
-
-# Env-var names whose values are credentials; a secret only ever lives in the
-# environment, so an executor CLI echoing one (e.g. in an auth error) is the one
-# path it could reach a persisted run artifact. Scrubbed by value below.
-_SECRET_ENV_NAME = re.compile(r"(API_KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL)S?$", re.IGNORECASE)
-# Generic provider-key shapes (sk-ant-…, sk-proj-…, sk-or-v1-…) as a second net.
-_SECRET_TOKEN = re.compile(r"sk-[A-Za-z0-9_\-]{8,}")
-
-
-def scrub_secrets(text: str) -> str:
-    """Redact anything secret-shaped before it reaches a run artifact.
-
-    Executor stdout/stderr is persisted into `.sembl/runs/<id>/change.json` for
-    debuggability; the security invariant (no key value ever stored) must hold even
-    when a CLI misbehaves and echoes a credential. Env values are compared in memory
-    only — nothing read here is ever written anywhere except as its redaction marker.
-    """
-    if not text:
-        return text
-    for name, value in os.environ.items():
-        if len(value) >= 8 and _SECRET_ENV_NAME.search(name):
-            text = text.replace(value, f"[redacted:{name}]")
-    return _SECRET_TOKEN.sub("[redacted:key]", text)
-
-
-def run_executor(cmd: list[str], cwd: str, timeout: int, **run_kwargs):
-    """Run an executor subprocess, turning a timeout into a structured signal.
-
-    Returns ``(returncode, stdout, stderr, timed_out)``. A `subprocess.TimeoutExpired`
-    is caught here (its partial stdout/stderr preserved) instead of being allowed to
-    propagate and abort the whole loop — the caller records `timed_out` in the report so
-    the gate stage can convert it to a BLOCK rather than a crash.
-    """
-    try:
-        # encoding/errors explicit: agents emit UTF-8 (box-drawing, emoji, ✓). The default
-        # text=True decodes with the locale codec (cp1252 on Windows), which crashes the
-        # stdout reader thread mid-run and silently loses the output. Decode as UTF-8 and
-        # replace undecodable bytes so capture never aborts the loop.
-        proc = subprocess.run(
-            cmd, cwd=cwd, capture_output=True, text=True, timeout=timeout,
-            encoding="utf-8", errors="replace", **run_kwargs)
-        return proc.returncode, proc.stdout or "", proc.stderr or "", False
-    except subprocess.TimeoutExpired as exc:
-        out, err = exc.stdout or "", exc.stderr or ""
-        if isinstance(out, bytes):
-            out = out.decode("utf-8", "replace")
-        if isinstance(err, bytes):
-            err = err.decode("utf-8", "replace")
-        return -1, out, err, True
-
-
-# --- Layer interfaces (Protocols) ---------------------------------------------
-
-class Sandbox(Protocol):              # an open sandbox handle (from L4)
-    workdir: str
-    def diff(self) -> str: ...
-    def close(self) -> None: ...
-
-
-@runtime_checkable
-class SpecAdapter(Protocol):         # L2: Task -> Bounds
-    def plan(self, task: Task) -> Bounds: ...
-
-
-@runtime_checkable
-class SandboxAdapter(Protocol):      # L4: Change -> Change (contained)
-    def open(self, repo: str) -> Sandbox: ...
-
-
-@runtime_checkable
-class ExecuteAdapter(Protocol):      # L3: Task+Bounds(+Context) -> Change
-    def run(self, task: Task, bounds: Bounds, sandbox: Sandbox,
-            feedback: str | None) -> ExecutionResult: ...
-
-
-@runtime_checkable
-class VerifyAdapter(Protocol):       # L5: Change+Bounds -> Verdict
-    def verify(self, bounds: Bounds, result: ExecutionResult,
-               strict: bool) -> Verdict: ...
-
-
-@runtime_checkable
-class ReconcileAdapter(Protocol):    # L5.5: SpecGraph+CodeGraph -> report
-    def reconcile(self, spec_graph: SpecGraph, code_graph: dict) -> ReconciliationReport:
-        ...
-
-
-@runtime_checkable
-class MergeAdapter(Protocol):        # L6.5: Verdict(PASS) -> MergeRecord
-    def merge(self, repo: str, *, into: str = "main", source: str = "HEAD",
-              no_ff: bool = True, message: str | None = None) -> MergeRecord:
-        ...
-
-
-@runtime_checkable
-class DeployAdapter(Protocol):       # L7: Verdict(PASS) -> Delivery; rollback reverts it
-    def deploy(self, repo: str, *, production: bool = False,
-               prebuilt: bool = False) -> Delivery:
-        ...
-
-    def rollback(self, repo: str, *, to: str | None = None) -> Delivery:
-        ...
-
-
-@runtime_checkable
-class PostDeployAdapter(Protocol):   # L8: Delivery -> Verdict
-    def verify(self, delivery: Delivery, *, health_path: str = "/",
-               timeout_s: float = 10.0) -> Verdict:
-        ...
-
-
-@runtime_checkable
-class ReviewAdapter(Protocol):       # L5.5 quality: a diff -> ReviewReport (advisory)
-    def review(self, diff: str, *, reviewer_hint: str = "") -> ReviewReport:
-        ...
+"""The platform contract.
+
+The data types are the canonical artifacts (see `sembl_stack/artifacts.py`); the
+Protocols below are what an adapter must satisfy to be swappable into a layer. Re-exported
+here so adapters import everything they need from one place.
+"""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from typing import Protocol, runtime_checkable
+
+from ..artifacts import (  # noqa: F401  (re-exported for adapters)
+    Bounds,
+    Change,
+    Context,
+    Delivery,
+    ExecutionResult,
+    MergeRecord,
+    ReconciliationReport,
+    ReviewReport,
+    SpecGraph,
+    Task,
+    Trace,
+    Verdict,
+)
+
+
+# --- Shared adapter helpers ---------------------------------------------------
+
+def changed_files_from_diff(diff: str) -> list[str]:
+    """Files touched by a unified git diff, order-preserved and de-duplicated.
+
+    Reads BOTH the `diff --git a/… b/…` headers and the `+++ b/…` markers, unioned:
+      * the `diff --git` header names a file even when it has no `+++` hunk — e.g. an
+        EMPTY new file an errored agent created. A `+++`-only parser silently drops it,
+        and the gate then flags a spurious "unreported change";
+      * the `+++ b/` marker is the fallback for a diff fragment that arrives without a
+        full header.
+    `/dev/null` (the add/delete sentinel) is skipped. Every executor adapter uses this
+    one parser so Claude/OpenCode/Aider report changed files consistently.
+    """
+    seen: set[str] = set()
+    out: list[str] = []
+
+    def add(path: str) -> None:
+        path = path.strip()
+        if path and path != "/dev/null" and path not in seen:
+            seen.add(path)
+            out.append(path)
+
+    for line in diff.splitlines():
+        if line.startswith("diff --git "):
+            _, _, tail = line.partition(" b/")
+            if tail:
+                add(tail)
+        elif line.startswith("+++ "):
+            marker = line[4:]
+            if marker.startswith("b/"):
+                marker = marker[2:]
+            add(marker.split("\t", 1)[0])     # drop a trailing tab-timestamp if present
+    return out
+
+
+# Env-var names whose values are credentials; a secret only ever lives in the
+# environment, so an executor CLI echoing one (e.g. in an auth error) is the one
+# path it could reach a persisted run artifact. Scrubbed by value below.
+_SECRET_ENV_NAME = re.compile(r"(API_KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL)S?$", re.IGNORECASE)
+# Generic provider-key shapes (sk-ant-…, sk-proj-…, sk-or-v1-…) as a second net.
+_SECRET_TOKEN = re.compile(r"sk-[A-Za-z0-9_\-]{8,}")
+
+
+def scrub_secrets(text: str) -> str:
+    """Redact anything secret-shaped before it reaches a run artifact.
+
+    Executor stdout/stderr is persisted into `.sembl/runs/<id>/change.json` for
+    debuggability; the security invariant (no key value ever stored) must hold even
+    when a CLI misbehaves and echoes a credential. Env values are compared in memory
+    only — nothing read here is ever written anywhere except as its redaction marker.
+    """
+    if not text:
+        return text
+    for name, value in os.environ.items():
+        if len(value) >= 8 and _SECRET_ENV_NAME.search(name):
+            text = text.replace(value, f"[redacted:{name}]")
+    return _SECRET_TOKEN.sub("[redacted:key]", text)
+
+
+def run_executor(cmd: list[str], cwd: str, timeout: int, **run_kwargs):
+    """Run an executor subprocess, turning a timeout into a structured signal.
+
+    Returns ``(returncode, stdout, stderr, timed_out)``. A `subprocess.TimeoutExpired`
+    is caught here (its partial stdout/stderr preserved) instead of being allowed to
+    propagate and abort the whole loop — the caller records `timed_out` in the report so
+    the gate stage can convert it to a BLOCK rather than a crash.
+
+    stdin is DEVNULL by default: a headless factory executor must never be able to sit
+    waiting on interactive input (e.g. a CLI's first-run provider setup) — that hangs
+    silently, since its stdout/stderr are captured into pipes the user can't see. Cut
+    off, the CLI hits EOF immediately and fails fast with a visible error instead.
+    """
+    run_kwargs.setdefault("stdin", subprocess.DEVNULL)
+    try:
+        # encoding/errors explicit: agents emit UTF-8 (box-drawing, emoji, ✓). The default
+        # text=True decodes with the locale codec (cp1252 on Windows), which crashes the
+        # stdout reader thread mid-run and silently loses the output. Decode as UTF-8 and
+        # replace undecodable bytes so capture never aborts the loop.
+        proc = subprocess.run(
+            cmd, cwd=cwd, capture_output=True, text=True, timeout=timeout,
+            encoding="utf-8", errors="replace", **run_kwargs)
+        return proc.returncode, proc.stdout or "", proc.stderr or "", False
+    except subprocess.TimeoutExpired as exc:
+        out, err = exc.stdout or "", exc.stderr or ""
+        if isinstance(out, bytes):
+            out = out.decode("utf-8", "replace")
+        if isinstance(err, bytes):
+            err = err.decode("utf-8", "replace")
+        return -1, out, err, True
+
+
+# --- Layer interfaces (Protocols) ---------------------------------------------
+
+class Sandbox(Protocol):              # an open sandbox handle (from L4)
+    workdir: str
+    def diff(self) -> str: ...
+    def close(self) -> None: ...
+
+
+@runtime_checkable
+class SpecAdapter(Protocol):         # L2: Task -> Bounds
+    def plan(self, task: Task) -> Bounds: ...
+
+
+@runtime_checkable
+class SandboxAdapter(Protocol):      # L4: Change -> Change (contained)
+    def open(self, repo: str) -> Sandbox: ...
+
+
+@runtime_checkable
+class ExecuteAdapter(Protocol):      # L3: Task+Bounds(+Context) -> Change
+    def run(self, task: Task, bounds: Bounds, sandbox: Sandbox,
+            feedback: str | None) -> ExecutionResult: ...
+
+
+@runtime_checkable
+class VerifyAdapter(Protocol):       # L5: Change+Bounds -> Verdict
+    def verify(self, bounds: Bounds, result: ExecutionResult,
+               strict: bool) -> Verdict: ...
+
+
+@runtime_checkable
+class ReconcileAdapter(Protocol):    # L5.5: SpecGraph+CodeGraph -> report
+    def reconcile(self, spec_graph: SpecGraph, code_graph: dict) -> ReconciliationReport:
+        ...
+
+
+@runtime_checkable
+class MergeAdapter(Protocol):        # L6.5: Verdict(PASS) -> MergeRecord
+    def merge(self, repo: str, *, into: str = "main", source: str = "HEAD",
+              no_ff: bool = True, message: str | None = None) -> MergeRecord:
+        ...
+
+
+@runtime_checkable
+class DeployAdapter(Protocol):       # L7: Verdict(PASS) -> Delivery; rollback reverts it
+    def deploy(self, repo: str, *, production: bool = False,
+               prebuilt: bool = False) -> Delivery:
+        ...
+
+    def rollback(self, repo: str, *, to: str | None = None) -> Delivery:
+        ...
+
+
+@runtime_checkable
+class PostDeployAdapter(Protocol):   # L8: Delivery -> Verdict
+    def verify(self, delivery: Delivery, *, health_path: str = "/",
+               timeout_s: float = 10.0) -> Verdict:
+        ...
+
+
+@runtime_checkable
+class ReviewAdapter(Protocol):       # L5.5 quality: a diff -> ReviewReport (advisory)
+    def review(self, diff: str, *, reviewer_hint: str = "") -> ReviewReport:
+        ...