@intentsolutionsio/dolt-mcp-vcs 0.1.0

package/scripts/profile_sql.py

@@ -0,0 +1,97 @@
+"""profile_sql.py — build the version-control audit SQL from a schema PROFILE.
+
+This is the seam that proves the use-case-adapter inversion (the panel's
+schema-profile MAJOR / §9): the generic queries (epic-closure drift, dependency
+bottlenecks) are emitted from a profile's table/column/encoding/value names, so a
+SECOND schema (profiles/example-generic.profile.json) runs the same logic with
+zero code change. `beads` stops being hardcoded and becomes profile #1.
+
+A profile is untrusted INPUT — names are quoted as identifiers and the type-value
+is quoted as a literal, so a malicious profile cannot inject SQL. (Live schema
+introspection still wins over the profile at agent runtime.)
+
+Pure stdlib; importable for tests.
+"""
+import json
+import re
+
+_IDENT = re.compile(r"^[A-Za-z_][A-Za-z_0-9]*$")
+
+
+def load_profile(path):
+    with open(path) as fh:
+        return json.load(fh)
+
+
+def _ident(name):
+    """Validate a table/column identifier and return it bare. Rejects anything that
+    is not a plain identifier, so a hostile profile cannot smuggle SQL through a
+    table/column name."""
+    if not isinstance(name, str) or not _IDENT.match(name):
+        raise ValueError(f"unsafe identifier in profile: {name!r}")
+    return name
+
+
+def _lit(value):
+    """Single-quote a string literal, escaping embedded quotes."""
+    if not isinstance(value, str):
+        raise ValueError(f"non-string value in profile: {value!r}")
+    return "'" + value.replace("'", "''") + "'"
+
+
+def _enc(profile, key):
+    enc = profile["encodings"][key]
+    return enc, enc.get("value", key)   # type-column value defaults to the encoding key
+
+
+def epic_closure_sql(profile):
+    """OPEN epics whose entire parent-child child set is already closed."""
+    issues = _ident(profile["tables"]["issues"])
+    deps = _ident(profile["tables"]["dependencies"])
+    col_id = _ident(profile["columns"]["id"])
+    col_status = _ident(profile["columns"]["status"])
+    col_type = _ident(profile["columns"]["type"])
+    col_itype = _ident(profile["columns"]["issue_type"])
+    pc, pc_val = _enc(profile, "parent-child")
+    child = _ident(pc["child"])
+    parent = _ident(pc["parent"])
+    closed = _lit(profile["closed-value"])
+    epic = _lit(profile["epic-value"])
+    pc_lit = _lit(pc_val)
+    return (
+        f"SELECT e.{col_id} AS epic, COUNT(d.{child}) AS children, "
+        f"SUM(CASE WHEN c.{col_status}={closed} THEN 1 ELSE 0 END) AS closed "
+        f"FROM {issues} e "
+        f"JOIN {deps} d ON d.{parent}=e.{col_id} AND d.{col_type}={pc_lit} "
+        f"JOIN {issues} c ON c.{col_id}=d.{child} "
+        f"WHERE e.{col_itype}={epic} AND e.{col_status}<>{closed} "
+        f"GROUP BY e.{col_id} "
+        f"HAVING children>0 AND closed=children "
+        f"ORDER BY children DESC"
+    )
+
+
+def bottleneck_sql(profile, top=10):
+    """OPEN issues blocking the most other OPEN issues (the `blocks` encoding)."""
+    if not isinstance(top, int) or isinstance(top, bool) or top < 1:
+        raise ValueError("top must be a positive integer")
+    issues = _ident(profile["tables"]["issues"])
+    deps = _ident(profile["tables"]["dependencies"])
+    col_id = _ident(profile["columns"]["id"])
+    col_status = _ident(profile["columns"]["status"])
+    col_type = _ident(profile["columns"]["type"])
+    bl, bl_val = _enc(profile, "blocks")
+    blocked = _ident(bl["blocked"])
+    blocker = _ident(bl["blocker"])
+    closed = _lit(profile["closed-value"])
+    bl_lit = _lit(bl_val)
+    return (
+        f"SELECT b.{col_id} AS blocker, b.{col_status} AS status, COUNT(*) AS blocking_open "
+        f"FROM {deps} d "
+        f"JOIN {issues} b ON b.{col_id}=d.{blocker} "
+        f"JOIN {issues} blocked ON blocked.{col_id}=d.{blocked} "
+        f"WHERE d.{col_type}={bl_lit} AND b.{col_status}<>{closed} "
+        f"AND blocked.{col_status}<>{closed} "
+        f"GROUP BY b.{col_id}, b.{col_status} "
+        f"ORDER BY blocking_open DESC LIMIT {top}"
+    )

