formwork-kit 0.1.0__py3-none-any.whl

formwork_cli/__init__.py

@@ -0,0 +1,326 @@
+"""The `formwork` command.
+
+    formwork init       put the kit into this project
+    formwork install    wire it up to your coding agent
+    formwork check      run every check
+    formwork demo       watch every check refuse a broken input
+    formwork roles      rebuild the role files after editing one
+    formwork record     write down what the kit looks like now
+    formwork test       run every test in the kit
+    formwork where      say which kit is being used
+
+WHY THIS EXISTS
+---------------
+The kit is a folder of files that has to live inside your project, because
+your agent's hooks call those files by path. That part cannot be global.
+
+What can be global is the word you type. This module is the word.
+
+HOW IT FINDS THE KIT
+--------------------
+It looks for a `formwork/` folder in the current directory, then each
+directory above it. So the command works anywhere inside your project.
+
+`formwork init` copies a fresh kit out of this package into the current
+directory. That copy is what your project uses from then on. Upgrading the
+command does not change a project you have already set up, which is
+deliberate: a rule that changes under you without a commit is not a rule.
+
+Python 3.8 or newer. No dependencies.
+"""
+import os
+import re
+import shutil
+import stat
+import subprocess
+import sys
+
+__all__ = ["main"]
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+BUNDLED_KIT = os.path.join(HERE, "kit")
+BUNDLED_PAGE = os.path.join(HERE, "kit-page", "FORMWORK.md")
+
+try:                                    # Python 3.8 or newer
+    from importlib.metadata import version as _version, PackageNotFoundError
+except ImportError:                     # pragma: no cover
+    _version = None
+
+COMMANDS = [
+    ("init",    "put the kit into this project"),
+    ("install", "wire it up to your agent. --runtime <name> to choose"),
+    ("check",   "run every check on this project"),
+    ("demo",    "watch every check refuse a broken input"),
+    ("roles",   "rebuild the role files after editing one"),
+    ("test",    "run every test in the kit"),
+    ("record",  "write down what the kit looks like now, after you changed it"),
+    ("where",   "say which kit is being used"),
+    ("version", "which version of the command this is"),
+]
+
+TESTS = [
+    os.path.join("guard", "test_boundary.py"),
+    os.path.join("guard", "test_protection.py"),
+    os.path.join("guard", "test_quality_gate.py"),
+    os.path.join("check", "test_gate.py"),
+    "test_install.py",
+]
+
+
+def find_kit(start=None, complete_only=True):
+    """The nearest formwork/ folder at or above here, or None.
+
+    complete_only=False also returns a folder that looks like a kit but is
+    missing pieces. Without that, a damaged kit produced three different
+    answers from three commands and no way forward.
+    """
+    d = os.path.abspath(start or os.getcwd())
+    while True:
+        candidate = os.path.join(d, "formwork")
+        looks_like = os.path.isdir(candidate) and (
+            os.path.isdir(os.path.join(candidate, "guard"))
+            or os.path.isdir(os.path.join(candidate, "check"))
+            or os.path.isdir(os.path.join(candidate, "roles")))
+        if os.path.isdir(candidate) and os.path.isfile(
+                os.path.join(candidate, "check", "run")):
+            return candidate
+        if looks_like and not complete_only:
+            return candidate
+        parent = os.path.dirname(d)
+        if parent == d:
+            return None
+        d = parent
+
+
+def make_runnable(root):
+    """Give every program in the kit its execute bit back.
+
+    A wheel does not reliably carry file modes, and a check that cannot run is
+    treated by the gate as a failure rather than a pass. So this is not
+    cosmetic.
+    """
+    fixed = 0
+    for dirpath, dirnames, filenames in os.walk(root):
+        for fn in filenames:
+            p = os.path.join(dirpath, fn)
+            try:
+                with open(p, "rb") as fh:
+                    if fh.read(2) != b"#!":
+                        continue
+            except OSError:
+                continue
+            mode = os.stat(p).st_mode
+            os.chmod(p, mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+            fixed += 1
+    return fixed
+
+
+def cmd_init(args):
+    if any(a.startswith("-") for a in args):
+        print("formwork init [directory]")
+        print("")
+        print("  Puts the kit into a directory. Defaults to this one.")
+        print("  `formwork init --help` used to create a folder called")
+        print("  --help, with a kit inside it.")
+        return 0
+    if not os.path.isdir(BUNDLED_KIT):
+        print("ERROR: this copy of the command has no kit bundled with it.",
+              file=sys.stderr)
+        print("       Clone the repository and copy formwork/ in by hand.",
+              file=sys.stderr)
+        return 2
+
+    target = os.path.abspath(args[0]) if args else os.getcwd()
+    dest = os.path.join(target, "formwork")
+
+    if os.path.exists(dest):
+        print("There is already a formwork/ folder here.")
+        print("Nothing was changed. Delete it first if you meant to start "
+              "again.")
+        return 1
+
+    # Without the filter, pip's own bytecode caches travel into the user's
+    # project and get committed by their first `git add .`
+    above = find_kit(os.path.dirname(target) if os.path.dirname(target) else None)
+    if above and os.path.dirname(os.path.dirname(above)) != target:
+        print("There is already a kit above this folder, at %s." % above)
+        print("Two kits in one tree is almost never what somebody wants.")
+        print("Nothing was changed. Pass a directory if you meant it:")
+        print("    formwork init /somewhere/else")
+        return 1
+
+    try:
+        shutil.copytree(BUNDLED_KIT, dest,
+                        ignore=shutil.ignore_patterns("__pycache__", "*.pyc"))
+    except OSError as e:
+        print("ERROR: could not write into %s: %s" % (target, e),
+              file=sys.stderr)
+        return 2
+    n = make_runnable(dest)
+
+    page = os.path.join(target, "FORMWORK.md")
+    wrote_page = False
+    if os.path.isfile(BUNDLED_PAGE) and not os.path.exists(page):
+        shutil.copy2(BUNDLED_PAGE, page)
+        wrote_page = True
+
+    print("wrote  formwork/        the kit, %d programs made runnable" % n)
+    if wrote_page:
+        print("wrote  FORMWORK.md     the method on one page")
+    print("")
+    print("Next:  formwork install --runtime claude-code")
+    return 0
+
+
+def run_in_kit(rel, args):
+    kit = find_kit()
+    if kit is None:
+        broken = find_kit(complete_only=False)
+        if broken:
+            print("ERROR: there is a formwork/ folder at %s, and it is "
+                  "incomplete." % broken, file=sys.stderr)
+            print("       formwork/check/run is missing. Delete the folder "
+                  "and run `formwork init` again.", file=sys.stderr)
+            return 2
+        print("ERROR: no formwork/ folder here, or in any folder above this "
+              "one.", file=sys.stderr)
+        print("       Run `formwork init` first, or change to a project that "
+              "has one.", file=sys.stderr)
+        return 2
+    program = os.path.join(kit, rel)
+    if not os.path.isfile(program):
+        print("ERROR: %s is missing from the kit at %s" % (rel, kit),
+              file=sys.stderr)
+        return 2
+    if not os.access(program, os.X_OK):
+        make_runnable(kit)
+    project = os.path.dirname(kit)
+    try:
+        return subprocess.run([sys.executable, program] + list(args),
+                              cwd=project).returncode
+    except OSError as e:
+        print("ERROR: could not run %s: %s" % (rel, e), file=sys.stderr)
+        return 2
+
+
+TOTAL = re.compile(r"(\d+) of \1 behaved as specified|(\d+) passed, 0 failed")
+
+
+def cmd_test():
+    kit = find_kit()
+    if kit is None:
+        print("ERROR: no formwork/ folder here.", file=sys.stderr)
+        return 2
+    # The tests exercise the guards with paths relative to the project root,
+    # so they must run from there. Running them from wherever the person
+    # happened to be standing failed 44 of them for the wrong reason.
+    project = os.path.dirname(kit)
+    failed = []
+    total = 0
+    for t in TESTS:
+        full = os.path.join(kit, t)
+        if not os.path.isfile(full):
+            continue
+        print("\n%s" % t, flush=True)
+        p = subprocess.run([sys.executable, full], cwd=project,
+                           capture_output=True, text=True)
+        sys.stdout.write(p.stdout)
+        sys.stderr.write(p.stderr)
+        if p.returncode != 0:
+            failed.append(t)
+        # Add the suites up. The README states one number and this command
+        # used to end on the smallest of five, so a reader checking the claim
+        # concluded it was inflated twelvefold.
+        for m in TOTAL.finditer(p.stdout):
+            total += int(m.group(1) or m.group(2))
+    print("")
+    if failed:
+        print("FAILED: %s" % ", ".join(failed), file=sys.stderr)
+        return 1
+    print("%d tests, all passed" % total)
+    return 0
+
+
+def cmd_version():
+    """Which version this is.
+
+    Every bug report worth having starts with this, and the first version of
+    this command did not have it.
+    """
+    v = "unknown"
+    if _version is not None:
+        try:
+            v = _version("formwork-kit")
+        except Exception:
+            v = "not installed as a package"
+    print("formwork-kit %s" % v)
+    kit = find_kit()
+    if kit:
+        print("kit at %s" % kit)
+    return 0
+
+
+def cmd_where():
+    kit = find_kit()
+    if kit is None:
+        broken = find_kit(complete_only=False)
+        if broken:
+            print("An incomplete kit at %s. formwork/check/run is missing."
+                  % broken)
+            print("Delete that folder and run `formwork init` again.")
+            return 1
+        print("No kit here. `formwork init` puts one in this folder.")
+        return 1
+    print("kit      %s" % kit)
+    print("project  %s" % os.path.dirname(kit))
+    print("command  %s" % HERE)
+    return 0
+
+
+def usage():
+    print("formwork <command>")
+    print("")
+    for name, what in COMMANDS:
+        print("  %-8s %s" % (name, what))
+    print("")
+    print("Everything here runs a program inside your project's formwork/")
+    print("folder. You can always run those directly instead.")
+    return 0
+
+
+def main(argv=None):
+    argv = list(sys.argv if argv is None else argv)
+    if len(argv) >= 2 and argv[1] in ("--version", "-V"):
+        return cmd_version()
+    if len(argv) < 2 or argv[1] in ("help", "-h", "--help"):
+        return usage()
+    cmd, rest = argv[1], argv[2:]
+    if cmd == "init":
+        return cmd_init(rest)
+    if cmd == "install":
+        return run_in_kit("install", rest)
+    if cmd == "check":
+        return run_in_kit(os.path.join("check", "run"), rest)
+    if cmd == "demo":
+        return run_in_kit(os.path.join("check", "run"), ["--demo-fail"] + rest)
+    if cmd == "roles":
+        return run_in_kit("build", rest)
+    if cmd == "test":
+        return cmd_test()
+    if cmd == "where":
+        return cmd_where()
+    if cmd in ("version", "--version", "-V"):
+        return cmd_version()
+    if cmd == "record":
+        kit = find_kit()
+        target = os.path.dirname(kit) if kit else "."
+        return run_in_kit(os.path.join("check", "checks", "kit-integrity"),
+                          ["--record", target] + rest)
+    print("ERROR: no such command: %s" % cmd, file=sys.stderr)
+    print("", file=sys.stderr)
+    usage()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

formwork_cli/kit/COSTS.md

@@ -0,0 +1,111 @@
+# What this costs to run
+
+Two of the three numbers below are measured. The most important one is not.
+
+---
+
+## The gate — measured
+
+```
+$ time formwork check
+real 1.89
+real 2.27
+real 2.20
+```
+
+About two seconds on this repository, over three runs. That is one run of all
+nine checks over 129 files, including the fixtures each check is tried
+against. It runs at the end of
+every turn in which something changed.
+
+**What would make that wrong:** it scales with how many files you have, and with
+how many checks you add. On a large repository, measure it rather than trusting
+this line.
+
+## What the kit adds to your repository — measured
+
+```
+$ find formwork -type f | wc -l
+129
+```
+
+129 files. Plain text and a few small programs. Python 3, standard library only,
+no dependencies of any kind. It costs nothing to carry and nothing to install.
+
+---
+
+## A round — NOT ESTABLISHED
+
+**Nobody has measured what a round costs in money. Not once.**
+
+This is the most important number on this page and it is missing. Treat a round
+as expensive until somebody produces the figure.
+
+### What can be measured without spending anything
+
+A round has a floor: the reading everybody has to do before a single thought
+happens.
+
+| | words |
+|---|---|
+| the core everybody reads — the page, the loop, the core rules | 2,276 |
+| five role files, one per participant | 7,733 |
+| **five participants, each reading the core plus their role** | **19,113** |
+
+```
+wc -w FORMWORK.md formwork/loop.md formwork/rules/core.md \
+      formwork/roles/method/{lead,challenger,architect,researcher,record-keeper}.md
+```
+
+**What that number is not.** It is the floor, and only the floor. It excludes:
+
+- your briefing, which is the largest single input and is different every time
+- whatever each participant reads from your repository
+- everything anybody writes
+- every exchange after the first — the challenge, the reply, the record
+
+A real round is a multiple of this, and **nobody knows the multiple.**
+
+**And it will be out of date.** These figures have gone stale twice while this
+page existed, because the roles keep growing. The commands are printed above for
+that reason: **run them, do not trust the table.**
+
+**What that number is also not:** it is words, not tokens. Models are billed in
+tokens, and the conversion depends on the model. Converting it here would be
+inventing precision.
+
+### What would establish it
+
+Run one round. Read the token usage the runtime itself reports. Multiply by the
+published rate. Write down the size of round it came from.
+
+That is an afternoon, and until somebody spends it this page keeps saying NOT
+ESTABLISHED.
+
+### There is no spend cap
+
+Nothing in this kit stops a round costing more than you expected. A cap is on
+the list of things not built, deliberately, because nobody has asked for one
+yet.
+
+**If you run rounds, set a limit with your provider.** That is outside this kit
+and it is the only real protection available today.
+
+---
+
+## The cost that is certain, and is not money
+
+**Every piece of work waits for you.**
+
+That is what the version-control boundary means. The agent stops, reports, and
+does nothing further until you say so.
+
+On a busy day that is the bottleneck. It is also the entire point, and it is
+the price of the whole method.
+
+---
+
+## What this page does not cover
+
+Time. How long a brief takes to write, how long a review takes to read.
+**Never measured**, and it would be a guess dressed as a figure.

formwork_cli/kit/adapters/claude-code/README.md

@@ -0,0 +1,53 @@
+# Claude Code adapter
+
+**Label: tested.** The boundary has been watched refusing a real command in
+this runtime.
+
+## What it wires
+
+**Four hooks across three events**, not one. Copying only part of this file
+leaves you with part of the protection.
+
+| Event | What runs | What it does |
+|---|---|---|
+| `PreToolUse` on `Bash` | `git-boundary` | refuses commits, pushes and merges |
+| `PreToolUse` on `Bash` | `protected-files` | refuses changes to the kit's own files |
+| `PreToolUse` on `Write\|Edit\|NotebookEdit` | `protected-files` | the same, for direct edits |
+| `Stop` | `quality-gate` | refuses to end a turn while the gate is red |
+
+Before any shell command runs, the guards read it and decide.
+
+- exit `0` — the command runs
+- exit `2` — the command is refused, and the reason goes back to the agent
+
+Exit code 2 is the runtime's documented way to block a tool call.
+
+## Installing it
+
+Merge `settings.json` here into `.claude/settings.json` in your project. If you
+have no hooks yet, copying the file is enough.
+
+`$CLAUDE_PROJECT_DIR` is set by the runtime and points at your project root, so
+the path works wherever the project lives.
+
+## Checking it took
+
+```
+formwork check
+```
+
+The `guard-wired` check fails if `.formwork.toml` names a runtime and that
+runtime's wiring is missing. A boundary that is not installed is a boundary
+that is not there, and nothing else would tell you.
+
+## Turning it down
+
+In `.formwork.toml`:
+
+```toml
+[strength]
+git_boundary = "block"   # block | warn | off
+```
+
+`block` is the default and is the right setting for one person working alone.
+Turning it down is a line you wrote, which is the point.

formwork_cli/kit/adapters/claude-code/settings.json

@@ -0,0 +1,46 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/formwork/guard/git-boundary --format claude-code",
+            "timeout": 10,
+            "statusMessage": "version-control boundary"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/formwork/guard/protected-files --format claude-code",
+            "timeout": 10,
+            "statusMessage": "self-protection"
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/formwork/guard/protected-files --format claude-code",
+            "timeout": 10,
+            "statusMessage": "self-protection"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/formwork/guard/quality-gate --format claude-code",
+            "timeout": 300,
+            "statusMessage": "the aggregate"
+          }
+        ]
+      }
+    ]
+  }
+}

