formwork-kit 0.1.0__py3-none-any.whl

formwork_cli/kit/build

@@ -0,0 +1,410 @@
+#!/usr/bin/env python3
+"""Generate each runtime's role files from one source.
+
+    formwork roles                 write files for the runtime in .formwork.toml
+    formwork roles --all           write files for every runtime
+    formwork roles --runtime codex just that one
+    formwork roles --check         regenerate in memory and compare. Change nothing
+
+Exit status:
+    0   done, or --check found everything current
+    1   --check found a generated file that is stale or hand-edited
+    2   could not run
+
+WHY GENERATE AT ALL
+-------------------
+Four runtimes want role definitions in four shapes. Keeping four hand-written
+copies of twenty-seven roles is the duplication that drifts — one gets updated
+and the others quietly do not, and nothing announces it.
+
+One source, generated outward, with a check that regeneration produces
+identical bytes. A hand-edit to a generated file then fails the gate instead of
+surviving.
+
+WHAT EACH RUNTIME GETS, AND WHY CURSOR GETS NOTHING
+---------------------------------------------------
+    claude-code   .claude/agents/<name>.md      markdown, tools by name
+    gemini-cli    .gemini/agents/<name>.md      markdown, tools by name
+    codex         .codex/agents/<name>.toml     TOML, no tool list at all
+    cursor        nothing is written
+
+Cursor's own documentation names `.claude/agents/` as a location it reads. So
+the Claude Code output serves it directly, and generating a second identical
+tree would be duplication for its own sake.
+
+THE TOOL GRANT DOES NOT SURVIVE EVERY TRANSLATION
+-------------------------------------------------
+Claude Code and Gemini CLI take a named list and enforce it. Cursor has one
+boolean. Codex has a sandbox mode, which is not a tool list.
+
+This generator writes the grant where it can be expressed and **says in the
+generated file where it cannot**, rather than emitting something that looks
+like a restriction and is not. That was decided deliberately; the two rejected
+alternatives are recorded in docs/role-formats.md.
+
+Python 3, standard library only, no dependencies.
+"""
+import os
+import re
+import sys
+
+CLEAN, STALE, CANNOT_RUN = 0, 1, 2
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.dirname(HERE)
+ROLES = os.path.join(HERE, "roles")
+
+BANNER = ("GENERATED FROM %s — DO NOT EDIT.\n"
+          "Change the source and run formwork roles. A hand-edit here fails "
+          "the gate.")
+
+# The kit's five abstract grants, mapped to what each runtime actually calls
+# them. None means the name is not established, and the generator will not
+# invent one.
+TOOL_NAMES = {
+    "claude-code": {
+        "read":  ["Read", "Glob", "Grep"],
+        "write": ["Write", "Edit"],
+        "run":   ["Bash"],
+        "web":   ["WebFetch", "WebSearch"],
+        "spawn": ["Task"],
+    },
+    "gemini-cli": {
+        "read":  ["read_file", "grep_search"],
+        "run":   ["run_shell_command"],
+        # Established from the publisher's own example. The name of the
+        # file-writing tool is NOT among the documented examples, and guessing
+        # it would produce an allowlist that silently omits a tool the role
+        # needs. See docs/role-formats.md.
+        "write": None,
+        "web":   None,
+        "spawn": None,
+    },
+}
+
+# Runtimes that can hold a role to its grant at all.
+ENFORCES = {"claude-code", "gemini-cli"}
+
+TARGETS = {
+    "claude-code": (os.path.join(".claude", "agents"), ".md"),
+    "gemini-cli":  (os.path.join(".gemini", "agents"), ".md"),
+    "codex":       (os.path.join(".codex", "agents"), ".toml"),
+}
+ALL_RUNTIMES = tuple(sorted(TARGETS)) + ("cursor",)
+
+
+def read_roles():
+    out = []
+    for sub in ("method", "packs", "project"):
+        d = os.path.join(ROLES, sub)
+        if not os.path.isdir(d):
+            continue
+        for fn in sorted(os.listdir(d)):
+            if not fn.endswith(".md") or fn.upper().startswith(("TEMPLATE",
+                                                                "HOW-TO",
+                                                                "README")):
+                continue
+            out.append(os.path.join(d, fn))
+    return out
+
+
+def parse(path):
+    text = open(path, encoding="utf-8").read()
+    m = re.match(r"^---\n(.*?)\n---\n(.*)$", text, re.S)
+    if not m:
+        return None
+    meta = {}
+    for line in m.group(1).split("\n"):
+        if ":" in line:
+            k, v = line.split(":", 1)
+            meta[k.strip()] = v.strip()
+    body = m.group(2).lstrip("\n")
+    # Accept both `tools: ["read", "write"]` and `tools: [read, write]`.
+    # Reading only the quoted form meant an unquoted list parsed as NO grants,
+    # which emitted frontmatter with no tools key at all — and in Claude Code
+    # that grants every tool. The safest-looking role got the widest grant.
+    raw = meta.get("tools", "")
+    tools = re.findall(r'"([a-z]+)"', raw) or re.findall(r"\b([a-z]+)\b", raw)
+    owns = re.search(r"^\*\*Owns\.\*\*\s*(.+?)(?:\n\n|\Z)", body, re.S | re.M)
+    description = " ".join(owns.group(1).split()) if owns else meta.get("name", "")
+    if len(description) > 300:
+        description = description[:297].rsplit(" ", 1)[0] + "…"
+    return {"name": meta.get("name", ""), "pack": meta.get("pack", ""),
+            "owns": meta.get("owns", ""), "tools": tools,
+            "description": description, "body": body,
+            "source": os.path.relpath(path, ROOT)}
+
+
+def resolve_tools(runtime, grants):
+    """(names, unmapped). names is None when the list cannot be completed."""
+    table = TOOL_NAMES.get(runtime)
+    if table is None:
+        return None, list(grants)
+    names, unmapped = [], []
+    for g in grants:
+        got = table.get(g)
+        if got is None:
+            unmapped.append(g)
+        else:
+            names.extend(got)
+    if unmapped:
+        return None, unmapped
+    return names, []
+
+
+def render_markdown(role, runtime):
+    names, unmapped = resolve_tools(runtime, role["tools"])
+    if not role["tools"]:
+        # No grant could be read at all. Emitting frontmatter without a tools
+        # key means "every tool" on some runtimes, so say so instead.
+        unmapped = ["(the grant could not be read from the source)"]
+    lines = ["---", "name: %s" % role["name"],
+             "description: %s" % role["description"]]
+    if runtime == "gemini-cli":
+        lines.append("kind: local")
+    if names:
+        if runtime == "claude-code":
+            lines.append("tools: %s" % ", ".join(names))
+        else:
+            lines.append("tools:")
+            lines += ["  - %s" % n for n in names]
+    lines.append("---")
+    lines.append("")
+    for line in (BANNER % role["source"]).split("\n"):
+        lines.append("<!-- %s -->" % line)
+    lines.append("")
+    if unmapped:
+        lines.append("> **This role's tool grant is not expressed here.** It "
+                     "asks for %s, and %s does not have a documented name for "
+                     "%s. An incomplete allowlist would quietly remove a tool "
+                     "the role needs, so none is written. The grant is advice "
+                     "on this runtime."
+                     % (", ".join("`%s`" % t for t in role["tools"]),
+                        runtime, " and ".join("`%s`" % u for u in unmapped)))
+        lines.append("")
+    lines.append(role["body"].rstrip())
+    lines.append("")
+    return "\n".join(lines)
+
+
+def toml_escape(s):
+    return s.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def render_toml(role):
+    banner = (BANNER % role["source"]).split("\n")
+    out = ["# %s" % b for b in banner]
+    out.append("")
+    out.append('name = "%s"' % toml_escape(role["name"]))
+    out.append('description = "%s"' % toml_escape(role["description"]))
+    out.append("")
+    out.append("# This runtime has a sandbox mode rather than a tool list, so")
+    out.append("# the grant %s is not expressed here. It is advice on Codex."
+               % ", ".join(role["tools"]))
+    out.append("")
+    out.append('developer_instructions = """')
+    out.append(role["body"].rstrip().replace('"""', '\\"\\"\\"'))
+    out.append('"""')
+    out.append("")
+    return "\n".join(out)
+
+
+def existing_targets():
+    """Runtimes whose generated tree is already present in this project.
+
+    A fork that uses one runtime should not be made to generate files for
+    three. But a tree that exists must stay current, or a stale agent
+    definition survives unnoticed — which is the whole reason this generator
+    exists.
+    """
+    out = []
+    for runtime, (folder, _ext) in sorted(TARGETS.items()):
+        if os.path.isdir(os.path.join(ROOT, folder)):
+            out.append(runtime)
+    return out
+
+
+def orphans(files, runtimes):
+    """Generated files with no source, in the trees we generate into.
+
+    An agent definition added by hand, or one left behind after its source was
+    deleted, used to pass unnoticed: --check only compared files the source
+    produces. A hand-written agent with every tool granted is exactly what
+    this kit exists to prevent.
+    """
+    expected = set(files)
+    found = []
+    for runtime in runtimes:
+        if runtime == "cursor":
+            continue
+        folder, ext = TARGETS[runtime]
+        d = os.path.join(ROOT, folder)
+        if not os.path.isdir(d):
+            continue
+        for fn in sorted(os.listdir(d)):
+            if not fn.endswith(ext):
+                continue
+            rel = os.path.join(folder, fn)
+            if rel not in expected:
+                found.append(rel)
+    return found
+
+
+SAFE_NAME = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
+
+
+def unsafe_names(roles):
+    """Role names that are not safe to put in a path, with the reason.
+
+    `name:` was joined into a file path with no checking at all. A role
+    claiming `name: /tmp/anything` or `name: ../../../elsewhere` made the
+    generator write outside the project, and the gate stayed green. Somebody
+    cloning a repository that ships a kit would have run one documented
+    command and had files written wherever they can write.
+    """
+    bad = []
+    seen = {}
+    for r in roles:
+        n = r["name"]
+        if not SAFE_NAME.match(n):
+            bad.append("%s declares name: %r. A name must be lower case "
+                       "letters, digits and hyphens, and nothing else."
+                       % (r["source"], n))
+        elif n in seen:
+            # Two roles with one name silently collapsed into one file, and
+            # both the shipped role and one of the pair disappeared.
+            bad.append("%s and %s both declare name: %s. Names must be unique."
+                       % (seen[n], r["source"], n))
+        else:
+            seen[n] = r["source"]
+    return bad
+
+
+def outputs(runtimes):
+    """{path: contents} for every runtime asked for."""
+    files = {}
+    roles = [parse(p) for p in read_roles()]
+    roles = [r for r in roles if r and r["name"]]
+    if not roles:
+        return None
+    bad = unsafe_names(roles)
+    if bad:
+        raise ValueError("\n".join(bad))
+    for runtime in runtimes:
+        if runtime == "cursor":
+            continue                       # reads .claude/agents/ directly
+        folder, ext = TARGETS[runtime]
+        for role in roles:
+            rel = os.path.join(folder, role["name"] + ext)
+            if ext == ".toml":
+                files[rel] = render_toml(role)
+            else:
+                files[rel] = render_markdown(role, runtime)
+    return files
+
+
+def configured_runtime():
+    config = os.path.join(ROOT, ".formwork.toml")
+    if os.path.exists(config):
+        text = open(config, encoding="utf-8", errors="ignore").read()
+        m = re.search(r'^\s*runtime\s*=\s*["\']([^"\']+)["\']', text, re.M)
+        if m and m.group(1) in ALL_RUNTIMES:
+            return m.group(1)
+    return "claude-code"
+
+
+def main(argv):
+    check_only = "--check" in argv
+    if "--all" in argv:
+        runtimes = [r for r in ALL_RUNTIMES if r != "cursor"]
+    elif check_only and "--runtime" not in argv:
+        # Check the configured runtime, plus any tree already present. A fork
+        # using one runtime is not made to generate files for three, and a
+        # tree that does exist is still held to being current.
+        runtimes = sorted(set([configured_runtime()] + existing_targets())
+                          - {"cursor"})
+        if not runtimes:
+            runtimes = ["claude-code"]
+    elif "--runtime" in argv:
+        i = argv.index("--runtime")
+        if i + 1 >= len(argv) or argv[i + 1] not in ALL_RUNTIMES:
+            print("ERROR: --runtime needs one of: %s" % ", ".join(ALL_RUNTIMES),
+                  file=sys.stderr)
+            return CANNOT_RUN
+        runtimes = [argv[i + 1]]
+    else:
+        if not os.path.exists(os.path.join(ROOT, ".formwork.toml")) \
+                and not check_only:
+            print("ERROR: this project has no .formwork.toml, so there is no "
+                  "runtime to generate for.", file=sys.stderr)
+            print("       Run the installer first, or say which: "
+                  "--runtime claude-code", file=sys.stderr)
+            return CANNOT_RUN
+        runtimes = [configured_runtime()]
+
+    if runtimes == ["cursor"]:
+        print("cursor reads .claude/agents/, so nothing is generated for it")
+        runtimes = ["claude-code"]
+
+    try:
+        files = outputs(runtimes)
+    except ValueError as e:
+        print("ERROR: %d role name(s) cannot be used:" % len(str(e).split("\n")),
+              file=sys.stderr)
+        for line in str(e).split("\n"):
+            print("  %s" % line, file=sys.stderr)
+        return CANNOT_RUN
+    if files is None:
+        print("ERROR: no roles found under %s" % ROLES, file=sys.stderr)
+        return CANNOT_RUN
+
+    if check_only:
+        stale = ["%s — generated, but nothing in formwork/roles/ produces it"
+                 % o for o in orphans(files, runtimes)]
+        for rel, content in sorted(files.items()):
+            full = os.path.join(ROOT, rel)
+            if not os.path.exists(full):
+                stale.append("%s — missing" % rel)
+            elif open(full, encoding="utf-8").read() != content:
+                stale.append("%s — differs from what the source produces" % rel)
+        if stale:
+            print("%d generated file(s) are not current:" % len(stale))
+            for s in stale:
+                print("  %s" % s)
+            print("  Run formwork roles. If you edited one by hand, that edit "
+                  "is about to be lost — move it to the source first.")
+            return STALE
+        print("%d generated file(s), all current" % len(files))
+        return CLEAN
+
+    written = 0
+    kept = []
+    for rel, content in sorted(files.items()):
+        full = os.path.join(ROOT, rel)
+        os.makedirs(os.path.dirname(full), exist_ok=True)
+        existing = None
+        if os.path.exists(full):
+            existing = open(full, encoding="utf-8").read()
+        # Somebody else's agent file, with the same name as one of ours.
+        # Overwriting it destroyed hand-written work with no backup and no
+        # message, in a program whose own promise is that it never deletes.
+        if existing is not None and BANNER.split(" ")[0] not in existing:
+            kept.append(rel)
+            continue
+        if existing != content:
+            open(full, "w", encoding="utf-8").write(content)
+            written += 1
+    if kept:
+        print("NOT WRITTEN, because these already exist and this kit did not "
+              "make them:")
+        for rel in kept:
+            print("  %s" % rel)
+        print("  Your file is untouched. Rename yours, or rename the role in "
+              "formwork/roles/, then run this again.")
+    print("%d role file(s) considered, %d written, for: %s"
+          % (len(files), written, ", ".join(runtimes)))
+    return CLEAN
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