package/scripts/resolve-creds-ref.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""resolve-creds-ref.py — resolve a connection-descriptor `creds-ref` to a secret.
+
+A `creds-ref` is a POINTER to a secret, never the secret itself (blueprint §2 /
+the panel's creds-ref MAJOR). Accepted schemes:
+
+  env:NAME            environment variable NAME
+  sops:PATH#KEY       KEY from a SOPS-encrypted file at PATH — decrypted to stdout
+                      only, NEVER to disk (per the SOPS posture)
+  pass:PATH           `pass show PATH`
+
+Resolution is **fail-closed**:
+  * an unknown scheme exits non-zero (this is the validator rule — a `creds-ref`
+    that is not a known `scheme:` prefix is rejected, never silently treated as a
+    literal);
+  * an empty/unresolved secret for a NON-loopback endpoint exits non-zero — we
+    never connect a remote endpoint with an empty (unauthenticated) password;
+  * for a loopback endpoint (127.0.0.1 / localhost / ::1) an empty result IS
+    allowed — bd's local dolt server is unauthenticated by default.
+
+The resolved secret is printed to stdout for capture into an env var:
+  export DOLT_PASSWORD="$(resolve-creds-ref.py --creds-ref env:DOLT_PASSWORD --endpoint 127.0.0.1:3308)"
+NEVER echo or log the captured value.
+
+Exit: 0 ok (secret on stdout; may be empty for loopback) · 2 bad usage /
+      unknown scheme · 4 resolution failed (fail-closed).
+"""
+import argparse
+import os
+import subprocess
+import sys
+
+KNOWN_SCHEMES = ("env", "sops", "pass")
+_LOOPBACK_HOSTS = {"127.0.0.1", "localhost", "::1", ""}
+
+
+def eprint(*a):
+    print(*a, file=sys.stderr)
+
+
+def is_loopback(endpoint):
+    host = (endpoint or "").strip()
+    if host.startswith("["):                      # [::1]:3306
+        host = host[1:].split("]", 1)[0]
+    elif host.count(":") == 1:                     # host:port
+        host = host.rsplit(":", 1)[0]
+    return host.lower() in _LOOPBACK_HOSTS
+
+
+def parse_scheme(ref):
+    if ":" not in ref:
+        return None, None
+    scheme, rest = ref.split(":", 1)
+    return scheme.lower(), rest
+
+
+def resolve_env(rest):
+    return os.environ.get(rest, "")
+
+
+def resolve_pass(rest):
+    try:
+        out = subprocess.run(["pass", "show", rest], capture_output=True,
+                             text=True, timeout=15)
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    if out.returncode != 0:
+        return ""
+    return out.stdout.splitlines()[0] if out.stdout else ""
+
+
+def resolve_sops(rest):
+    if "#" not in rest:
+        eprint("error: sops ref must be 'sops:PATH#KEY'")
+        return None  # signals usage error
+    path, key = rest.rsplit("#", 1)
+    # dotenv files: decrypt as dotenv, then read KEY=VALUE. Structured (yaml/json):
+    # use --extract for a single value. Both stream to stdout only (never to disk).
+    is_dotenv = path.endswith((".env", ".env.sops")) or ".env" in os.path.basename(path)
+    try:
+        if is_dotenv:
+            out = subprocess.run(["sops", "-d", "--input-type", "dotenv",
+                                  "--output-type", "dotenv", path],
+                                 capture_output=True, text=True, timeout=30)
+            if out.returncode != 0:
+                return ""
+            for line in out.stdout.splitlines():
+                if line.startswith(key + "="):
+                    return line.split("=", 1)[1].strip().strip('"').strip("'")
+            return ""
+        out = subprocess.run(["sops", "-d", "--extract", f'["{key}"]', path],
+                             capture_output=True, text=True, timeout=30)
+        return out.stdout.strip() if out.returncode == 0 else ""
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def resolve(ref):
+    """Return (secret, ok). ok=False on unknown scheme / usage error."""
+    scheme, rest = parse_scheme(ref)
+    if scheme not in KNOWN_SCHEMES:
+        eprint(f"error: unknown creds-ref scheme '{scheme}'. "
+               f"Accepted: {', '.join(s + ':' for s in KNOWN_SCHEMES)}")
+        return None, False
+    if scheme == "env":
+        return resolve_env(rest), True
+    if scheme == "pass":
+        return resolve_pass(rest), True
+    secret = resolve_sops(rest)
+    if secret is None:        # sops usage error
+        return None, False
+    return secret, True
+
+
+def main():
+    ap = argparse.ArgumentParser(description="resolve a descriptor creds-ref (fail-closed)")
+    ap.add_argument("--creds-ref", required=True, help="env:NAME | sops:PATH#KEY | pass:PATH")
+    ap.add_argument("--endpoint", default=os.environ.get("DOLT_ENDPOINT", "127.0.0.1:3308"),
+                    help="host:port — loopback permits an empty secret")
+    args = ap.parse_args()
+
+    secret, ok = resolve(args.creds_ref)
+    if not ok:
+        return 2
+    if not secret:
+        if is_loopback(args.endpoint):
+            return 0  # empty is fine for a loopback (unauthenticated) server
+        eprint(f"error: creds-ref '{args.creds_ref}' resolved empty for non-loopback "
+               f"endpoint '{args.endpoint}' — refusing to connect unauthenticated (fail-closed).")
+        return 4
+    sys.stdout.write(secret)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/server-health.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# server-health.sh — inventory running `dolt sql-server` processes and flag sprawl.
+# bd starts a per-project server on an auto-detected port; over time that becomes
+# many servers (one per workspace). This maps each running server to its workspace
+# and warns when the count suggests consolidation onto one shared server (:3308 via
+# `bd dolt --global`) is warranted.
+#
+# Usage:  server-health.sh [--warn N]   (default warn threshold: 5 servers)
+# Requires: pgrep, /proc (Linux). Read-only — never kills anything.
+set -uo pipefail
+
+WARN=5
+[ "${1:-}" = "--warn" ] && { WARN="${2:-5}"; }
+
+mapfile -t PIDS < <(pgrep -f 'dolt sql-server' 2>/dev/null || true)
+n=0
+rows=""
+for p in "${PIDS[@]}"; do
+  [ -n "$p" ] || continue
+  port="$(tr '\0' ' ' < "/proc/$p/cmdline" 2>/dev/null | grep -oE '\-P [0-9]+' | grep -oE '[0-9]+' || true)"
+  [ -n "$port" ] || continue
+  cwd="$(readlink "/proc/$p/cwd" 2>/dev/null || echo '?')"
+  ws="$(echo "$cwd" | sed 's#'"$HOME"'/##; s#/.beads.*##')"
+  rows+="$(printf "%-8s %-8s %s" "$port" "$p" "$ws")"$'\n'
+  n=$((n+1))   # counted in the main shell, not a pipe subshell
+done
+printf "%-8s %-8s %s\n" "PORT" "PID" "WORKSPACE"
+[ -n "$rows" ] && printf '%s' "$rows" | sort -n
+
+echo
+echo "# $n running dolt sql-server process(es)."
+if [ "$n" -gt "$WARN" ]; then
+  echo "# ⚠ Sprawl: $n servers > threshold $WARN. Consolidate onto ONE shared server:"
+  echo "#     bd config set dolt.shared-server true   # machine-wide"
+  echo "#     bd dolt killall                          # per repo (refuses external/other-repo servers)"
+  echo "#   The next bd command auto-starts a single server at ~/.beads/shared-server/ on :3308."
+else
+  echo "# ✓ Server count within threshold ($WARN)."
+fi

package/scripts/sql_classifier.py

@@ -0,0 +1,259 @@
+"""sql_classifier.py — verb-class statement classifier (the mutation chokepoint).
+
+This is the heart of blueprint §3 / D4 blocker B1. Every SQL statement that the
+plugin runs through `dolt-mcp-client.py` is classified into one of three verb
+classes and gated *before* it reaches the dolt-mcp server:
+
+  read              SELECT / SHOW / DESCRIBE / EXPLAIN / dolt read table-funcs …
+                    -> executes freely.
+  safe-write        INSERT / UPDATE / DELETE / CREATE TABLE / CALL DOLT_COMMIT …
+                    -> executes ONLY on an agent-owned branch (never `main`) and
+                       ONLY with --allow-mutation; refused on pre-GA flavors.
+  history-affecting CALL DOLT_PUSH / DOLT_MERGE / DOLT_RESET('--hard') /
+                    branch-delete / DROP DATABASE / unknown CALL …
+                    -> ALWAYS refused (recommend-only; a human runs it).
+
+Why a *statement* classifier and not a tool allowlist: `query`/`exec` is a single
+MCP tool that carries every SQL verb, so excluding "history-affecting tools" from
+an agent grant does nothing — the dangerous verbs ride inside the one allowed
+tool. The gate therefore has to read the statement, not the tool name.
+
+Design bias is fail-safe: anything we cannot positively prove is a read is
+treated as at least safe-write, and any unrecognized `CALL …` (especially an
+unrecognized `CALL DOLT_*`) is treated as history-affecting. A multi-statement
+batch is classified at the severity of its most dangerous statement. Comments are
+stripped before classification so `/* */`-hidden or `--`-trailing verbs cannot
+slip a mutation past a read-looking prefix.
+
+Pure stdlib; importable (no side effects on import) so it can be unit-tested
+directly.
+"""
+import re
+
+READ = "read"
+SAFE_WRITE = "safe-write"
+HISTORY_AFFECTING = "history-affecting"
+
+# Severity ordering for batch (max-wins) classification.
+_SEVERITY = {READ: 0, SAFE_WRITE: 1, HISTORY_AFFECTING: 2}
+
+# Leading keywords that are unambiguously read-only.
+_READ_LEADERS = {
+    "SELECT", "SHOW", "DESCRIBE", "DESC", "EXPLAIN", "USE", "VALUES", "TABLE",
+    "HELP", "PREPARE", "EXECUTE", "DEALLOCATE",
+}
+# `SET` is session config (read-class for our purposes); `SET PASSWORD`/`SET GLOBAL`
+# are handled as exceptions below.
+_READ_SET_EXCEPTIONS = ("PASSWORD", "GLOBAL")
+
+# Leading keywords that mutate the working set / commit on a branch. Recoverable
+# through Dolt history as long as no history-affecting op runs, so: safe-write.
+_SAFE_WRITE_LEADERS = {
+    "INSERT", "UPDATE", "DELETE", "REPLACE", "MERGE", "TRUNCATE",
+    "CREATE", "ALTER", "RENAME", "ANALYZE", "LOAD", "IMPORT",
+}
+
+# Leading keywords that are destructive/admin and never safe from an agent.
+_HISTORY_LEADERS = {
+    "GRANT", "REVOKE", "FLUSH", "SHUTDOWN", "KILL", "RESET", "PURGE",
+    "LOCK", "UNLOCK", "INSTALL", "UNINSTALL", "BACKUP", "RESTORE",
+}
+
+# CALL DOLT_* procedure verb-classes. Anything not listed -> history-affecting.
+_DOLT_PROC_CLASS = {
+    "DOLT_COMMIT": SAFE_WRITE,
+    "DOLT_ADD": SAFE_WRITE,
+    "DOLT_CHECKOUT": SAFE_WRITE,   # incl. -b create; switches working set, non-destructive
+    "DOLT_BRANCH": SAFE_WRITE,     # create/list; delete is special-cased below
+    "DOLT_TAG": SAFE_WRITE,        # create; delete is special-cased below
+    "DOLT_FETCH": SAFE_WRITE,      # network read + remote-tracking refs; no local rewrite
+    "DOLT_REMOTE": SAFE_WRITE,     # add/list; remove is non-destructive to data
+    "DOLT_VERIFY_CONSTRAINTS": SAFE_WRITE,
+    # --- history-affecting (always recommend-only) ---
+    "DOLT_PUSH": HISTORY_AFFECTING,
+    "DOLT_PULL": HISTORY_AFFECTING,
+    "DOLT_MERGE": HISTORY_AFFECTING,
+    "DOLT_REVERT": HISTORY_AFFECTING,
+    "DOLT_CHERRY_PICK": HISTORY_AFFECTING,
+    "DOLT_REBASE": HISTORY_AFFECTING,
+    "DOLT_CLEAN": HISTORY_AFFECTING,   # discards uncommitted working changes
+    "DOLT_GC": HISTORY_AFFECTING,
+    "DOLT_PURGE_DROPPED_DATABASES": HISTORY_AFFECTING,
+    # DOLT_RESET handled specially (soft vs hard) below.
+}
+
+_LEADING_TOKEN = re.compile(r"[A-Za-z_][A-Za-z_0-9]*")
+_CALL_PROC = re.compile(r"^CALL\s+([A-Za-z_][A-Za-z_0-9]*)", re.IGNORECASE)
+# A complete quoted `-d` / `-D` / `--delete` flag arg inside a CALL DOLT_BRANCH /
+# DOLT_TAG list — matched as a whole quoted token so a branch literally named
+# e.g. '-delete-me' does not trip it.
+_DELETE_FLAG = re.compile(r"""['"]\s*--?(?:delete|d)\s*['"]""", re.IGNORECASE)
+_WRITE_VERB_ANYWHERE = re.compile(r"\b(INSERT|UPDATE|DELETE|REPLACE|MERGE)\b", re.IGNORECASE)
+
+
+def strip_sql_comments(sql):
+    """Remove `/* */`, `--`, and `#` comments so a verb hidden behind a comment
+    cannot mask the real leading verb — while preserving string literals, so a
+    `--`/`#` *inside* a quoted value (e.g. `DOLT_RESET('--hard')`) is NOT mistaken
+    for a comment. Quote-aware with backslash- and doubled-quote escapes."""
+    out = []
+    i, n, quote = 0, len(sql), None
+    while i < n:
+        ch = sql[i]
+        if quote:
+            out.append(ch)
+            if ch == "\\" and i + 1 < n:        # backslash escape inside a string
+                out.append(sql[i + 1]); i += 2; continue
+            if ch == quote:
+                if i + 1 < n and sql[i + 1] == quote:   # doubled-quote escape ('')
+                    out.append(sql[i + 1]); i += 2; continue
+                quote = None
+            i += 1
+            continue
+        if ch in ("'", '"', "`"):
+            quote = ch; out.append(ch); i += 1; continue
+        if ch == "/" and i + 1 < n and sql[i + 1] == "*":   # block comment
+            j = sql.find("*/", i + 2)
+            i = n if j == -1 else j + 2
+            out.append(" "); continue
+        if (ch == "-" and i + 1 < n and sql[i + 1] == "-") or ch == "#":   # line comment
+            j = sql.find("\n", i)
+            i = n if j == -1 else j
+            out.append(" "); continue
+        out.append(ch); i += 1
+    return "".join(out)
+
+
+def split_statements(sql):
+    """Naive `;` split (ignoring `;` inside quotes). Conservative: when in doubt a
+    fragment is classified, and the batch takes the max severity, so an over-split
+    never *lowers* the verdict."""
+    out, buf, quote = [], [], None
+    for ch in sql:
+        if quote:
+            buf.append(ch)
+            if ch == quote:
+                quote = None
+        elif ch in ("'", '"', "`"):
+            quote = ch
+            buf.append(ch)
+        elif ch == ";":
+            out.append("".join(buf))
+            buf = []
+        else:
+            buf.append(ch)
+    if buf:
+        out.append("".join(buf))
+    return [s for s in (frag.strip() for frag in out) if s]
+
+
+def _classify_call(stmt_upper):
+    m = _CALL_PROC.match(stmt_upper)
+    if not m:
+        return HISTORY_AFFECTING  # CALL with no resolvable proc name -> deny
+    proc = m.group(1).upper()
+    if proc == "DOLT_RESET":
+        return HISTORY_AFFECTING if "HARD" in stmt_upper else SAFE_WRITE
+    if proc in ("DOLT_BRANCH", "DOLT_TAG") and _DELETE_FLAG.search(stmt_upper):
+        return HISTORY_AFFECTING  # branch/tag deletion erases a ref
+    if proc.startswith("DOLT_"):
+        return _DOLT_PROC_CLASS.get(proc, HISTORY_AFFECTING)
+    # Non-dolt stored procedure: unknown effect -> deny from an agent context.
+    return HISTORY_AFFECTING
+
+
+def classify_statement(sql):
+    """Classify a single SQL statement into read / safe-write / history-affecting."""
+    stmt = strip_sql_comments(sql).strip().lstrip("(").strip()
+    if not stmt:
+        return READ
+    m = _LEADING_TOKEN.match(stmt)
+    if not m:
+        return SAFE_WRITE  # cannot identify a leading keyword -> not provably read
+    lead = m.group(0).upper()
+    stmt_upper = stmt.upper()
+
+    if lead == "CALL":
+        return _classify_call(stmt_upper)
+
+    if lead == "WITH":
+        # A CTE wraps either a read (SELECT) or a write (INSERT/UPDATE/DELETE/...).
+        return SAFE_WRITE if _WRITE_VERB_ANYWHERE.search(stmt) else READ
+
+    if lead == "SET":
+        return SAFE_WRITE if any(x in stmt_upper for x in _READ_SET_EXCEPTIONS) else READ
+
+    if lead == "DROP":
+        # DROP DATABASE/SCHEMA/USER rewrites/erases beyond version control; other
+        # DROPs (TABLE/VIEW/INDEX/TRIGGER) are recoverable via Dolt history.
+        if re.match(r"DROP\s+(DATABASE|SCHEMA|USER|ROLE)\b", stmt_upper):
+            return HISTORY_AFFECTING
+        return SAFE_WRITE
+
+    if lead == "CREATE":
+        if re.match(r"CREATE\s+(USER|ROLE)\b", stmt_upper):
+            return HISTORY_AFFECTING
+        return SAFE_WRITE
+
+    if lead in _READ_LEADERS:
+        return READ
+    if lead in _HISTORY_LEADERS:
+        return HISTORY_AFFECTING
+    if lead in _SAFE_WRITE_LEADERS:
+        return SAFE_WRITE
+
+    # Unknown leading keyword: not provably read -> require the mutation gate.
+    return SAFE_WRITE
+
+
+def classify_sql(sql):
+    """Classify a (possibly multi-statement) SQL string at its max severity."""
+    statements = split_statements(strip_sql_comments(sql))
+    if not statements:
+        return READ
+    worst = READ
+    for stmt in statements:
+        cls = classify_statement(stmt)
+        if _SEVERITY[cls] > _SEVERITY[worst]:
+            worst = cls
+    return worst
+
+
+def gate_decision(sql, allow_mutation, branch, maturity):
+    """Decide whether a SQL string may run, and why.
+
+    Returns (allowed: bool, verb_class: str, reason: str).
+
+    Rules (blueprint §3):
+      * history-affecting  -> always refused (recommend-only).
+      * pre-GA maturity (alpha/experimental) -> only `read` is allowed at all.
+      * safe-write         -> allowed only with allow_mutation AND a non-main,
+                              non-empty branch (agent/<task>).
+      * read               -> always allowed.
+    """
+    verb = classify_sql(sql)
+    maturity = (maturity or "ga").strip().lower()
+    pre_ga = maturity in ("alpha", "experimental")
+
+    if verb == HISTORY_AFFECTING:
+        return (False, verb,
+                "history-affecting statements are recommend-only — a human runs "
+                "merge/push/--force/reset --hard/branch-delete/DROP DATABASE, never "
+                "an agent. Surface the command for the operator instead of executing it.")
+
+    if verb == SAFE_WRITE:
+        if pre_ga:
+            return (False, verb,
+                    f"maturity '{maturity}' is pre-GA: this flavor is read-only until "
+                    "dolt-watch reports it has reached GA. No writes, even on a branch.")
+        if not allow_mutation:
+            return (False, verb,
+                    "safe-write requires --allow-mutation (the agent default is read-only).")
+        b = (branch or "").strip()
+        if not b or b.lower() == "main":
+            return (False, verb,
+                    "safe-write must target an agent-owned branch (--branch agent/<task>), "
+                    "never `main`.")
+        return (True, verb, f"safe-write permitted on branch '{b}'.")
+
+    return (True, verb, "read.")