formwork_cli/kit/adapters/codex/README.md

@@ -0,0 +1,43 @@
+# Codex adapter
+
+**Label: untested.** The publisher documents everything below. Nobody has run
+it. It stays untested until somebody watches it work.
+
+## Blocking
+
+Codex refuses a tool call on exit code 2, the same as the other three, so the
+same guards serve it. Wire both to `preToolUse`, pointing at:
+
+```
+formwork/guard/git-boundary   --format codex
+formwork/guard/protected-files --format codex
+```
+
+Hooks go in `.codex/hooks.json`, or inline in `~/.codex/config.toml`. Its own
+source carries `PreToolUseHookResult::Blocked`, so the mechanism is real even
+though this wiring has not been exercised.
+
+## Roles
+
+`formwork roles --runtime codex` writes `.codex/agents/<name>.toml`.
+
+**Of the four runtimes, this is the one that does not take markdown.** It takes TOML, with
+`name`, `description` and `developer_instructions`.
+
+## Where the tool grant goes
+
+**Nowhere.** Codex has a sandbox mode, which is not a tool list. A role that
+may not start other agents cannot say so here.
+
+Each generated file states that in a comment rather than emitting a setting
+that looks like a restriction and is not. **On Codex the grant is advice.**
+
+## A defect worth knowing before you rely on this
+
+Its issue tracker carries a report that agents in `.codex/agents/` cannot be
+invoked by name from a tool-backed session — the runtime exposing only generic
+spawning — and that the configuration has to be extracted and passed as
+overrides instead.
+
+If that holds, these generated files exist and cannot be used as documented.
+**Not established here**, and worth checking before depending on it.