formwork_cli/kit/check/checks/config-shape

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Check: the configuration file is the shape the documents describe.
+
+    config-shape <directory>
+
+CATCHES  Documentation drifting from the file it documents. Three documents
+         once described this configuration three different ways, and following
+         one of them would have moved a key where the guard could not find it.
+         Everything read correctly and the tool quietly stopped working.
+
+Two things are checked:
+
+  1. the layers are separate — [bindings] and [strength] exist, and [rules]
+     does not, because rules are not switched off in configuration
+  2. every section the kit's own instructions show in an example is a section
+     the real file actually has
+
+Only the kit's instructions are held to this — FORMWORK.md and everything
+under formwork/. A design document is allowed to describe something not built
+yet; an instruction telling somebody to write a section that nothing reads is
+a different thing, and that is what this catches.
+
+Exit status:
+    0   the file matches what is documented, or there is no file to check
+    1   they disagree, and the disagreement is named
+    2   the check could not run
+"""
+import os
+import re
+import sys
+
+CONFIG = ".formwork.toml"
+REQUIRED = ("bindings", "strength")
+FORBIDDEN = ("rules",)
+SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv"}
+SECTION = re.compile(r"^\s*\[([a-z_]+)\]", re.M)
+# Paths the runner has told this check to stay out of. The kit's own fixtures
+# are wrong on purpose.
+EXCLUDED = [os.path.abspath(p) for p in
+            os.environ.get("FORMWORK_EXCLUDE", "").split(os.pathsep) if p]
+
+
+def excluded(path):
+    a = os.path.abspath(path)
+    return any(a == e or a.startswith(e + os.sep) for e in EXCLUDED)
+# A toml block in a document that is clearly about this configuration.
+TOML_BLOCK = re.compile(r"```toml\n(.*?)```", re.S)
+
+
+def sections(text):
+    return set(SECTION.findall(text))
+
+
+def main(argv):
+    if len(argv) < 2:
+        print("usage: config-shape <directory>", file=sys.stderr)
+        return 2
+    root = argv[1]
+    if not os.path.isdir(root):
+        print("ERROR: not a directory: %s" % root, file=sys.stderr)
+        return 2
+
+    path = os.path.join(root, CONFIG)
+    if not os.path.exists(path):
+        print("no %s, nothing claimed" % CONFIG)
+        return 0
+    try:
+        real = open(path, encoding="utf-8", errors="strict").read()
+    except (UnicodeDecodeError, OSError) as e:
+        print("ERROR: cannot read %s: %s" % (CONFIG, e), file=sys.stderr)
+        return 2
+
+    have = sections(real)
+    problems = []
+    for s in REQUIRED:
+        if s not in have:
+            problems.append("%s has no [%s] section" % (CONFIG, s))
+    for s in FORBIDDEN:
+        if s in have:
+            problems.append("%s has a [%s] section. Rules are not switched off "
+                            "in configuration" % (CONFIG, s))
+
+    # Only the kit's own instructions. Planning documents may describe intent.
+    instruction_roots = [os.path.join(root, "formwork")]
+    front = os.path.join(root, "FORMWORK.md")
+    targets = [front] if os.path.exists(front) else []
+    for base in instruction_roots:
+        for dp, dn, fns in os.walk(base):
+            dn[:] = [d for d in dn if d not in SKIP_DIRS]
+            if excluded(dp):
+                dn[:] = []
+                continue
+            targets += [os.path.join(dp, f) for f in fns if f.endswith(".md")]
+
+    for full in targets:
+        if True:
+            try:
+                text = open(full, encoding="utf-8", errors="ignore").read()
+            except OSError:
+                continue
+            for block in TOML_BLOCK.findall(text):
+                shown = sections(block)
+                if not shown & set(REQUIRED) and not shown & {"roles"}:
+                    continue          # some other toml, not this file
+                for s in sorted(shown - have):
+                    problems.append("%s shows a [%s] section that %s does not "
+                                    "have" % (os.path.relpath(full, root), s,
+                                              CONFIG))
+
+    if problems:
+        print("%d disagreement(s) between the configuration and the documents"
+              % len(problems))
+        for p in sorted(set(problems)):
+            print("  %s" % p)
+        return 1
+
+    print("%s has %s, and every documented example matches it"
+          % (CONFIG, ", ".join("[%s]" % s for s in REQUIRED)))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

formwork_cli/kit/check/checks/decision-ids

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Check: decision numbers come from the record, and none was guessed.
+
+    decision-ids <directory>
+    decision-ids --next <directory>    print the number a new decision takes
+
+CATCHES  Two decisions sharing a number, because two threads were each reading
+         a different stale state and both were confident. And a placeholder
+         that shipped — a decision carrying a number nobody ever assigned, which
+         everything downstream then cites.
+
+         Also a superseding decision pointing at one that does not exist, which
+         is how a cross-reference breaks silently.
+
+What it does not do is watch how a number was chosen. Nothing can. It checks
+that the result is consistent, which catches the failure without pretending to
+police the act.
+
+Exit status:
+    0   the numbering holds
+    1   it does not, and the problem is named
+    2   the check could not run
+"""
+import os
+import re
+import sys
+
+DECISIONS = os.path.join("docs", "decisions")
+NAMED = re.compile(r"^(\d{1,6})[-_]")
+# Two kinds of placeholder, and they need different rules.
+#
+# These are never English. Anywhere they appear, they are a placeholder.
+OBVIOUS_PLACEHOLDER = re.compile(
+    r"\b(DEC-PENDING|TBD|XXXX+|NNNN+|\?\?\?\?)\b")
+
+# These are ordinary words. They only mean "unfilled" when they stand where an
+# answer should be — alone, or right after a label. "The migration is pending
+# review by the team" and "a TODO list was kept" are things a decision record
+# is entitled to say, and both used to fail the gate with a message accusing
+# the author of shipping a placeholder.
+WORDY_PLACEHOLDER = re.compile(
+    r"(?:^|[:(\[]\s*|^\s*[-*]\s*)(TODO|PENDING)\s*(?:$|[)\].,;])", re.M)
+
+
+def placeholder_in(text):
+    return OBVIOUS_PLACEHOLDER.search(text) or WORDY_PLACEHOLDER.search(text)
+
+
+PLACEHOLDER = OBVIOUS_PLACEHOLDER
+STATUS = re.compile(r"^\s*status\s*:\s*(.+?)\s*$", re.M | re.I)
+SUPERSEDED_BY = re.compile(r"superseded\s+by\s+#?(\d{1,6})", re.I)
+
+ALLOWED_STATUS = {"proposed", "accepted", "rejected", "superseded"}
+
+
+def decision_files(root):
+    d = os.path.join(root, DECISIONS)
+    if not os.path.isdir(d):
+        return None
+    out = []
+    for fn in sorted(os.listdir(d)):
+        if not fn.endswith(".md") or fn.upper().startswith("README"):
+            continue
+        out.append((fn, os.path.join(d, fn)))
+    return out
+
+
+def main(argv):
+    want_next = "--next" in argv
+    args = [a for a in argv[1:] if not a.startswith("--")]
+    if not args:
+        print("usage: decision-ids [--next] <directory>", file=sys.stderr)
+        return 2
+    root = args[0]
+    if not os.path.isdir(root):
+        print("ERROR: not a directory: %s" % root, file=sys.stderr)
+        return 2
+
+    files = decision_files(root)
+    if files is None:
+        if want_next:
+            print("0001")
+            return 0
+        print("no %s directory, nothing claimed" % DECISIONS)
+        return 0
+
+    numbers = {}
+    problems = []
+
+    for fn, path in files:
+        m = NAMED.match(fn)
+        if not m:
+            problems.append("%s — the filename does not start with a number" % fn)
+            continue
+        n = int(m.group(1))
+        numbers.setdefault(n, []).append(fn)
+
+        try:
+            text = open(path, encoding="utf-8", errors="strict").read()
+        except (UnicodeDecodeError, OSError) as e:
+            print("ERROR: cannot read %s: %s" % (path, e), file=sys.stderr)
+            return 2
+
+        ph = placeholder_in(text)
+        if ph:
+            problems.append("%s — still carries the placeholder '%s'"
+                            % (fn, ph.group(1)))
+
+        st = STATUS.search(text)
+        if not st:
+            problems.append("%s — no status" % fn)
+        else:
+            # An empty value used to raise IndexError here, which surfaced
+            # as a traceback and exit 1 — where the contract says a check
+            # that cannot run says 2, and one that finds something names it.
+            words = st.group(1).strip().strip('"\'').split()
+            if not words:
+                problems.append("%s — status is empty" % fn)
+                continue
+            first = words[0].lower()
+            if first not in ALLOWED_STATUS:
+                problems.append("%s — status '%s' is not one of: %s"
+                                % (fn, st.group(1).strip(),
+                                   ", ".join(sorted(ALLOWED_STATUS))))
+
+    highest = max(numbers) if numbers else 0
+    if want_next:
+        print("%04d" % (highest + 1))
+        return 0
+
+    for n, names in sorted(numbers.items()):
+        if len(names) > 1:
+            problems.append("number %04d is used by %d files: %s"
+                            % (n, len(names), ", ".join(names)))
+
+    # A supersession must point at something that exists.
+    for fn, path in files:
+        try:
+            text = open(path, encoding="utf-8", errors="ignore").read()
+        except OSError:
+            continue
+        for target in SUPERSEDED_BY.findall(text):
+            if int(target) not in numbers:
+                problems.append("%s — says it is superseded by %s, which does "
+                                "not exist" % (fn, target))
+
+    if problems:
+        print("%d problem(s) across %d decision(s)" % (len(problems), len(files)))
+        for p in problems:
+            print("  %s" % p)
+        return 1
+
+    print("%d decision(s), numbered without collision, nothing left pending"
+          % len(files))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))