feature-flow-cli 0.1.0__py3-none-any.whl

feature_flow/conductor.py

@@ -0,0 +1,299 @@
+"""The state machine that tells an interactive session what to do next.
+
+It sets the limits, retries and review rounds. It judges every phase from the repo, never from the
+caller, and prints exactly one line per command.
+"""
+
+import os
+import re
+import secrets
+from pathlib import Path
+
+from feature_flow import checks, git, prompts, state, tickets
+
+
+VERDICT = re.compile(r"^REVIEW: (PASS|FAIL)[ \t\r\f\v]*$")
+
+
+class Stop(Exception):
+    """A problem the session must report. Printed as `STOP <reason>`, exit 1."""
+
+
+class NoPhase(Exception):
+    """`prompt` or `verdict` with nothing for it pending: nothing changes, exit 2."""
+
+
+def _env_int(name, default):
+    value = os.environ.get(name, "")
+    try:
+        return int(value) if value.strip() else default
+    except ValueError:
+        raise Stop("%s must be a whole number, not %s" % (name, value))
+
+
+class Conductor:
+    def __init__(self, feature, scripts):
+        self.feature = feature
+        self.scripts = Path(scripts)
+        self.root = Path(os.environ.get("FLOW_DIR") or "plans")
+        self.plan = self.root / feature
+        self.commands = self.plan / "commands.md"
+        self.max_retries = _env_int("FLOW_MAX_RETRIES", 2)
+        self.max_rounds = _env_int("FLOW_MAX_REVIEW_ROUNDS", 3)
+        self.gate_on = os.environ.get("FLOW_GATE", "on") != "off"
+        self.per_session = _env_int("FLOW_TICKETS_PER_SESSION", 4)
+        self.relay = os.environ.get("FLOW_RELAY", "0") == "1"
+        self.invoke = os.environ.get("FLOW_INVOKE") or "/feature-flow"
+        top = git.toplevel()
+        if top is None:
+            raise Stop("not inside a git worktree")
+        try:
+            folder = state.state_dir(top)
+            state.migrate(git.git_dir(), folder, feature)
+        except OSError as err:
+            raise Stop("cannot write the flow state in %s: %s. this session must be allowed to write there"
+                       % (top / state.STATE_DIR, err.strerror or err))
+        self.state_file = state.state_path(folder, feature)
+        self.log_file = state.log_path(folder, feature)
+        self.findings_file = state.file_path(folder, feature, "findings")
+        self.st = state.load(self.state_file)
+
+    # ---- small helpers -------------------------------------------------
+
+    def get(self, key, default=""):
+        return self.st.get(key, default)
+
+    def num(self, key):
+        try:
+            return int(self.st.get(key, "0") or 0)
+        except ValueError:
+            raise Stop("the state file %s is damaged: %s is not a number" % (self.state_file, key))
+
+    def save(self):
+        state.save(self.state_file, self.st)
+
+    def log(self, event):
+        state.log(self.log_file, self.get("num"), event)
+
+    def emit(self, line):
+        self.log(line.split(" ", 1)[0])
+        return line
+
+    def ticket(self):
+        return self.get("ticket")
+
+    def ticket_name(self):
+        return tickets.name(self.ticket())
+
+    # ---- the checks ----------------------------------------------------
+
+    def smoke_command(self):
+        cmd = os.environ.get("FLOW_SMOKE", "")
+        if not cmd:
+            cmd = tickets.commands_value(self.commands, "Smoke")
+        return "" if cmd.startswith("<") else cmd
+
+    def run_smoke(self):
+        cmd = self.smoke_command()
+        if not cmd:
+            return
+        result = checks.smoke(cmd)
+        if not result.ok:
+            raise Stop("smoke test failed before %s: the base is already broken. fix it first. command: %s"
+                       % (self.ticket_name(), cmd))
+
+    def run_limit(self):
+        result = checks.flow_status(self.scripts, self.feature, "--counts")
+        total = 0
+        for word in result.out.split():
+            if word.startswith("total="):
+                total = int(word[len("total="):])
+        return total * 2 * self.max_retries * (self.max_rounds + 1) + 1
+
+    def count_run(self):
+        runs = self.num("runs") + 1
+        limit = self.num("limit")
+        if runs > limit:
+            raise Stop("run limit of %d sessions reached, stopping" % limit)
+        self.st["runs"] = runs
+
+    # ---- phases --------------------------------------------------------
+
+    def hand_out_build(self):
+        self.count_run()
+        self.st["phase"] = "build"
+        self.st["attempt"] = self.num("attempt") + 1
+        self.st["relay_handoff"] = "1" if self.relay else ""
+        self.save()
+        return self.emit("BUILD %s %s %s" % (self.ticket(), self.get("num"), self.get("base")))
+
+    def hand_out_review(self):
+        self.count_run()
+        self.st["phase"] = "review"
+        self.st["review_attempt"] = self.num("review_attempt") + 1
+        self.st["review_sha"] = git.head()
+        self.st["relay_handoff"] = "1" if self.relay else ""
+        self.save()
+        return self.emit("REVIEW %s %s %s" % (self.ticket(), self.get("num"), self.get("base")))
+
+    def send_back(self, source, findings):
+        """Write the findings into the ticket, reopen it, commit, and build again."""
+        round_no = self.num("round") + 1
+        if round_no > self.max_rounds:
+            raise Stop("%s still fails the %s after %d round(s)" % (self.ticket_name(), source, self.max_rounds))
+        self.st["round"] = round_no
+        tickets.append_findings(self.ticket(), round_no, source, findings)
+        tickets.set_open(self.ticket())
+        if not git.commit_file(self.ticket(), "chore(%s): %s review findings, round %d"
+                               % (self.feature, self.get("num"), round_no)):
+            raise Stop("cannot commit the %s findings to %s. this session must be allowed to run git commit"
+                       % (source, self.ticket_name()))
+        self.st["attempt"] = 0
+        self.st["review_attempt"] = 0
+        return self.hand_out_build()
+
+    def pick_ticket(self):
+        """Hand out the next ready ticket, or finish."""
+        check = checks.flow_status(self.scripts, self.feature, "--check")
+        if not check.ok:
+            raise Stop("ticket check failed, fix the tickets first")
+        if not git.is_clean():
+            raise Stop("working tree is not clean, commit or stash first")
+        nxt = checks.flow_status(self.scripts, self.feature, "--next")
+        if nxt.code == 10:
+            done = self.num("done")
+            self.st["phase"] = ""
+            self.st["owner"] = ""
+            self.save()
+            return self.emit("DONE %s is complete: %d ticket(s) resolved in this run" % (self.feature, done))
+        if nxt.code == 11:
+            raise Stop("stuck: unfinished tickets remain but none is ready. run: python3 scripts/flow-status.py %s"
+                       % self.feature)
+        if nxt.code != 0:
+            raise Stop("flow-status.py failed with exit code %d" % nxt.code)
+        if self.per_session > 0 and self.num("session_done") >= self.per_session:
+            return self.handoff()
+        path = nxt.out.strip().splitlines()[-1]
+        self.st.update({"ticket": path, "num": tickets.number(path), "base": git.head(), "phase": "",
+                        "attempt": 0, "review_attempt": 0, "round": 0, "review_sha": ""})
+        self.run_smoke()
+        return self.hand_out_build()
+
+    def judge_build(self):
+        status = tickets.status(self.ticket())
+        if status not in tickets.DONE:
+            if status in tickets.RESET:
+                tickets.set_open(self.ticket())
+            if self.num("attempt") >= self.max_retries:
+                raise Stop("%s is still unresolved after %d attempt(s)" % (self.ticket_name(), self.max_retries))
+            return self.hand_out_build()
+        if not git.is_clean():
+            raise Stop("working tree is dirty after %s, it should have been committed" % self.ticket_name())
+        if self.gate_on:
+            result = checks.gate(self.scripts, self.feature)
+            self.log("GATE-PASS" if result.ok else "GATE-FAIL")
+            if not result.ok:
+                return self.send_back("gate", result.out)
+        result = checks.floor_guard(self.scripts, self.feature, self.get("num"), self.get("base"))
+        self.log("GUARD-PASS" if result.ok else "GUARD-FAIL")
+        if not result.ok:
+            return self.send_back("floor guard", result.out)
+        return self.hand_out_review()
+
+    # ---- commands ------------------------------------------------------
+
+    def handoff(self):
+        """Release the owner; the user continues in a new session with the printed line."""
+        self.st["owner"] = ""
+        self.st["relay_handoff"] = ""
+        self.save()
+        return self.emit("HANDOFF %s %s" % (self.invoke, self.feature))
+
+    def check_owner(self):
+        """While a session owns the feature, every call must carry its token. Checked before any change."""
+        owner = self.get("owner")
+        if owner and os.environ.get("FLOW_SESSION", "") != owner:
+            raise Stop("%s is owned by another session (%s). pass its token as FLOW_SESSION, or start this session "
+                       "with FLOW_TAKEOVER=1 once you are sure the other one is closed" % (self.feature, owner))
+
+    def start(self):
+        if not self.plan.is_dir():
+            return self.emit("PLAN")
+        owner = self.get("owner")
+        takeover = bool(owner)
+        if owner and os.environ.get("FLOW_TAKEOVER", "0") != "1":
+            raise Stop("%s is owned by session %s. if that session is closed or dead, run start with FLOW_TAKEOVER=1"
+                       % (self.feature, owner))
+        token = secrets.token_hex(8)
+        self.st["owner"] = token
+        self.st["session_done"] = 0
+        self.save()
+        self.log("TAKEOVER" if takeover else "START")
+        return "OK %s" % token
+
+    def next(self):
+        self.check_owner()
+        if not self.plan.is_dir():
+            raise Stop("no plan folder %s" % self.plan)
+        if self.get("relay_handoff") == "1":
+            return self.handoff()
+        if "limit" not in self.st:
+            self.st["limit"] = self.run_limit()
+            self.st.setdefault("runs", 0)
+            self.st.setdefault("done", 0)
+        phase = self.get("phase")
+        if phase == "build":
+            return self.judge_build()
+        if phase == "review":
+            return self.judge_review()
+        return self.pick_ticket()
+
+    def judge_review(self):
+        if not git.tracked_clean() or git.head() != self.get("review_sha"):
+            raise Stop("the reviewer changed tracked files, which a reviewer must never do")
+        verdict = self.get("verdict")
+        self.st["verdict"] = ""
+        if verdict == "pass":
+            self.st["phase"] = ""
+            self.st["done"] = self.num("done") + 1
+            self.st["session_done"] = self.num("session_done") + 1
+            self.save()
+            return self.pick_ticket()
+        if verdict == "fail":
+            findings = self.findings_file.read_text(encoding="utf-8") if self.findings_file.is_file() else ""
+            return self.send_back("independent review", findings)
+        if self.num("review_attempt") >= self.max_retries:
+            raise Stop("no review verdict for %s after %d attempt(s)" % (self.ticket_name(), self.max_retries))
+        return self.hand_out_review()
+
+    def prompt(self):
+        """The full prompt for the BUILD or REVIEW that `next` handed out. Exit 2 (NoPhase) when none is."""
+        self.check_owner()
+        phase = self.get("phase")
+        if phase not in ("build", "review"):
+            raise NoPhase("no BUILD or REVIEW is pending for %s" % self.feature)
+        try:
+            return prompts.build(phase, self.scripts, self.feature, self.ticket(), self.get("num"), self.get("base"))
+        except FileNotFoundError as err:
+            raise Stop(str(err))
+
+    def verdict(self, reply):
+        """Record the reviewer's reply. Exit 2 (NoPhase) unless a review is pending."""
+        self.check_owner()
+        if self.get("phase") != "review":
+            raise NoPhase("no review is pending for %s" % self.feature)
+        try:
+            text = Path(reply).read_text(encoding="utf-8", errors="replace")
+        except OSError as err:
+            raise Stop("cannot read the review reply %s: %s" % (reply, err.strerror))
+        found = ""
+        for line in text.splitlines():
+            match = VERDICT.match(line)
+            if match:
+                found = match.group(1).lower()
+        if found == "fail":
+            self.findings_file.write_text("\n".join(text.splitlines()[:120]) + "\n", encoding="utf-8")
+        self.st["verdict"] = found or "none"
+        self.save()
+        self.log("VERDICT-%s" % (found or "none").upper())
+        return "OK" if found else "RETRY no review verdict"