formwork_cli/kit/adapters/cursor/README.md

@@ -0,0 +1,45 @@
+# Cursor adapter
+
+**Label: untested.** Documented by the publisher, never run.
+
+## Roles — nothing is generated
+
+Cursor's own documentation names `.claude/agents/` as a location it reads,
+alongside `.cursor/agents/` and `.codex/agents/`.
+
+So **the Claude Code output serves Cursor directly.** Generating a second,
+identical tree would be duplication for its own sake, and duplication is what
+the generator exists to remove.
+
+Run `formwork roles --runtime claude-code` and Cursor finds them.
+
+## Where the tool grant goes
+
+Cursor has `readonly: true|false`. One bit.
+
+That can say "this role may not write". It cannot say "this role may write and
+may not start other agents", which is what the challenger needs.
+
+Nothing approximate is emitted. **On Cursor the grant is advice.**
+
+**And no file tells you that**, because nothing is generated for Cursor. The
+files Cursor reads are the Claude Code ones, and they carry a Claude Code tool
+list that Cursor cannot act on. This page is the only place that says so, which
+is worth knowing before you rely on it.
+
+## Blocking
+
+Cursor refuses on exit code 2, and has more hook events than any of the four —
+`preToolUse`, `beforeShellExecution`, `beforeMCPExecution`, `beforeReadFile`,
+`subagentStart`.
+
+Point `beforeShellExecution` at:
+
+```
+formwork/guard/git-boundary   --format cursor
+formwork/guard/protected-files --format cursor
+```
+
+`subagentStart` is worth knowing about: it can refuse the creation of a
+subagent outright, which is the nearest thing Cursor has to the `spawn` grant.
+Whether it is a workable substitute is **not established**.

