task-pipeline-skill 1.96.0 → 1.98.0

package/plugins/task-pipeline/skills/task-pipeline/scripts/graph.py

@@ -35,6 +35,7 @@ conditional on the code, never merely sequenced after it):
     4  nothing runnable: an unclassified, running or parked dependency remains
     5  external execution lease contention
     6  nothing runnable: all remaining dependency leaves are recorded watched waits
+    7  `certify` stopped at its ceiling: the node is parked with the evidence
 
 **The mutation verbs never leave a half-written queue.** `add` and `park` write to a
 temp file in the same directory and `os.replace` it into place, so a crash mid-write
@@ -654,10 +655,25 @@ ALL_TIERS = TIERS + (VISUAL_TIER,)
 SURFACE_CLASSES = ("flagship", "product", "internal", "ad")
 RISK_CLASSES = ("R1", "R2", "R3")
 # Passing certification rounds a node owes before `close` accepts it, by risk class
-# (`references/certification.md` → *Rounds owed by risk class*). R3's must include one
-# round recorded `--kind adversarial`.
-ROUNDS_OWED = {"R1": 1, "R2": 2, "R3": 3}
+# (`references/certification.md` → *Rounds owed by risk class*). A clean round ends the
+# node unless it is R3 or a flagship surface: those owe a second passing round, and it is
+# the adversarial one, a different question rather than the same reading again. R2 owed
+# two blind rounds until 1.98.0, and a clean round did not cancel the next one: the loop
+# the 2026-10-20 cost audit measured.
+ROUNDS_OWED = {"R1": 1, "R2": 1, "R3": 2}
 ROUND_KINDS = ("blind", "adversarial")
+# An R1 node certifies with ONE blind tier (any of the three; `unit` is the default
+# reading). Every other node owes all three, and a flagship or product surface the fourth.
+ONE_TIER_RISK = ("R1",)
+
+
+def owed_rounds(node):
+    """(rounds owed, adversarial owed) for a node, or (0, False) when it owes no count."""
+    owed = ROUNDS_OWED.get(node.get("risk"), 0)
+    adversarial = node.get("risk") == "R3" or node.get("surface_class") == "flagship"
+    if node.get("surface_class") == "flagship":
+        owed = max(owed, 2)
+    return owed, adversarial
 
 
 def passing_rounds(cert):
@@ -675,13 +691,13 @@ def passing_rounds(cert):
 
 def owed_shortfall(node):
     """None when the node's class is satisfied, else a sentence saying what it still owes."""
-    owed = ROUNDS_OWED.get(node.get("risk"))
+    owed, adversarial = owed_rounds(node)
     if not owed:
         return None
     passed = passing_rounds(node.get("certification"))
     if len(passed) < owed:
         return "%d of %d owed passing rounds" % (len(passed), owed)
