leanlab 0.2.1__py3-none-any.whl

leanlab/core/coding/engineer.py

@@ -0,0 +1,304 @@
+"""The engineer loop — implement a spec'd task to a green gate + reviewer sign-off, then merge.
+
+Realizes the build-task use case. The engineer edits the worktree; the gate checks it; on a
+green gate the reviewer judges the diff. It loops on gate failures / review feedback, then
+commits and merges the branch into main. `runner` / `ui` are injected for testing.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import shlex
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ..loop import make_runner
+from .board import log_event
+from .gate import run_gate
+from .personas import spec_text
+from .playbook import read_playbook, update_playbook
+
+_APPROVED = (True, "true", "yes", "True")
+
+
+def _git(repo, *args):
+    return subprocess.run(["git", "-C", str(repo), *args], capture_output=True, text=True)
+
+
+def _record(repo, rec):
+    """Append a build outcome so `leanlab board` can show it."""
+    p = Path(repo) / ".leanlab" / "coding-results.jsonl"
+    p.parent.mkdir(parents=True, exist_ok=True)
+    rec = {**rec, "ts": datetime.now(timezone.utc).isoformat()}
+    with p.open("a") as f:
+        f.write(json.dumps(rec) + "\n")
+
+
+def _load_lock(repo, slug):
+    """Load the out-of-tree lock (pristine acceptance tests). None if the task wasn't spec'd."""
+    p = Path(repo) / ".leanlab" / "locks" / f"{slug}.json"
+    if not p.exists():
+        return None
+    try:
+        return json.loads(p.read_text())
+    except (OSError, ValueError):
+        return None
+
+
+def _is_pristine(lock, wt) -> bool:
+    """Did the engineer leave the locked tests untouched? (missing or changed = tampered)"""
+    for it in lock.get("tests", []):
+        p = Path(wt) / it["path"]
+        if not p.exists() or hashlib.sha256(p.read_bytes()).hexdigest() != it["sha256"]:
+            return False
+    return True
+
+
+def _isolated_acceptance(wt, lock, accept_cmd):
+    """Re-run the pristine acceptance tests with engineer conftest/fixtures DISABLED.
+
+    If they passed the normal gate but fail here (exit 1), the pass relied on engineer-added
+    test infrastructure (a conftest monkeypatch, a fixture) — i.e. gaming. Any other exit
+    (can't collect / import) means we couldn't isolate cleanly, so we don't block on it.
+    """
+    paths = [it["path"] for it in lock.get("tests", [])]
+    if not paths:
+        return True, ""
+    try:
+        proc = subprocess.run(shlex.split(accept_cmd) + paths, cwd=Path(wt),
+                              capture_output=True, text=True, timeout=600)
+    except Exception as e:  # noqa: BLE001
+        return True, f"(isolation skipped: {e})"
+    out = (proc.stdout + ("\n" + proc.stderr if proc.stderr else "")).strip()
+    return (proc.returncode != 1), out
+
+
+def _restore_tests(lock, wt) -> None:
+    """Overwrite the worktree's acceptance tests with the pristine, out-of-tree copies, so the
+    gate always runs the ORIGINAL tests no matter what the engineer did to them."""
+    for it in lock.get("tests", []):
+        p = Path(wt) / it["path"]
+        p.parent.mkdir(parents=True, exist_ok=True)
+        if p.exists():
+            p.chmod(0o644)
+        p.write_text(it["content"])
+        p.chmod(0o444)
+
+
+def _stage(wt):
+    """Stage all changes except gate caches and the lock file."""
+    ep = _git(wt, "rev-parse", "--git-path", "info/exclude").stdout.strip()
+    epath = Path(ep) if Path(ep).is_absolute() else Path(wt) / ep
+    try:
+        epath.parent.mkdir(parents=True, exist_ok=True)
+        cur = epath.read_text() if epath.exists() else ""
+        for pat in ("__pycache__/", ".pytest_cache/", ".leanlab-lock.json"):
+            if pat not in cur:
+                cur += pat + "\n"
+        epath.write_text(cur)
+    except Exception:  # noqa: BLE001
+        pass
+    _git(wt, "add", "-A")
+
+
+def _engineer_prompt(spec_md, persona_set, feedback, playbook=""):
+    base = spec_text("engineer", persona_set) + "\n\n## The task spec\n" + spec_md + "\n\n"
+    if playbook:
+        base += "## Project playbook (follow it)\n" + playbook + "\n\n"
+    base += (
+        "Implement the change in this worktree so the gate passes. Read the locked acceptance "
+        "tests under the test directory and make them pass — do NOT modify them. Follow the "
+        "repository's conventions. Edit files with your tools, then stop."
+    )
+    if feedback:
+        base += "\n\n## Fix this (from the last attempt)\n" + feedback
+    return base
+
+
+_DIFF_LIMIT = 40000
+
+# Each panel reviewer attacks from a distinct angle — diversity catches what one lens misses.
+REVIEW_LENSES = [
+    {"name": "correctness",
+     "focus": "logic errors, off-by-one, wrong operators, integer division, edge cases, error paths"},
+    {"name": "spec-conformance",
+     "focus": "requirements stated in the spec that the locked tests do NOT check — find one the code gets wrong"},
+    {"name": "security",
+     "focus": "injection, path traversal, unsafe input handling, leaked secrets, resource exhaustion"},
+    {"name": "robustness",
+     "focus": "behaviour on bad/empty/huge input, concurrency, mutable shared state, failure recovery"},
+]
+
+
+def _clip_diff(diff):
+    if len(diff) <= _DIFF_LIMIT:
+        return diff
+    return (diff[:_DIFF_LIMIT]
+            + f"\n…(diff truncated — {len(diff) - _DIFF_LIMIT} more chars not shown; "
+              "do NOT approve code you could not see)")
+
+
+def _lenses_for(n):
+    """Lenses for a panel of n reviewers. n<=1 → one general reviewer (no extra focus)."""
+    if n <= 1:
+        return [None]
+    return [REVIEW_LENSES[i % len(REVIEW_LENSES)] for i in range(n)]
+
+
+def _review_prompt(spec_md, diff, persona_set, lens=None):
+    body = spec_text("reviewer", persona_set)
+    if lens:
+        body += (f"\n\n## Your lens: {lens['name']}\nWeight your attack toward {lens['focus']}. "
+                 "Still reject any blocking defect you find outside this lens.")
+    return (body + "\n\n## Task spec\n" + spec_md
+            + "\n\n## The diff to review\n```diff\n" + _clip_diff(diff) + "\n```")
+
+
+def _review_panel(runner, spec_md, diff, persona_set, lenses):
+    """Adversarial quorum: run one reviewer per lens. Approved only if ALL approve; score is the
+    harshest (min); feedback aggregates every blocker, labelled by lens. Returns
+    (approved, score, feedback, verdicts)."""
+    verdicts = []
+    for lens in lenses:
+        res = runner.run_structured(_review_prompt(spec_md, diff, persona_set, lens),
+                                    ["approved", "feedback"])
+        ok = res.ok and res.data.get("approved") in _APPROVED
+        try:
+            sc = float(res.data.get("score", 100)) if res.ok else 0.0
+        except (TypeError, ValueError):
+            sc = 0.0
+        fb = str(res.data.get("feedback", "")) if res.ok else "(review call failed)"
+        verdicts.append({"lens": lens["name"] if lens else "review",
+                         "approved": ok, "score": sc, "feedback": fb})
+    approved = bool(verdicts) and all(v["approved"] for v in verdicts)
+    score = min((v["score"] for v in verdicts), default=0.0)
+    feedback = "\n\n".join(f"[{v['lens']}] {v['feedback']}"
+                           for v in verdicts if not v["approved"] and v["feedback"])
+    return approved, score, feedback, verdicts
+
+
+def build_task(repo, slug, *, runner=None, ui=None, gate_cmds=None,
+               persona_set="coding", max_attempts=5, playbook=True, min_quality=0,
+               isolate=True, accept_cmd="pytest --noconftest -q", reviewers=1):
+    """Run the engineer loop on a spec'd task. Returns a result dict or None."""
+    repo = Path(repo).resolve()
+    ui = ui or BuildUI()
+    wt = repo / ".leanlab" / "worktrees" / slug
+    if not wt.is_dir():
+        ui.error(f"no worktree at {wt} — run `leanlab spec` first.")
+        return None
+    branch = f"leanlab/{slug}"
+    spec_md = (wt / "SPEC.md").read_text() if (wt / "SPEC.md").exists() else ""
+    pb = read_playbook(repo)
+    lock = _load_lock(repo, slug)
+    runner = runner or make_runner(wt)
+
+    feedback = None
+    for attempt in range(1, max_attempts + 1):
+        ui.attempt(attempt, max_attempts)
+        with ui.status("Engineer is implementing the change…"):
+            runner.run_plain(_engineer_prompt(spec_md, persona_set, feedback, pb))
+
+        tampered = lock is not None and not _is_pristine(lock, wt)
+        if lock is not None:
+            _restore_tests(lock, wt)             # the gate ALWAYS runs the pristine acceptance tests
+
+        result = run_gate(wt, gate_cmds)
+        ui.gate(result)
+        log_event(repo, slug, {"event": "attempt", "n": attempt, "gate_passed": result.passed,
+                               "failures": [c.name for c in result.failures()]})
+        if not result.passed:
+            feedback = "The gate failed:\n" + "\n".join(
+                f"[{c.name}]\n{c.output[-800:]}" for c in result.failures())
+            continue
+
+        if tampered:
+            ui.error("⚠ locked acceptance tests were modified — restored; rejecting this attempt.")
+            log_event(repo, slug, {"event": "tamper", "n": attempt})
+            feedback = ("You modified the locked acceptance tests (they were restored). They are "
+                        "FROZEN — solve the task without touching them.")
+            continue
+
+        if lock is not None and isolate:
+            ok_iso, _iso = _isolated_acceptance(wt, lock, accept_cmd)
+            if not ok_iso:
+                ui.error("⚠ acceptance tests fail without the engineer's fixtures — gamed.")
+                log_event(repo, slug, {"event": "isolation", "n": attempt})
+                feedback = ("Your change passes only with extra fixtures/conftest. The acceptance "
+                            "tests must pass on their own — implement the real behaviour.")
+                continue
+
+        _stage(wt)
+        diff = _git(wt, "diff", "--cached").stdout
+        lenses = _lenses_for(reviewers)
+        msg = ("Reviewer is checking the diff…" if len(lenses) == 1
+               else f"{len(lenses)} reviewers are attacking the diff…")
+        with ui.status(msg):
+            approved, score, review_fb, verdicts = _review_panel(
+                runner, spec_md, diff, persona_set, lenses)
+        log_event(repo, slug, {"event": "review", "n": attempt, "approved": bool(approved),
+                               "score": score, "feedback": review_fb[:200],
+                               "reviewers": [{"lens": v["lens"], "approved": v["approved"],
+                                              "score": v["score"]} for v in verdicts]})
+        if approved and score >= min_quality:
+            merged = _merge(repo, wt, branch, slug, ui)
+            log_event(repo, slug, {"event": "merged", "branch": branch, "merged": merged})
+            if merged:
+                ui.success(branch, attempt)
+                if playbook:
+                    update_playbook(repo, slug=slug, ui=ui)  # tech-lead refreshes the PLAYBOOK
+            _record(repo, {"slug": slug, "branch": branch, "attempts": attempt,
+                           "merged": merged, "quality": score})
+            return {"branch": branch, "attempts": attempt, "merged": merged, "quality": score}
+        if approved:                                    # passed review but below the quality bar
+            feedback = (f"Quality {score:.0f} is below the required {min_quality:.0f} — improve it. "
+                        + review_fb)
+        else:
+            feedback = "The reviewer(s) requested changes:\n" + (review_fb or "(no feedback)")
+
+    ui.error(f"Gave up after {max_attempts} attempts — not merged.")
+    log_event(repo, slug, {"event": "gaveup", "attempts": max_attempts})
+    _record(repo, {"slug": slug, "branch": branch, "attempts": max_attempts, "merged": False})
+    return {"branch": branch, "attempts": max_attempts, "merged": False}
+
+
+def _merge(repo, wt, branch, slug, ui) -> bool:
+    _stage(wt)
+    _git(wt, "commit", "-m", f"leanlab: {slug}")
+    r = _git(repo, "merge", "--no-ff", "-m", f"leanlab: merge {slug}", branch)
+    if r.returncode != 0:
+        ui.error("merge failed (resolve by hand): " + (r.stderr or r.stdout).strip())
+        return False
+    return True
+
+
+class BuildUI:
+    """Terminal UI for `leanlab build` — attempt rules, spinners, gate report, merge panel."""
+
+    def __init__(self):
+        from rich.console import Console
+        self.console = Console()
+
+    def attempt(self, n, total):
+        self.console.rule(f"[bold cyan]Attempt {n}/{total}", style="cyan")
+
+    def status(self, message):
+        return self.console.status(f"[bold cyan]{message}", spinner="dots")
+
+    def gate(self, result):
+        from .gate import report
+        report(result, self.console)
+
+    def note(self, message):
+        self.console.print(message)
+
+    def error(self, message):
+        self.console.print(f"[bold red]{message}[/bold red]")
+
+    def success(self, branch, attempts):
+        from rich.panel import Panel
+        self.console.print(Panel(
+            f"Merged [bold]{branch}[/bold] into main after {attempts} attempt(s).",
+            title="✓ Task complete", border_style="green"))

leanlab/core/coding/gate.py

@@ -0,0 +1,63 @@
+"""The gate — the deterministic checks a code change must pass.
+
+Objective and binary: every configured command must exit 0 (tests incl. the locked
+acceptance tests, plus optional lint / typecheck). Returns a structured GateResult.
+The LLM quality score (the reviewer) is a separate, later concern.
+"""
+
+from __future__ import annotations
+
+import shlex
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_GATE = [{"name": "tests", "cmd": "pytest -q"}]
+
+
+@dataclass
+class GateCheck:
+    name: str
+    ok: bool
+    code: int
+    output: str
+
+
+@dataclass
+class GateResult:
+    passed: bool
+    checks: list
+
+    def failures(self):
+        return [c for c in self.checks if not c.ok]
+
+
+def run_gate(worktree, gate_cmds=None, *, timeout=600) -> GateResult:
+    """Run each gate command in the worktree; the change passes only if all exit 0."""
+    wt = Path(worktree)
+    checks = []
+    for step in (gate_cmds or DEFAULT_GATE):
+        name, cmd = step["name"], step["cmd"]
+        try:
+            proc = subprocess.run(shlex.split(cmd), cwd=wt, capture_output=True,
+                                  text=True, timeout=timeout)
+            out = (proc.stdout + ("\n" + proc.stderr if proc.stderr else "")).strip()
+            checks.append(GateCheck(name, proc.returncode == 0, proc.returncode, out))
+        except Exception as e:  # noqa: BLE001 — couldn't even run it
+            checks.append(GateCheck(name, False, -1, f"could not run `{cmd}`: {e}"))
+    return GateResult(passed=all(c.ok for c in checks), checks=checks)
+
+
+def report(result: GateResult, console=None):
+    """Print a rich pass/fail report."""
+    if console is None:
+        from rich.console import Console
+        console = Console()
+    for c in result.checks:
+        mark = "[green]✓[/green]" if c.ok else "[red]✗[/red]"
+        console.print(f"{mark} [bold]{c.name}[/bold] (exit {c.code})")
+        if not c.ok:
+            tail = "\n".join(c.output.splitlines()[-12:])
+            console.print(f"[dim]{tail}[/dim]")
+    verdict = "[green]GATE PASSED[/green]" if result.passed else "[red]GATE FAILED[/red]"
+    console.print(f"\n[bold]{verdict}[/bold]")

leanlab/core/coding/personas.py

@@ -0,0 +1,23 @@
+"""Configurable agent persona sets — which package template each role uses.
+
+A lab picks a set ("metric" for the classic Worker/Director/Critic, "coding" for the
+Engineer/Reviewer/Tech-lead). Selectable via lab config and a CLI flag.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+
+PERSONAS = {
+    "metric": {"worker": "CLAUDE.md", "director": "director.md", "critic": "critic.md"},
+    "coding": {"engineer": "engineer.md", "reviewer": "reviewer.md", "techlead": "techlead.md"},
+}
+
+
+def spec_text(role: str, persona_set: str = "coding") -> str:
+    """Load the template text for a role in a persona set (shipped as package data)."""
+    try:
+        fname = PERSONAS[persona_set][role]
+    except KeyError as e:
+        raise KeyError(f"no persona '{role}' in set '{persona_set}'") from e
+    return (resources.files("leanlab") / "templates" / "agents" / fname).read_text().strip()

leanlab/core/coding/playbook.py

@@ -0,0 +1,47 @@
+"""The PLAYBOOK — project knowledge the tech-lead maintains and the engineer reads.
+
+`.leanlab/PLAYBOOK.md` accumulates conventions, architecture notes, and pitfalls so each
+task starts smarter — the coding lab's version of memory. The engineer reads it; after a
+successful merge the tech-lead rewrites it. (The test "ratchet" is automatic: each merged
+task's locked acceptance tests join the main branch's suite and stay.)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..loop import make_runner
+from .personas import spec_text
+
+
+def playbook_path(repo) -> Path:
+    return Path(repo) / ".leanlab" / "PLAYBOOK.md"
+
+
+def read_playbook(repo) -> str:
+    p = playbook_path(repo)
+    return p.read_text().strip() if p.exists() else ""
+
+
+def update_playbook(repo, *, slug=None, runner=None, ui=None) -> None:
+    """Have the tech-lead study recent changes and rewrite .leanlab/PLAYBOOK.md.
+
+    `slug` ties the update to the task that triggered it, so it shows on that task's
+    timeline as the tech-lead's step in the loop.
+    """
+    runner = runner or make_runner(Path(repo))
+    prompt = (
+        spec_text("techlead", "coding") + "\n\n"
+        "Study the recent merged changes (use `git log -p -5` and read key files), then write a "
+        "concise `.leanlab/PLAYBOOK.md`: conventions to follow, the architecture map, and "
+        "pitfalls already hit, as guidance for the next tasks. Create the `.leanlab` directory if "
+        "needed. Write ONLY that file, then stop."
+    )
+    if ui is not None:
+        with ui.status("Tech-lead is updating the PLAYBOOK…"):
+            runner.run_plain(prompt)
+    else:
+        runner.run_plain(prompt)
+    if slug:
+        from .board import log_event          # lazy: board imports playbook, so import here
+        log_event(repo, slug, {"event": "playbook"})

leanlab/core/coding/spec.py

@@ -0,0 +1,232 @@
+"""Spec a coding task — the spec-writer drafts a spec + acceptance tests in an isolated
+git worktree, loops on the operator's feedback, then LOCKS the tests as the frozen
+criteria the engineer is judged by (and can't change).
+
+Realizes the spec-task use case. `runner` / `ui` are injected so it's testable without
+Claude or a terminal.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import subprocess
+from pathlib import Path
+
+from ..loop import make_runner
+from .board import log_event
+
+
+# Filler words dropped from slugs so the name leads with what matters.
+_SLUG_STOP = {"a", "an", "the", "to", "of", "for", "in", "on", "and"}
+
+
+def _slug(task: str, max_len: int = 50) -> str:
+    """A short, readable, stable slug from a task description.
+
+    Rules so the name stays meaningful (vs. a blind 40-char chop):
+      1. Use only the first sentence/line — task briefs are often multi-sentence.
+      2. Drop filler words ("a", "the", "to", …) so the slug leads with the verb/noun.
+      3. Kebab-case and cut on a WORD boundary — never mid-word, never a trailing dash.
+    Deterministic: the same task always yields the same slug.
+    """
+    first = re.split(r"[.\n!?]", task.strip(), maxsplit=1)[0]
+    words = re.sub(r"[^a-z0-9]+", " ", first.lower()).split()
+    meaningful = [w for w in words if w not in _SLUG_STOP] or words
+    out = ""
+    for w in meaningful:
+        candidate = f"{out}-{w}" if out else w
+        if len(candidate) > max_len:
+            break
+        out = candidate
+    if not out and meaningful:                 # a single first word longer than max_len
+        out = meaningful[0][:max_len]
+    return out or "task"
+
+
+def _git(repo, *args):
+    return subprocess.run(["git", "-C", str(repo), *args], capture_output=True, text=True)
+
+
+def _is_git_repo(repo) -> bool:
+    return _git(repo, "rev-parse", "--is-inside-work-tree").returncode == 0
+
+
+def _create_worktree(repo, slug):
+    """Create (or reuse) an isolated worktree + branch for this task."""
+    wt = Path(repo) / ".leanlab" / "worktrees" / slug
+    branch = f"leanlab/{slug}"
+    gi = Path(repo) / ".gitignore"
+    line = ".leanlab/worktrees/"
+    if not gi.exists() or line not in gi.read_text():
+        with gi.open("a") as f:
+            f.write(("" if not gi.exists() or gi.read_text().endswith("\n") else "\n") + line + "\n")
+    if wt.exists():
+        return wt, branch
+    wt.parent.mkdir(parents=True, exist_ok=True)
+    r = _git(repo, "worktree", "add", "-b", branch, str(wt))
+    if r.returncode != 0:                       # branch may already exist — attach to it
+        r2 = _git(repo, "worktree", "add", str(wt), branch)
+        if r2.returncode != 0:
+            raise RuntimeError("git worktree add failed: " + (r.stderr or r2.stderr).strip())
+    return wt, branch
+
+
+def _merged_branches(repo):
+    # `git branch` marks the current branch with "* " and worktree-checked-out ones with "+ ";
+    # the name is after the 2-char marker.
+    out = _git(repo, "branch", "--merged").stdout
+    return {ln[2:].strip() for ln in out.splitlines() if ln.strip()}
+
+
+def clean_worktrees(repo, slug=None, *, remove_all=False) -> list[str]:
+    """Remove task worktrees + branches. Bulk removes only merged ones unless remove_all."""
+    repo = Path(repo).resolve()
+    wtroot = repo / ".leanlab" / "worktrees"
+    if not wtroot.is_dir():
+        return []
+    merged = _merged_branches(repo)
+    if slug:
+        targets = [slug] if (wtroot / slug).is_dir() else []
+    else:
+        all_slugs = [d.name for d in sorted(wtroot.iterdir()) if d.is_dir()]
+        targets = all_slugs if remove_all else [s for s in all_slugs if f"leanlab/{s}" in merged]
+    removed = []
+    for s in targets:
+        branch = f"leanlab/{s}"
+        force_branch = remove_all or bool(slug) or branch not in merged
+        # always --force the worktree: real task worktrees carry an untracked .leanlab-lock.json
+        # that would otherwise block removal. Branch deletion stays safe (-d) unless forced.
+        _git(repo, "worktree", "remove", "--force", str(wtroot / s))
+        _git(repo, "branch", "-D" if force_branch else "-d", branch)
+        (repo / ".leanlab" / "locks" / f"{s}.json").unlink(missing_ok=True)
+        removed.append(s)
+    return removed
+
+
+def _spec_prompt(task: str, feedback: str | None) -> str:
+    base = (
+        "You are the SPEC-WRITER for a coding lab. Turn the task below into a precise spec and "
+        "a set of ACCEPTANCE TESTS that define 'done'. A different agent (the engineer) will be "
+        "judged ONLY by these tests and must not change them — so make them concrete, fair, and "
+        "runnable.\n\n"
+        f"TASK:\n{task}\n\n"
+        "Study the repository in the current directory (read files) to match its language, test "
+        "framework, and conventions. Do NOT create or edit any files — return everything in the "
+        "JSON. Use one or more acceptance test files as needed. Reply with ONLY this JSON object: "
+        '{"spec_md": "<the spec, as markdown>", '
+        '"tests": [{"path": "<relative test file path>", "content": "<full file contents>"}]}'
+    )
+    if feedback:
+        return (f"The operator gave feedback on your previous draft:\n\n{feedback}\n\n"
+                f"Revise the spec and tests accordingly. {base}")
+    return base
+
+
+def spec_task(repo, task, *, runner=None, ui=None, yes=False):
+    """Draft → approve → lock the acceptance tests for a task. Returns a dict or None.
+
+    yes=True auto-approves the first draft (headless, for an agent driving leanlab).
+    """
+    repo = Path(repo).resolve()
+    ui = ui or SpecUI()
+    if not _is_git_repo(repo):
+        ui.error("not a git repository — coding labs need git for worktree isolation")
+        return None
+
+    slug = _slug(task)
+    wt, branch = _create_worktree(repo, slug)
+    runner = runner or make_runner(wt)          # the spec-writer works inside the worktree
+
+    feedback = None
+    while True:
+        with ui.status("Spec-writer is drafting the spec + acceptance tests…"):
+            res = runner.run_structured(_spec_prompt(task, feedback), ["spec_md", "tests"])
+        if not res.ok:
+            ui.error("could not draft the spec — aborting.")
+            return None
+        files = [t for t in res.data["tests"]
+                 if isinstance(t, dict) and t.get("path") and "content" in t]
+        if not files:
+            ui.error("the spec-writer returned no acceptance test files — aborting.")
+            return None
+        (wt / "SPEC.md").write_text(res.data["spec_md"])
+        for t in files:
+            p = wt / t["path"]
+            p.parent.mkdir(parents=True, exist_ok=True)
+            if p.exists():
+                p.chmod(0o644)                   # a prior spec run may have locked this file
+            p.write_text(t["content"])
+
+        ui.spec(res.data["spec_md"])
+        if yes:
+            action, text = "approve", None
+        else:
+            action, text = ui.decide("\n\n".join(f"# {t['path']}\n{t['content']}" for t in files))
+        if action == "approve":
+            # Store the lock + a PRISTINE copy OUTSIDE the worktree, where the engineer (which
+            # works inside the worktree) cannot reach it. The build step restores from here.
+            locked = [{"path": t["path"], "content": t["content"],
+                       "sha256": hashlib.sha256(t["content"].encode()).hexdigest()} for t in files]
+            for t in files:
+                (wt / t["path"]).chmod(0o444)    # in-tree lock is a cosmetic guardrail only
+            locks = repo / ".leanlab" / "locks"
+            locks.mkdir(parents=True, exist_ok=True)
+            (locks / f"{slug}.json").write_text(json.dumps({"tests": locked}))
+            log_event(repo, slug, {"event": "spec", "tests": [t["path"] for t in files]})
+            break
+        if action == "cancel":
+            ui.note("Cancelled — worktree kept, tests not locked.")
+            return None
+        feedback = text
+
+    ui.success(wt, branch)
+    return {"worktree": str(wt), "branch": branch, "test_paths": [t["path"] for t in files]}
+
+
+class SpecUI:
+    """Terminal UI for `leanlab spec` — spinner, spec panel, arrow-key approve menu."""
+
+    def __init__(self):
+        from rich.console import Console
+        self.console = Console()
+
+    def status(self, message):
+        return self.console.status(f"[bold cyan]{message}", spinner="dots")
+
+    def note(self, message):
+        self.console.print(message)
+
+    def error(self, message):
+        self.console.print(f"[bold red]{message}[/bold red]")
+
+    def spec(self, spec_md):
+        from rich.markdown import Markdown
+        from rich.panel import Panel
+        self.console.print(Panel(Markdown(spec_md), title="Proposed spec", border_style="magenta"))
+
+    def decide(self, test_code):
+        import questionary
+        from rich.syntax import Syntax
+        approve, view, feedback, cancel = (
+            "✓ Approve & lock the acceptance tests", "👁 View the acceptance tests",
+            "✍ Give feedback (revise)", "✖ Cancel")
+        while True:
+            choice = questionary.select("What now?", choices=[approve, view, feedback, cancel]).ask()
+            if choice is None or choice == cancel:
+                return ("cancel", None)
+            if choice == view:
+                self.console.print(Syntax(test_code, "python", theme="ansi_dark",
+                                          line_numbers=True, word_wrap=True))
+                continue
+            if choice == approve:
+                return ("approve", None)
+            return ("feedback", questionary.text("Your feedback for the spec-writer:").ask() or "")
+
+    def success(self, worktree, branch):
+        from rich.panel import Panel
+        self.console.print(Panel(
+            f"Spec locked in [bold]{worktree}[/bold]\nbranch [bold]{branch}[/bold]\n\n"
+            "Acceptance tests are frozen — the engineer will implement against them.",
+            title="✓ Spec ready", border_style="green"))