feature_flow/floorguard.py

@@ -0,0 +1,340 @@
+"""The floor guard, ported from the bash script with the same output and exit codes.
+
+usage: python3 scripts/floor-guard.py <feature> <NN> [base-commit]
+looks at the diff from base-commit (default HEAD~1) to HEAD for ways of weakening the bar
+instead of meeting it: skipped tests, silenced checks, empty catches, deleted tests,
+lowered thresholds, edited lint or test config.
+it also protects the plan from the worker: only the ticket's own Status line and Answer,
+appended lines in map.md and learnings.md may change, and nothing else under the plans folder.
+a ticket can allow categories with a line "Floor: allow skip, suppress" (skip, suppress,
+empty-catch, test-delete, threshold, config, ticket-edit, commands-edit). the line is
+read from the ticket as it was at base-commit, so a worker cannot excuse itself.
+run it from the repo root. exit 0 clean, 1 findings, 2 usage error.
+
+The bash version ran its pattern matching in awk (mawk on Ubuntu, a byte-oriented awk), so the
+diff is handled here as bytes too: the patterns, the 100 byte cut and the lower-casing behave
+like mawk's. Text is decoded with surrogateescape so any byte comes back out unchanged.
+"""
+
+import os
+import re
+import subprocess
+import sys
+
+USAGE = "usage: python3 scripts/floor-guard.py <feature> <NN> [base-commit]"
+
+SKIP = re.compile(rb"@pytest\.mark\.(skip|xfail)|pytest\.skip\(|(^|[^A-Za-z_])(it|test|describe)\.(skip|todo)\("
+                  rb"|(^|[^A-Za-z_])(xit|xdescribe|xtest)\(|@Disabled|t\.Skip\(|#\[ignore\]|unittest\.skip")
+SUPPRESS = re.compile(rb"# noqa|# type: ignore|# pylint: disable|# pragma: no cover|# fmt: off|# ruff: noqa"
+                      rb"|eslint-disable|@ts-ignore|@ts-expect-error|// nolint|#\[allow\(|--no-verify")
+EMPTY_CATCH = re.compile(rb"except[^:]*:[ \t]*pass[ \t]*$|catch[ \t]*(\([^)]*\))?[ \t]*\{[ \t]*\}")
+THRESHOLD = re.compile(rb"fail_under|fail-under|coverageThreshold|cov-fail-under")
+DELETED_TEST = re.compile(r"(^|/)(test_[^/]*\.py|[^/]*_test\.[a-z]+|[^/]*\.(test|spec)\.[a-z]+|tests?/|__tests__/)")
+CONFIG = re.compile(r"(^|/)(\.eslintrc[^/]*|eslint\.config\.[a-z]+|ruff\.toml|\.ruff\.toml|mypy\.ini|pytest\.ini"
+                    r"|tox\.ini|tsconfig[^/]*\.json|jest\.config\.[a-z]+|vitest\.config\.[a-z]+"
+                    r"|\.pre-commit-config\.yaml|\.github/workflows/[^/]*|\.azure/.*)$")
+ASSERT_REMOVED = re.compile(rb"^-.*(assert|expect\()")
+ASSERT_ADDED = re.compile(rb"^\+.*(assert|expect\()")
+FIELDS = re.compile(rb"[ \t\n]+")
+SPACE_CHARS = " \t\n\v\f\r"
+HEX = b"0123456789abcdefABCDEF"
+
+
+def _text(data):
+    return data.decode("utf-8", "surrogateescape")
+
+
+def _bytes(text):
+    return text.encode("utf-8", "surrogateescape")
+
+
+def _records(data):
+    """awk records: split on newline, a last line without one still counts."""
+    if not data:
+        return []
+    lines = data.split(b"\n")
+    if lines[-1] == b"":
+        lines.pop()
+    return lines
+
+
+def _strip_newlines(data):
+    """What $(...) does to a command's output."""
+    return data.rstrip(b"\n")
+
+
+def _ascii_lower(data):
+    return bytes(c + 32 if 65 <= c <= 90 else c for c in data)
+
+
+def _awk_assign(value):
+    """Escape processing mawk applies to `awk -v name=value`."""
+    simple = {ord('"'): b'"', ord("\\"): b"\\", ord("a"): b"\a", ord("b"): b"\b", ord("f"): b"\f",
+              ord("n"): b"\n", ord("r"): b"\r", ord("t"): b"\t", ord("v"): b"\v"}
+    out = bytearray()
+    i = 0
+    while i < len(value):
+        c = value[i]
+        if c != 0x5C or i + 1 >= len(value):
+            out.append(c)
+            i += 1
+            continue
+        nxt = value[i + 1]
+        if nxt in simple:
+            out += simple[nxt]
+            i += 2
+        elif 0x30 <= nxt <= 0x37:
+            j = i + 1
+            while j < len(value) and j < i + 4 and 0x30 <= value[j] <= 0x37:
+                j += 1
+            out.append(int(value[i + 1:j], 8) & 0xFF)
+            i = j
+        elif nxt == ord("x") and value[i + 2:i + 3] and value[i + 2:i + 3] in HEX:
+            j = i + 2
+            while j < len(value) and j < i + 4 and value[j:j + 1] in HEX:
+                j += 1
+            out.append(int(value[i + 2:j], 16))
+            i = j
+        else:
+            out.append(c)
+            i += 1
+    return bytes(out)
+
+
+def allow_line(source):
+    """The categories named on the first `Floor:` line in the first 20 lines, lower case."""
+    for n, line in enumerate(_records(source), 1):
+        if n > 20:
+            break
+        if line.startswith(b"Floor:"):
+            v = re.sub(rb"^floor:[ \t]*allow[ \t]*", b"", _ascii_lower(line), count=1)
+            return v.replace(b",", b" ")
+    return b""
+
+
+def diff_findings(diff, allow):
+    """The awk pass over added lines: skip, suppress, empty-catch and threshold."""
+    allow = b" " + _awk_assign(allow) + b" "
+    out = []
+    file = b""
+
+    def report(cat, text):
+        if (b" " + cat + b" ") in allow:
+            return
+        text = re.sub(rb"^[ \t]+", b"", text, count=1)
+        out.append(cat + b": " + file + b": " + text[:100] + b"\n")
+
+    for record in _records(diff):
+        if record.startswith(b"+++ "):
+            fields = FIELDS.split(record.strip(b" \t\n"))
+            file = fields[1] if len(fields) > 1 else b""
+            if file.startswith(b"b/"):
+                file = file[2:]
+            continue
+        if record.startswith(b"+"):
+            line = record[1:]
+            if SKIP.search(line):
+                report(b"skip", line)
+            if SUPPRESS.search(line):
+                report(b"suppress", line)
+            if EMPTY_CATCH.search(line):
+                report(b"empty-catch", line)
+            if THRESHOLD.search(line):
+                report(b"threshold", line)
+    return b"".join(out)
+
+
+def frozen(data):
+    """The ticket without its first Status line and from its Answer or Review findings on."""
+    out = []
+    seen = False
+    for n, line in enumerate(_records(data), 1):
+        if n <= 20 and not seen and line.startswith(b"Status:"):
+            seen = True
+            continue
+        if re.match(rb"## (Answer|Review findings)", line):
+            break
+        out.append(line + b"\n")
+    return b"".join(out)
+
+
+def count_removed_real_lines(diff):
+    n = 0
+    for line in _records(diff):
+        if line.startswith(b"---"):
+            continue
+        if line.startswith(b"-"):
+            text = line[1:].strip(b" \t")
+            if text != b"" and not re.match(rb"(- )?<", text):
+                n += 1
+    return n
+
+
+def count_matching(diff, pattern):
+    return sum(1 for line in _records(diff) if pattern.search(line))
+
+
+def _find_ticket(dir_, num):
+    """The first match of the glob "$DIR"/"$NUM"-*.md, or None."""
+    prefix = dir_ + "/" + num + "-"
+    folder, start = os.path.split(prefix)
+    try:
+        names = os.listdir(folder or ".")
+    except OSError:
+        return None
+    hits = sorted(name for name in names
+                  if name.startswith(start) and name.endswith(".md") and len(name) >= len(start) + 3
+                  and (start.startswith(".") or not name.startswith(".")))
+    return prefix + hits[0][len(start):] if hits else None
+
+
+class _Guard:
+    def __init__(self, err):
+        self.err = err
+
+    def git(self, *args, quiet=False):
+        result = subprocess.run(["git"] + list(args), stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        if result.stderr and not quiet:
+            self.err(_text(result.stderr))
+        return result.returncode, result.stdout
+
+
+def run(argv, out, err, environ=None):
+    """Run the guard. out and err take text; returns the exit code."""
+    environ = os.environ if environ is None else environ
+    feature = argv[0] if len(argv) > 0 else ""
+    num = argv[1] if len(argv) > 1 else ""
+    base = argv[2] if len(argv) > 2 and argv[2] else "HEAD~1"
+    if not feature or not num:
+        err(USAGE + "\n")
+        return 2
+
+    root = environ.get("FLOW_DIR") or "plans"
+    dir_ = "%s/%s/%s" % (root, feature, environ.get("FLOW_TICKETS") or "tasks")
+    ticket = _find_ticket(dir_, num)
+    if ticket is None or not os.path.exists(ticket):
+        err("no ticket %s in %s\n" % (num, dir_))
+        return 2
+
+    g = _Guard(err)
+    if g.git("cat-file", "-e", "%s:./%s" % (base, ticket), quiet=True)[0] == 0:
+        source = _strip_newlines(g.git("show", "%s:./%s" % (base, ticket), quiet=True)[1])
+    else:
+        try:
+            with open(ticket, "rb") as f:
+                source = _strip_newlines(f.read())
+        except OSError as e:
+            err("cat: %s: %s\n" % (ticket, e.strerror))
+            return 1
+    allow = allow_line(source)
+    allow_words = " %s " % _text(allow)
+
+    def allows(cat):
+        return (" %s " % cat) in allow_words
+
+    outside = ["--", ".", ":(exclude)%s" % root]
+    rc, diff = g.git("diff", "--no-color", "--unified=0", base, "HEAD", *outside)
+    if rc != 0:
+        return rc
+    findings = _text(_strip_newlines(diff_findings(diff, allow)))
+
+    deleted = _git_lines(g, DELETED_TEST, "diff", "--name-only", "--diff-filter=D", base, "HEAD", *outside)
+    if deleted and not allows("test-delete"):
+        findings += "\n" + "\n".join("test-delete: " + p for p in deleted)
+
+    touched = _git_lines(g, CONFIG, "diff", "--name-only", base, "HEAD", *outside)
+    if touched and not allows("config"):
+        findings += "\n" + "\n".join("config: " + p for p in touched)
+
+    def rel(path):
+        p = _records(g.git("ls-files", "--full-name", "--", path, quiet=True)[1])
+        if p and p[0]:
+            return _text(p[0])
+        return path[2:] if path.startswith("./") else path
+
+    def show(rev, path):
+        return g.git("show", "%s:./%s" % (rev, path), quiet=True)[1]
+
+    t_rel = rel(ticket)
+    m_rel = rel("%s/%s/map.md" % (root, feature))
+    c_rel = rel("%s/%s/commands.md" % (root, feature))
+    l_rel = rel("%s/%s/learnings.md" % (root, feature))
+
+    added = []
+
+    def add_finding(cat, path, text):
+        added.append("%s: %s: %s" % (cat, path, text))
+
+    for st, path in _name_status(g.git("diff", "--name-status", "--no-renames", base, "HEAD", "--", root)[1]):
+        if path == t_rel:
+            if allows("ticket-edit"):
+                continue
+            if st != "M":
+                add_finding("ticket-edit", path, "the ticket was added or deleted")
+            elif frozen(show(base, path)) != frozen(show("HEAD", path)):
+                add_finding("ticket-edit", path, "text outside the Status line and the Answer was changed")
+        elif path in (m_rel, l_rel):
+            if allows("ticket-edit"):
+                continue
+            if st == "D":
+                add_finding("ticket-edit", path, "the file was deleted")
+            elif st == "M" and count_removed_real_lines(
+                    g.git("diff", "--no-color", "--unified=0", base, "HEAD", "--", path)[1]) > 0:
+                add_finding("ticket-edit", path, "existing lines were removed or rewritten (append only)")
+        elif path == c_rel:
+            if not allows("commands-edit"):
+                add_finding("commands-edit", path, "the frozen commands file was changed")
+        else:
+            if not allows("ticket-edit"):
+                add_finding("ticket-edit", path, "only your own ticket, map.md and learnings.md may change")
+    for line in added:
+        findings += "\n" + line
+
+    findings = "\n".join(line for line in findings.split("\n") if line.strip(SPACE_CHARS))
+
+    diff = g.git("diff", "--no-color", "--unified=0", base, "HEAD", *outside)[1]
+    removed_asserts = count_matching(diff, ASSERT_REMOVED)
+    diff = g.git("diff", "--no-color", "--unified=0", base, "HEAD", *outside)[1]
+    added_asserts = count_matching(diff, ASSERT_ADDED)
+    if removed_asserts > added_asserts:
+        out("warning: %d assertion line(s) removed, %d added. check that no test got weaker.\n"
+            % (removed_asserts, added_asserts))
+
+    if findings:
+        out("floor guard: the diff weakens the bar instead of meeting it\n")
+        out(findings + "\n")
+        out("if a finding is intended, the ticket needs a line like: Floor: allow <category>\n")
+        return 1
+    out("floor guard: clean\n")
+    return 0
+
+
+def _git_lines(g, pattern, *args):
+    """git ... | grep -E pattern, as a list of lines."""
+    return [line for line in (_text(r) for r in _records(g.git(*args)[1])) if pattern.search(line)]
+
+
+def _name_status(data):
+    """`while IFS=$'\\t' read -r st path`: the first field and the rest, outer tabs trimmed."""
+    rows = []
+    for record in _records(data):
+        line = _text(record).strip("\t")
+        st, _, path = line.partition("\t")
+        path = path.lstrip("\t")
+        if path:
+            rows.append((st, path))
+    return rows
+
+
+def main(argv=None):
+    """The command line: writes the exact bytes to stdout and stderr."""
+    argv = sys.argv[1:] if argv is None else argv
+
+    def writer(stream):
+        def write(text):
+            stream.buffer.write(_bytes(text))
+            stream.buffer.flush()
+        return write
+
+    sys.stdout.flush()
+    return run(argv, writer(sys.stdout), writer(sys.stderr))