-    if node.get("risk") == "R3" and "adversarial" not in passed:
+    if adversarial and "adversarial" not in passed:
         cert = node.get("certification") or {}
         kinds = list(cert.get("kinds") or [])
         failed_adv = any(k == "adversarial" and not all(v == "pass" for v in (h or {}).values())
@@ -1661,10 +1677,14 @@ def cmd_certify(graph, args):
     the number the ceiling below reads. The node stays `pending` on a failure; the
     round count is the trail.
 
-    **The ceiling measures rather than stops** — `references/loop-guard.md`. At the
-    ceiling `certify` still runs and still tells the truth about the tiers; what it
-    adds is the name of the tier that keeps failing, because a run spinning on one
-    level needs the operator to see WHICH level, not to be halted.
+    **The ceiling stops** (`references/loop-guard.md`, since 1.98.0). A round that fails
+    with the node's failing rounds at the ceiling parks the node with the evidence as its
+    reason (exit 7): the run records a blocker row and moves on. It used to measure
+    only, and a measured loop is still a loop.
+
+    **No re-run on unchanged input.** A round of the same kind on the same tree as the
+    round before it is refused before anything is written: a tier's answer about a tree
+    it already read is the answer it gave.
     """
     guard(graph, args.graph)
 
@@ -1721,10 +1741,14 @@ def cmd_certify(graph, args):
         die("the tier reports are malformed — nothing was written:\n  " + "\n  ".join(bad))
 
     missing = [x for x in TIERS if x not in reports]
-    if missing:
+    if node.get("risk") in ONE_TIER_RISK:
+        if len(missing) == len(TIERS):
+            die("certification of an %s node needs one blind tier report (unit, seam or "
+                "product); none was given" % node.get("risk"))
+    elif missing:
         die("certification is missing the %s report(s) — all three are required, because "
-            "the level nobody read is the level the defect survives at"
-            % ", ".join("`%s`" % m for m in missing))
+            "the level nobody read is the level the defect survives at (an R1 node "
+            "certifies with one)" % ", ".join("`%s`" % m for m in missing))
     sclass = node.get("surface_class")
     if sclass in VISUAL_REQUIRED and VISUAL_TIER not in reports:
         die("certification is missing the `%s` report — %s is a %s surface, and on one the "
@@ -1743,6 +1767,18 @@ def cmd_certify(graph, args):
         head = ""
 
     prior = node.get("certification") or {}
+    try:
+        _t = subprocess.run(["git", "rev-parse", "HEAD^{tree}"], capture_output=True, text=True)
+        tree = _t.stdout.strip() if _t.returncode == 0 else ""
+    except OSError:
+        tree = ""
+    prior_kinds = list(prior.get("kinds") or [])
+    if (tree and prior.get("tree") == tree
+            and (prior_kinds[-1] if prior_kinds else "blind") == args.kind):
+        die("%s: round %d already read tree %s as a %s round: re-running a tier on "
+            "unchanged input repeats its answer. Change the code, run the other kind of round, "
+            "or record a blocker (references/loop-guard.md). Nothing was written."
+            % (nid, int(prior.get("round") or 0), tree[:12], args.kind))
     round_no = int(prior.get("round") or 0) + 1
     tiers_now = {x: reports[x]["verdict"] for x in tiers}
     history = list(prior.get("history") or []) + [tiers_now]
@@ -1754,6 +1790,8 @@ def cmd_certify(graph, args):
         "history": history,
         "kinds": kinds,
     }
+    if tree:
+        node["certification"]["tree"] = tree
 
     failed = [x for x in tiers if tiers_now[x] == "fail"]
 
@@ -1761,6 +1799,20 @@ def cmd_certify(graph, args):
     # operator needs named; counting it here is what makes the loop visible.
     churning = [x for x in tiers
                 if len(history) >= 2 and all(h.get(x) == "fail" for h in history)]
+    failed_rounds = sum(1 for h in history if any(v == "fail" for v in h.values()))
+    stop = bool(failed) and failed_rounds >= args.ceiling
+    if stop:
+        first = next((f for x in failed for f in reports[x]["findings"]
+                      if f.get("severity") == "breaks"), {})
+        reason = ("certification ceiling: %d failing round(s), ceiling %d; failing tier(s) %s; "
+                  "%s; first break %s: %s; check: %s. Blocker row owed on the board"
+                  % (failed_rounds, args.ceiling, ", ".join(failed),
+                     ("stuck on " + ", ".join(churning)) if churning else "churn across levels",
+                     first.get("where", "?"), first.get("what", "?"), first.get("check", "?")))
+        reason = " ".join(reason.split())
+        node["status"] = "parked"
+        node["parked_reason"] = reason
+        revise(graph, "park", nid, reason)
 
     save(args.graph, graph)
 
@@ -1774,9 +1826,10 @@ def cmd_certify(graph, args):
                 print("  [%s] %s — %s" % (tier, f["where"], f["what"]), file=sys.stderr)
                 print("      fix:   %s" % f.get("fix", "(not stated)"), file=sys.stderr)
                 print("      check: %s" % f["check"], file=sys.stderr)
-        if round_no >= args.ceiling:
-            print("\n%s has been certified %d time(s), at or over the ceiling of %d."
-                  % (nid, round_no, args.ceiling), file=sys.stderr)
+        if stop:
+            print("\n%s has failed %d round(s), at the ceiling of %d. STOPPED: the node is "
+                  "parked with this evidence as its reason; record a blocker row and move on."
+                  % (nid, failed_rounds, args.ceiling), file=sys.stderr)
             if churning:
                 print("The same tier has failed every round: %s. That is not a fix "
                       "away — the level itself is being misread, or the node is the "
@@ -1785,6 +1838,8 @@ def cmd_certify(graph, args):
             else:
                 print("No single tier is failing every round, so this is churn across "
                       "levels rather than one stuck level.", file=sys.stderr)
+        if stop:
+            return 7
         print("\nThe node stays open. Round %d is recorded on it." % round_no,
               file=sys.stderr)
         return 1
@@ -1843,7 +1898,7 @@ def cmd_certify(graph, args):
         fh.write("\n")
     os.replace(tmp, out)
     print("%s: certified at %s in round %d" % (nid, ", ".join(tiers), round_no))
-    owed = ROUNDS_OWED.get(node.get("risk"))
+    owed, _adv = owed_rounds(node)
     short = owed_shortfall(node)
     if short:
         print("round %d: %s — not closable yet. The next round reads the node's whole diff at "
@@ -1964,7 +2019,7 @@ def cmd_close(graph, args):
     if short and not exc:
         die("%s is %s: %s — not closable yet. Run the next round with `graph.py certify`, "
             "or record an authorized exception with `waive`. Nothing was written."
-            % (nid, node["risk"], short))
+            % (nid, node.get("risk") or "a %s surface" % node.get("surface_class"), short))
     if cert:
         tiers = cert.get("tiers") or {}
         failing = sorted(k for k, val in tiers.items() if val != "pass")
@@ -2073,8 +2128,8 @@ VERBS = {
     "wait": (cmd_wait, "record a watched external wait, without executing its locator"),
     "resume": (cmd_wait, "resolve the exact wait identity and return to pending"),
     "wave": (cmd_wave, "move a node to another wave, carrying the reason"),
-    "certify": (cmd_certify, "require three independent tier reports (four on a "
-                             "flagship or product surface), then emit the verdict "
+    "certify": (cmd_certify, "require three independent tier reports (one on an R1 node, "
+                             "four on a flagship or product surface), then emit the verdict "
                              "`close` consumes"),
     "close": (cmd_close, "consume a verdict, close one node and re-plan"),
 }
@@ -2128,8 +2183,9 @@ def main(argv=None):
                         help="the round's kind; R3 owes one `adversarial` round "
                              "(references/certification.md → *Rounds owed by risk class*)")
     p_cert.add_argument("--ceiling", type=int, default=3,
-                        help="rounds after which the output names the churning tier; it "
-                             "measures rather than stops (references/loop-guard.md)")
+                        help="failing rounds after which certify STOPS: the node is parked "
+                             "with the evidence and the run records a blocker row and moves "
+                             "on, exit 7 (references/loop-guard.md)")
 
     for verb in ("claim", "release", "recover", "complete"):
         made[verb].add_argument("--authority", required=True,

package/plugins/task-pipeline/skills/task-pipeline/scripts/retro_budget.py

@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+"""retro_budget.py: the byte budget of the retro's floor, measured and enforced.
+
+The floor is what stage 0 reads in full: the *Standing instructions* section and the
+*Run stamps* section of `<artifacts>/retro.md` (`references/retrospective.md` ->
+*The floor has a byte budget*). A cap of ten rows never bounded their SIZE: measured
+on 2026-10-20 across ~50 projects the floor ran from ~3k to ~76k tokens, one of them
+304 KB. This script is the bound.
+
+    retro_budget.py check   [--retro PATH] [--budget N] [--row N] [--stamp N]
+        prints one line: the floor's bytes, bytes/4 tokens, and the largest row of
+        each kind. Exit 0 within budget; 1 over budget (every offender listed);
+        2 could not measure (no file, or a floor section is missing).
+    retro_budget.py migrate [--retro PATH] [--archive PATH] [--write]
+        moves narrative out of the floor VERBATIM into the archive, each block
+        carrying the sha256 of the text it holds, and leaves a pointer in its place:
+        a stamp row over the stamp limit keeps Date, Topic and Commit; a standing row
+        over the row limit loses its `Because` cell. Without --write it prints the
+        plan and writes nothing. Exit 0 when the floor is then within budget, 1 when a
+        row is still over (an instruction too long to shorten by moving its story:
+        rewrite it by hand), 2 could not measure.
+    retro_budget.py verify  [--retro PATH]
+        every `sha256:` pointer in the floor resolves to an archive block whose text
+        hashes to it. Exit 0, or 1 naming each pointer that does not.
+
+Standard library only, like every script this skill ships.
+"""
+import argparse
+import datetime
+import hashlib
+import os
+import re
+import sys
+
+BUDGET = 12000  # bytes of floor (standing instructions + run stamps)
+ROW = 600       # chars per standing-instruction row
+STAMP = 300     # chars per run-stamp row
+CAP = 10        # rows per table, the existing cap
+
+STANDING = "## Standing instructions"
+STAMPS = "## Run stamps"
+POINTER = re.compile(r"(retro/[0-9]{4}-Q[1-4]\.md) sha256:([0-9a-f]{12,64})")
+
+
+class Unmeasurable(Exception):
+    pass
+
+
+def sections(text):
+    """{name: (start, end)} line spans of the two floor sections, end exclusive."""
+    lines = text.split("\n")
+    spans = {}
+    for i, line in enumerate(lines):
+        for name in (STANDING, STAMPS):
+            if line.startswith(name) and name not in spans:
+                j = i + 1
+                while j < len(lines) and not (lines[j].startswith("## ")
+                                              or lines[j].startswith("# ")):
+                    j += 1
+                spans[name] = (i, j)
+    missing = [n for n in (STANDING, STAMPS) if n not in spans]
+    if missing:
+        raise Unmeasurable("no `%s` section, so the floor cannot be measured"
+                           % "` or `".join(missing))
+    return lines, spans
+
+
+def table_rows(lines, span):
+    """Indices of the data rows of every table inside a span (header and rule skipped)."""
+    out = []
+    start, end = span
+    i = start
+    while i < end:
+        if lines[i].startswith("|") and i + 1 < end and re.match(r"^\|\s*:?-{3}", lines[i + 1]):
+            i += 2
+            while i < end and lines[i].startswith("|"):
+                out.append(i)
+                i += 1
+            continue
+        i += 1
+    return out
+
+
+def cells(row):
+    parts = row.strip().split("|")
+    return [c.strip() for c in parts[1:-1]]
+
+
+def header_cols(lines, i):
+    """Column count of the table holding row i, read from its header (a `|` inside a
+    cell's text must not widen the row that replaces it)."""
+    k = i
+    while k > 0 and lines[k - 1].startswith("|"):
+        k -= 1
+    return len(cells(lines[k]))
+
+
+def measure(text, budget=BUDGET, row=ROW, stamp=STAMP):
+    lines, spans = sections(text)
+    floor = "\n".join(lines[spans[STANDING][0]:spans[STANDING][1]]) + "\n" + \
+            "\n".join(lines[spans[STAMPS][0]:spans[STAMPS][1]])
+    nbytes = len(floor.encode("utf-8"))
+    std = table_rows(lines, spans[STANDING])
+    stm = table_rows(lines, spans[STAMPS])
+    over = []
+    if nbytes > budget:
+        over.append("floor is %d bytes, over the budget of %d" % (nbytes, budget))
+    for i in std:
+        if len(lines[i]) > row:
+            over.append("standing row %s is %d chars, over %d"
+                        % ((cells(lines[i]) or ["?"])[0], len(lines[i]), row))
+    for i in stm:
+        if len(lines[i]) > stamp:
+            c = cells(lines[i])
+            over.append("stamp %s %s is %d chars, over %d"
+                        % (c[0] if c else "?", c[2] if len(c) > 2 else "", len(lines[i]), stamp))
+    if len(std) > CAP:
+        over.append("%d standing rows, over the cap of %d" % (len(std), CAP))
+    if len(stm) > CAP:
+        over.append("%d run stamps, over the cap of %d" % (len(stm), CAP))
+    return {
+        "bytes": nbytes, "tokens": nbytes // 4, "budget": budget,
+        "standing": len(std), "standing_max": max([len(lines[i]) for i in std] or [0]),
+        "stamps": len(stm), "stamps_max": max([len(lines[i]) for i in stm] or [0]),
+        "over": over, "lines": lines, "spans": spans, "std": std, "stm": stm,
+    }
+
+
+def summary(m, row=ROW, stamp=STAMP):
+    return ("retro floor: %d bytes · ~%d tokens (bytes/4) · budget %d · standing %d/%d rows, "
+            "largest %d/%d · stamps %d/%d, largest %d/%d"
+            % (m["bytes"], m["tokens"], m["budget"], m["standing"], CAP, m["standing_max"], row,
+               m["stamps"], CAP, m["stamps_max"], stamp))
+
+
+def read(path):
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return fh.read()
+    except OSError as exc:
+        raise Unmeasurable("cannot read %s (%s)" % (path, exc.strerror or exc))
+
+
+def default_archive(retro):
+    today = datetime.date.today()
+    q = (today.month - 1) // 3 + 1
+    return os.path.join(os.path.dirname(os.path.abspath(retro)), "retro",
+                        "%d-Q%d.md" % (today.year, q))
+
+
+def digest(text):
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def block(kind, label, text):
+    h = digest(text)
+    return h, ("\n### retro_budget migrate · %s · %s · %s\n\n<!-- sha256:%s -->\n%s\n"
+               % (datetime.date.today().isoformat(), kind, label, h, text))
+
+
+def cmd_check(a):
+    m = measure(read(a.retro), a.budget, a.row, a.stamp)
+    print(summary(m, a.row, a.stamp))
+    if m["over"]:
+        for o in m["over"]:
+            print("  over: " + o)
+        print("  remedy: retro_budget.py migrate --write moves the narrative to the archive "
+              "verbatim; an instruction still over the row limit is rewritten by hand")
+        return 1
+    return 0
+
+
+def cmd_migrate(a):
+    text = read(a.retro)
+    m = measure(text, a.budget, a.row, a.stamp)
+    lines = m["lines"]
+    archive = a.archive or default_archive(a.retro)
+    rel = os.path.relpath(os.path.abspath(archive),
+                          os.path.dirname(os.path.abspath(a.retro))).replace(os.sep, "/")
+    moved = []
+    for i in m["stm"]:
+        if len(lines[i]) <= a.stamp:
+            continue
+        c = cells(lines[i])
+        if len(c) < 3:
+            continue
+        h, b = block("stamp", "%s %s" % (c[0], c[2]), lines[i])
+        ptr = "moved: %s sha256:%s" % (rel, h[:12])
+        # the table keeps its column count: the pointer fills Verdict, `·` the rest
+        tail = ["·"] * max(0, header_cols(lines, i) - 4)
+
+        def row_of(topic):
+            return "| " + " | ".join([c[0], topic, c[2], ptr] + tail) + " |"
+
+        topic = c[1]
+        new = row_of(topic)
+        if len(new) > a.stamp:
+            keep = max(8, len(topic) - (len(new) - a.stamp) - 1)
+            new = row_of(topic[:keep].rstrip() + "…")
+        moved.append((i, new, b, "stamp %s %s" % (c[0], c[2])))
+    for i in m["std"]:
+        if len(lines[i]) <= a.row:
+            continue
+        c = cells(lines[i])
+        if len(c) < 5:
+            continue
+        h, b = block("standing", c[0], c[4])
+        c[4] = "story: %s sha256:%s" % (rel, h[:12])
+        moved.append((i, "| " + " | ".join(c) + " |", b, "standing %s Because" % c[0]))
+    if not moved:
+        print(summary(m, a.row, a.stamp))
+        print("migrate: nothing to move")
+        return 1 if m["over"] else 0
+    for i, new, _, label in moved:
+        print("migrate: %s -> %s (%d -> %d chars)" % (label, rel, len(lines[i]), len(new)))
+    if not a.write:
+        print("migrate: dry run, nothing written (pass --write)")
+        return 0
+    os.makedirs(os.path.dirname(os.path.abspath(archive)), exist_ok=True)
+    if not os.path.exists(archive):
+        with open(archive, "w", encoding="utf-8") as fh:
+            fh.write("# Retro archive · %s\n\n**Append-only. Queried, never read in full.** "
+                     "Blocks moved here by `retro_budget.py migrate` carry the sha256 of the "
+                     "text they hold; the floor keeps a pointer to it.\n"
+                     % os.path.basename(archive)[:-3])
+    with open(archive, "a", encoding="utf-8") as fh:
+        for _, _, b, _ in moved:
+            fh.write(b)
+    for i, new, _, _ in moved:
+        lines[i] = new
+    tmp = a.retro + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as fh:
+        fh.write("\n".join(lines))
+    os.replace(tmp, a.retro)
+    after = measure(read(a.retro), a.budget, a.row, a.stamp)
+    print(summary(after, a.row, a.stamp))
+    bad = verify(a.retro)
+    if bad:
+        for b in bad:
+            print("  unproved: " + b)
+        return 1
+    for o in after["over"]:
+        print("  still over: " + o)
+    return 1 if after["over"] else 0
+
+
+def verify(retro):
+    text = read(retro)
+    lines, spans = sections(text)
+    floor = "\n".join(lines[spans[STANDING][0]:spans[STANDING][1]] +
+                      lines[spans[STAMPS][0]:spans[STAMPS][1]])
+    base = os.path.dirname(os.path.abspath(retro))
+    bad, cache = [], {}
+    for rel, short in POINTER.findall(floor):
+        path = os.path.join(base, rel)
+        if path not in cache:
+            try:
+                cache[path] = read(path)
+            except Unmeasurable:
+                cache[path] = None
+        arch = cache[path]
+        if arch is None:
+            bad.append("sha256:%s points at %s, which does not exist" % (short, rel))
+            continue
+        ok = False
+        for m in re.finditer(r"<!-- sha256:([0-9a-f]{64}) -->\n(.*?)\n(?=\n#{2,3} |\Z)", arch, re.S):
+            if m.group(1).startswith(short) and digest(m.group(2)) == m.group(1):
+                ok = True
+                break
+        if not ok:
+            bad.append("sha256:%s has no block in %s whose text hashes to it" % (short, rel))
+    return bad
+
+
+def cmd_verify(a):
+    bad = verify(a.retro)
+    for b in bad:
+        print("unproved: " + b)
+    if not bad:
+        print("verify: every archive pointer in the floor resolves and its hash matches")
+    return 1 if bad else 0
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    sub = p.add_subparsers(dest="cmd", required=True)
+    for name in ("check", "migrate", "verify"):
+        s = sub.add_parser(name)
+        s.add_argument("--retro", default="docs/evidence/retro.md")
+        s.add_argument("--budget", type=int, default=BUDGET)
+        s.add_argument("--row", type=int, default=ROW)
+        s.add_argument("--stamp", type=int, default=STAMP)
+        if name == "migrate":
+            s.add_argument("--archive")
+            s.add_argument("--write", action="store_true")
+    a = p.parse_args(argv)
+    try:
+        return {"check": cmd_check, "migrate": cmd_migrate, "verify": cmd_verify}[a.cmd](a)
+    except Unmeasurable as exc:
+        print("retro_budget: could not measure: %s" % exc, file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/plugins/task-pipeline/skills/task-pipeline/scripts/short_path.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""short_path.py: stage 0's proportional decision, computed rather than proposed.
+
+`references/stage-00-intake.md` -> Phase 1d. Until 1.98.0 the short path was only
+*proposed*, and silence took the full flow; under a standing "decide and act"
+instruction silence is the normal answer, so a small fix met eleven stages every time.
+This script takes the five triage answers and DECIDES, printing the one line the run
+shows the operator.
+
+    short_path.py --files PATH [PATH ...] --contract yes|no --user-facing yes|no
+                  --deploy yes|no --risk R1|R2|R3 [--unknowns N]
+
+Exit 0: the short path (brief in the run ledger, build with tests, one verification,
+docs and handoff). Exit 3: the full flow, with every answer that ruled the short path
+out. Exit 2: usage. Standard library only.
+"""
+import argparse
+import sys
+
+MAX_FILES = 5
+SMALL_RISK = "R1"
+
+
+def decide(files, contract, user_facing, deploy, risk, unknowns=0):
+    """(short?, line) for the five answers plus the gap check's unknowns."""
+    n = len(set(files))
+    why = []
+    if unknowns:
+        why.append("%d material unknown(s) left by the gap check" % unknowns)
+    if n > MAX_FILES:
+        why.append("%d files, over %d" % (n, MAX_FILES))
+    if n == 0:
+        why.append("no file named, so the change is not bounded")
+    if contract:
+        why.append("a public contract is touched")
+    if user_facing:
+        why.append("a user-observable change")
+    if deploy:
+        why.append("a deploy target")
+    if risk != SMALL_RISK:
+        why.append("risk %s" % risk)
+    if why:
+        return False, "full flow: " + "; ".join(why)
+    return True, ("short path: %s · %d file%s · no contract · no user-facing change · "
+                  "no deploy" % (risk, n, "" if n == 1 else "s"))
+
+
+def yes_no(v):
+    v = v.strip().lower()
+    if v not in ("yes", "no"):
+        raise argparse.ArgumentTypeError("answer yes or no, not %r" % v)
+    return v == "yes"
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    p.add_argument("--files", nargs="*", default=[], help="the paths the change touches")
+    p.add_argument("--contract", type=yes_no, required=True)
+    p.add_argument("--user-facing", type=yes_no, required=True)
+    p.add_argument("--deploy", type=yes_no, required=True)
+    p.add_argument("--risk", choices=("R1", "R2", "R3"), required=True)
+    p.add_argument("--unknowns", type=int, default=0)
+    a = p.parse_args(argv)
+    short, line = decide(a.files, a.contract, a.user_facing, a.deploy, a.risk, a.unknowns)
+    print(line)
+    return 0 if short else 3
+
+
+if __name__ == "__main__":
+    sys.exit(main())