formwork_cli/kit/adapters/gemini-cli/README.md

@@ -0,0 +1,47 @@
+# Gemini CLI adapter
+
+**Label: untested.** Documented by the publisher, never run.
+
+## Blocking
+
+`BeforeTool` refuses on exit code 2, with the reason taken from standard error.
+Configure hooks in `.gemini/settings.json`, pointing at:
+
+```
+formwork/guard/git-boundary   --format gemini-cli
+formwork/guard/protected-files --format gemini-cli
+```
+
+## Roles
+
+`formwork roles --runtime gemini-cli` writes `.gemini/agents/<name>.md` —
+markdown with YAML frontmatter, `kind: local`, and a `tools:` list.
+
+## Where the tool grant goes — and the gap
+
+Gemini CLI takes a named allowlist and enforces it, which is what the kit
+wants. Two documented tool names are known and used:
+
+```
+read  →  read_file, grep_search
+run   →  run_shell_command
+```
+
+**The name of the file-writing tool is not among the publisher's documented
+examples.**
+
+An allowlist is exact: writing one that omits a tool the role needs would
+silently take that tool away. So the generator **writes no list at all** for
+any role that needs `write`, and puts a line in the file saying why.
+
+The consequence, stated plainly: **most roles get no enforced grant on Gemini
+CLI today**, because most roles write. Read-only roles — the reviewer — get a
+real one.
+
+Closing this needs one fact: the documented name of the write tool. It is a
+research task, not a design problem.
+
+## One limit that costs this kit nothing
+
+Subagents cannot start subagents, even with a wildcard grant. Only the lead
+spawns, so nothing here is affected.