formwork-kit 0.1.0__py3-none-any.whl

formwork_cli/kit/check/checks/role-shape

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Check: every role is complete, and no two roles claim the same job.
+
+    role-shape <directory>
+
+Over every role in formwork/roles/:
+
+  1. it declares name, pack, owns and tools
+  2. it has all five sections
+  3. no other role claims the same `owns` slug
+  4. only the lead may hold `spawn`
+
+CATCHES  A role with no stated boundary, which wanders into somebody else's
+         work and nobody notices because nothing said where the edge was.
+
+         And two roles owning one thing, which is how two agents produce
+         opposite answers with equal confidence.
+
+Exit status:
+    0   every role complete, every job owned once
+    1   at least one problem, named
+    2   the check could not run
+"""
+import os
+import re
+import sys
+
+ROLES_SUBDIR = os.path.join("formwork", "roles")
+SKIP = {"TEMPLATE.md", "HOW-TO-ADD-A-ROLE.md", "README.md"}
+SECTIONS = ("Owns", "Does not own", "Tools", "Stops when", "Would be wrong if")
+FIELDS = ("name", "pack", "owns", "tools")
+MAY_SPAWN = {"lead"}
+
+SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv",
+             "venv", "build", "dist", "target", "vendor",
+             "site-packages", ".tox"}
+# Paths the runner has told this check to stay out of.
+EXCLUDED = [os.path.abspath(p) for p in
+            os.environ.get("FORMWORK_EXCLUDE", "").split(os.pathsep) if p]
+
+# Which runtimes can actually hold a role to its tool grant, established by
+# reading each publisher's own documentation. Recorded in docs/role-formats.md.
+#
+#   Claude Code, Gemini CLI   a named list of permitted tools
+#   Cursor                    read-only, or not. One bit, nothing finer
+#   Codex                     a sandbox mode, which is not a tool list at all
+ENFORCES_GRANTS = {"claude-code"}
+# Gemini CLI takes a named list and would enforce it. The documented name of
+# its file-writing tool is not established, so the generator writes no list for
+# any role that writes — which today is 26 of 27. Enforced in principle,
+# advisory in practice, and this check reports the practice.
+ADVISORY_GRANTS = {"cursor", "codex", "gemini-cli (for now)"}
+
+# A claim that a grant binds somewhere it cannot. Written as a check rather
+# than a sentence, because a sentence gets deleted by somebody tidying up.
+OVERCLAIM = re.compile(
+    r"(?i)(?:tool\s+grants?|grants?)\s+(?:are\s+|is\s+)?enforced\s+(?:on|in|by)"
+    r"\s+(?:all\s+(?:four\s+)?runtimes|every\s+runtime|cursor|codex)")
+
+
+def frontmatter(text):
+    m = re.match(r"^---\n(.*?)\n---\n", text, re.S)
+    if not m:
+        return None
+    out = {}
+    for line in m.group(1).split("\n"):
+        if ":" in line:
+            k, v = line.split(":", 1)
+            out[k.strip()] = v.strip()
+    return out
+
+
+def role_files(root):
+    base = os.path.join(root, ROLES_SUBDIR)
+    if not os.path.isdir(base):
+        return None
+    found = []
+    for dirpath, dirnames, filenames in os.walk(base):
+        for fn in sorted(filenames):
+            if fn.endswith(".md") and fn not in SKIP:
+                found.append(os.path.join(dirpath, fn))
+    return found
+
+
+def main(argv):
+    if len(argv) < 2:
+        print("usage: role-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
+
+    files = role_files(root)
+    if files is None:
+        print("no roles directory, nothing claimed")
+        return 0
+    if not files:
+        print("ERROR: a roles directory with no roles in it", file=sys.stderr)
+        return 2
+
+    problems = []
+    claimed = {}
+    for path in files:
+        rel = os.path.relpath(path, root)
+        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
+
+        fm = frontmatter(text)
+        if fm is None:
+            problems.append("%s — no frontmatter" % rel)
+            continue
+        for field in FIELDS:
+            if not fm.get(field):
+                problems.append("%s — no '%s' declared" % (rel, field))
+
+        for section in SECTIONS:
+            if not re.search(r"^\*\*%s\.?\*\*" % re.escape(section), text, re.M):
+                problems.append("%s — no '%s' section" % (rel, section))
+
+        owns = fm.get("owns")
+        if owns:
+            if owns in claimed:
+                problems.append("%s — claims '%s', already owned by %s"
+                                % (rel, owns, claimed[owns]))
+            else:
+                claimed[owns] = rel
+
+        if "spawn" in fm.get("tools", "") and fm.get("name") not in MAY_SPAWN:
+            problems.append("%s — holds 'spawn', which only the lead may hold"
+                            % rel)
+
+    # Nothing in the kit may claim a grant binds where the runtime cannot
+    # express it. Two of the four can only approximate one.
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        here = os.path.abspath(dirpath)
+        if any(here == e or here.startswith(e + os.sep) for e in EXCLUDED):
+            dirnames[:] = []
+            continue
+        for fn in sorted(filenames):
+            if not fn.endswith(".md"):
+                continue
+            full = os.path.join(dirpath, fn)
+            try:
+                text = open(full, encoding="utf-8", errors="ignore").read()
+            except OSError:
+                continue
+            for m in OVERCLAIM.finditer(text):
+                line = text[:m.start()].count("\n") + 1
+                problems.append("%s:%d — claims a tool grant is enforced where "
+                                "it cannot be. It binds on %s and is advice on "
+                                "%s" % (os.path.relpath(full, root), line,
+                                        ", ".join(sorted(ENFORCES_GRANTS)),
+                                        ", ".join(sorted(ADVISORY_GRANTS))))
+
+    if problems:
+        print("%d problem(s) across %d role(s)" % (len(problems), len(files)))
+        for p in problems:
+            print("  %s" % p)
+        return 1
+
+    print("%d role(s), each complete, each owning something nobody else does"
+          % len(files))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

formwork_cli/kit/check/checks/rule-labels

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Check: every rule is labelled, says what it catches, and does not lie.
+
+    rule-labels <directory>
+
+Three things, over every rule in formwork/rules/:
+
+  1. it says whether it is Enforced or Advice
+  2. it has a "Catches:" line
+  3. if it claims to be enforced, the check it names exists
+
+CATCHES  A rule that says it is enforced when nothing enforces it. Everything
+         reads correctly, the rule is in the file, and no program will ever
+         refuse anything. That is worse than honest advice, because you stop
+         watching for the thing yourself.
+
+         Also a rule with no "catches" line, which is a rule asking to be
+         obeyed without saying what for. Those get deleted in week two, and
+         they should be.
+
+Exit status:
+    0   every rule is labelled, explained, and honest
+    1   at least one is not, and it is named
+    2   the check could not run
+"""
+import os
+import re
+import sys
+
+RULES_SUBDIR = os.path.join("formwork", "rules")
+CHECKS_SUBDIR = os.path.join("formwork", "check", "checks")
+GUARD_SUBDIR = os.path.join("formwork", "guard")
+
+LABEL = re.compile(r"^\*\*(Enforced|Advice)\b", re.M)
+ENFORCER = re.compile(r"^\*\*Enforced\*\*\s+by\s+`([^`]+)`", re.M)
+CATCHES = re.compile(r"^\*\*Catches:\*\*", re.M)
+
+# A Catches line has to name a failure. "nothing" is the word a rule uses when
+# it cannot, and one shipped saying exactly that while this check passed it.
+EMPTY_CATCH = re.compile(
+    r"^\*\*Catches:\*\*\s*(nothing|none|n/a|-|tbd|todo)\s*\.?\s*$",
+    re.M | re.I)
+
+
+def rules_in(text):
+    """Split a rules file into (heading, body) at level-three headings."""
+    parts = re.split(r"^### (.+)$", text, flags=re.M)
+    out = []
+    for i in range(1, len(parts), 2):
+        out.append((parts[i].strip(), parts[i + 1]))
+    return out
+
+
+def enforcer_exists(root, named):
+    """A rule may name a check or a guard. It must be one that really runs.
+
+    This used to accept any file of that name anywhere, so `nonexistent/dir/
+    doc-links` passed because a file called doc-links exists somewhere. It now
+    requires the named thing to sit where the gate and the hooks look for it,
+    and to be runnable.
+    """
+    base = os.path.basename(named)
+    if named not in (base, os.path.join(CHECKS_SUBDIR, base),
+                     os.path.join(GUARD_SUBDIR, base)):
+        return False
+    for sub in (CHECKS_SUBDIR, GUARD_SUBDIR):
+        full = os.path.join(root, sub, base)
+        if os.path.isfile(full) and os.access(full, os.X_OK):
+            return True
+    return False
+
+
+def main(argv):
+    if len(argv) < 2:
+        print("usage: rule-labels <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
+
+    rules_dir = os.path.join(root, RULES_SUBDIR)
+    if not os.path.isdir(rules_dir):
+        print("no rules directory, nothing claimed")
+        return 0
+
+    problems = []
+    counted = 0
+    for fn in sorted(os.listdir(rules_dir)):
+        if not fn.endswith(".md"):
+            continue
+        path = os.path.join(rules_dir, 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
+
+        for heading, body in rules_in(text):
+            counted += 1
+            where = "%s: %s" % (fn, heading)
+            label = LABEL.search(body)
+            if not label:
+                problems.append("%s — neither Enforced nor Advice" % where)
+            elif label.group(1) == "Enforced":
+                named = ENFORCER.search(body)
+                if not named:
+                    problems.append("%s — says Enforced, names no check" % where)
+                elif not enforcer_exists(root, named.group(1)):
+                    problems.append("%s — says Enforced by `%s`, which does not "
+                                    "exist" % (where, named.group(1)))
+            if not CATCHES.search(body):
+                problems.append("%s — no 'Catches:' line" % where)
+            elif EMPTY_CATCH.search(body):
+                problems.append("%s — its 'Catches:' line says nothing is "
+                                "caught. A rule that cannot name a failure is "
+                                "an opinion" % where)
+
+    if not counted:
+        print("ERROR: a rules directory with no rules in it", file=sys.stderr)
+        return 2
+
+    if problems:
+        print("%d problem(s) across %d rule(s)" % (len(problems), counted))
+        for p in problems:
+            print("  %s" % p)
+        return 1
+
+    print("%d rule(s), each labelled, explained, and honest about enforcement"
+          % counted)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

formwork_cli/kit/check/fixtures/config-shape/must-fail/documents-a-section-that-does-not-exist/.formwork.toml

@@ -0,0 +1,5 @@
+[bindings]
+runtime = "claude-code"
+
+[strength]
+git_boundary = "block"

formwork_cli/kit/check/fixtures/config-shape/must-fail/documents-a-section-that-does-not-exist/formwork/guide.md

@@ -0,0 +1,13 @@
+# Guide
+
+Switch role packs on here:
+
+```toml
+[bindings]
+runtime = "claude-code"
+
+[roles]
+packs = ["method"]
+```
+
+There is no `[roles]` section in the real file, so this instruction is fiction.

formwork_cli/kit/check/fixtures/config-shape/must-fail/rules-as-a-switchboard/.formwork.toml

@@ -0,0 +1,8 @@
+[bindings]
+runtime = "claude-code"
+
+[strength]
+git_boundary = "block"
+
+[rules]
+one_unit_at_a_time = false

formwork_cli/kit/check/fixtures/config-shape/must-pass/layers-kept-apart/.formwork.toml

@@ -0,0 +1,5 @@
+[bindings]
+runtime = "claude-code"
+
+[strength]
+git_boundary = "block"

formwork_cli/kit/check/fixtures/decision-ids/must-fail/a-placeholder-shipped/docs/decisions/0003-still-pending.md

@@ -0,0 +1,7 @@
+---
+status: accepted
+---
+# A decision carrying a number nobody assigned
+
+Status says accepted; the number is still DEC-PENDING, and everything
+downstream will now cite it.

formwork_cli/kit/check/fixtures/decision-ids/must-fail/superseded-by-nothing/docs/decisions/0002-old.md

@@ -0,0 +1,6 @@
+---
+status: superseded by 0099
+---
+# 0002. Overtaken by something that does not exist
+
+The cross-reference breaks quietly.

formwork_cli/kit/check/fixtures/decision-ids/must-fail/two-decisions-one-number/docs/decisions/0007-first.md

@@ -0,0 +1,6 @@
+---
+status: accepted
+---
+# 0007. The first one
+
+Two threads were open and each read a different stale state.

formwork_cli/kit/check/fixtures/decision-ids/must-fail/two-decisions-one-number/docs/decisions/0007-second.md

@@ -0,0 +1,6 @@
+---
+status: accepted
+---
+# 0007. The second one
+
+Both were confident. Nothing anywhere noticed.

formwork_cli/kit/check/fixtures/decision-ids/must-pass/clean-numbering/docs/decisions/0001-the-first.md

@@ -0,0 +1,6 @@
+---
+status: accepted
+---
+# 0001. The first decision
+
+Numbered from the directory.

formwork_cli/kit/check/fixtures/decision-ids/must-pass/clean-numbering/docs/decisions/0002-the-second.md

@@ -0,0 +1,6 @@
+---
+status: superseded by 0003
+---
+# 0002. Overtaken later
+
+Kept, with its reasoning, because that is the useful part.

formwork_cli/kit/check/fixtures/decision-ids/must-pass/clean-numbering/docs/decisions/0003-the-third.md

@@ -0,0 +1,6 @@
+---
+status: accepted
+---
+# 0003. What replaced it
+
+The one that holds now.

formwork_cli/kit/check/fixtures/decision-ids/must-pass/nothing-recorded-yet/docs/decisions/README.md

@@ -0,0 +1,3 @@
+# Decisions
+
+A project that has recorded none yet.

formwork_cli/kit/check/fixtures/doc-links/must-fail/never-written/index.md

@@ -0,0 +1,7 @@
+# Index
+
+This fixture exists to make the doc-links check fail.
+
+A link written to a document somebody intended to write, and did not.
+
+Start with [the first run](first-run.md).

formwork_cli/kit/check/fixtures/doc-links/must-fail/renamed-file/architecture-notes.md

@@ -0,0 +1,3 @@
+# Architecture notes
+
+The file the guide is looking for, under its new name.

formwork_cli/kit/check/fixtures/doc-links/must-fail/renamed-file/guide.md

@@ -0,0 +1,8 @@
+# Guide
+
+This fixture exists to make the doc-links check fail.
+
+The file below was renamed, and this link was not updated. That is the whole
+failure mode: the sentence still reads correctly.
+
+See [the architecture notes](architecture.md) for the boundaries.

formwork_cli/kit/check/fixtures/doc-links/must-pass/links-resolve/architecture-notes.md

@@ -0,0 +1 @@
+# Architecture notes

formwork_cli/kit/check/fixtures/doc-links/must-pass/links-resolve/guide.md

@@ -0,0 +1,5 @@
+# Guide
+
+Every link here points at something real.
+
+See [the architecture notes](architecture-notes.md) for the boundaries.

formwork_cli/kit/check/fixtures/generated-current/must-fail/a-generated-file-was-edited/.claude/agents/sample.md

@@ -0,0 +1,22 @@
+---
+name: sample
+description: One clearly stated thing.
+tools: Read, Glob, Grep
+---
+
+<!-- GENERATED FROM formwork/roles/method/sample.md — DO NOT EDIT. -->
+<!-- Change the source and run formwork/build. A hand-edit here fails the gate. -->
+
+# Sample
+
+**Owns.** One clearly stated thing.
+
+**Does not own.** Something else.
+
+**Tools.** Reading.
+
+**Stops when.** It reaches the edge.
+
+**Would be wrong if.** It carried on.
+
+<!-- somebody edited this by hand and it will vanish -->

formwork_cli/kit/check/fixtures/generated-current/must-fail/a-generated-file-was-edited/.codex/agents/sample.toml

@@ -0,0 +1,22 @@
+# GENERATED FROM formwork/roles/method/sample.md — DO NOT EDIT.
+# Change the source and run formwork/build. A hand-edit here fails the gate.
+
+name = "sample"
+description = "One clearly stated thing."
+
+# This runtime has a sandbox mode rather than a tool list, so
+# the grant read is not expressed here. It is advice on Codex.
+
+developer_instructions = """
+# Sample
+
+**Owns.** One clearly stated thing.
+
+**Does not own.** Something else.
+
+**Tools.** Reading.
+
+**Stops when.** It reaches the edge.
+
+**Would be wrong if.** It carried on.
+"""

formwork_cli/kit/check/fixtures/generated-current/must-fail/a-generated-file-was-edited/.formwork.toml

@@ -0,0 +1 @@
+runtime = "claude-code"

formwork_cli/kit/check/fixtures/generated-current/must-fail/a-generated-file-was-edited/.gemini/agents/sample.md

@@ -0,0 +1,23 @@
+---
+name: sample
+description: One clearly stated thing.
+kind: local
+tools:
+  - read_file
+  - grep_search
+---
+
+<!-- GENERATED FROM formwork/roles/method/sample.md — DO NOT EDIT. -->
+<!-- Change the source and run formwork/build. A hand-edit here fails the gate. -->
+
+# Sample
+
+**Owns.** One clearly stated thing.
+
+**Does not own.** Something else.
+
+**Tools.** Reading.
+
+**Stops when.** It reaches the edge.
+
+**Would be wrong if.** It carried on.