formwork-kit 0.1.0__py3-none-any.whl

formwork_cli/kit/first-run.md

@@ -0,0 +1,204 @@
+# Your first fifteen minutes
+
+Seven short steps, on your own project. No tutorial, no sample repository.
+
+**Nothing here restructures your work.** The install adds files and touches
+nothing else. It does not need a clean working tree.
+
+**The fifteen minutes is a target, not a measurement.** The machine's share is
+about a second. Your share is step 4, which is real work on your own project,
+and nobody can time that for you.
+
+> [!TIP]
+> **`command not found: formwork`?** Everything here also works as
+> `formwork/fw check`, `formwork/fw record` and so on, from the top of your
+> project. To get the short command: `pipx install formwork-kit`.
+
+---
+
+## 0. Get the kit into your project
+
+```
+formwork init
+```
+
+That puts `formwork/` and `FORMWORK.md` here. Without the command, copy those
+two in by hand from the source repository. Nothing else in it is needed.
+
+---
+
+## 1. Install
+
+```
+formwork install
+```
+
+It works out which agent you use, writes `.formwork.toml`, wires the guards
+into that agent's hooks, and generates your role files.
+
+**It adds and never removes.** Existing hook settings are kept, the kit's are
+added alongside, and a copy of your original is saved first.
+
+**It also writes one file outside your project**, in `~/.formwork/`: a
+fingerprint of everything that enforces a rule. Keeping it outside means a
+change to a guard cannot be hidden by changing the record next to it. It is
+also why a clone on another machine needs installing again.
+
+`formwork install --dry-run` shows what it would do. `--runtime cursor` says
+which agent when it cannot tell.
+
+**Read the exit code.** `0` finished. `1` got as far as it could and prints a
+`NOT FINISHED` list. `2` could not run.
+
+**On Claude Code the gate is green straight away.** On the other three it
+writes your config and roles but cannot wire the hooks, because the kit ships
+no wiring file for them. Your gate stays red until you write that file
+yourself, using your agent's page in `formwork/adapters/`. Red is correct
+there: nothing is guarding yet.
+
+---
+
+## 2. Watch it refuse
+
+Ask your agent to commit something.
+
+```
+you:    commit this for me
+agent:  (tries)
+        REFUSED by the version-control boundary: git commit changes
+        the repository.
+```
+
+The command never ran.
+
+Now ask it for `git status`. That works, as it always did.
+
+**Nothing was explained to you. You watched it happen.** That is the whole
+teaching method here: the rules catch things in front of you rather than being
+argued for.
+
+---
+
+## 3. Watch a check go red
+
+```
+formwork check
+```
+
+Green. Now:
+
+```
+formwork demo
+```
+
+Each check runs against an input built to break it, and you watch each one
+refuse.
+
+**A check nobody has seen fail is not evidence of anything.** Every check ships
+an input it must reject and one it must accept, so it has to tell them apart
+rather than simply be capable of complaining. If one ever stops rejecting its
+broken input, the gate goes red for that reason alone.
+
+---
+
+## 4. Do one real thing
+
+Pick something small and genuinely yours. A rename. A typo. A comment.
+
+Write a one-line brief:
+
+```
+Rename `foo` to `bar` in the parser. Nothing else.
+```
+
+That is a complete brief: a goal, a scope, and a fence.
+
+Let the agent do it. Then read what comes back:
+
+```
+Renamed foo -> bar in parser.py and its two tests.
+Gate green.
+Nothing staged.
+Nothing unasked, nothing skipped, brief was accurate.
+```
+
+Four lines, answering the three questions that matter: what was done beyond the
+request, what was skipped, and whether the brief was right.
+
+> [!IMPORTANT]
+> **Then it stops.** It does not start the next thing. That is the loop, and
+> `STOP` is the part worth keeping if you keep nothing else.
+
+---
+
+## 5. Now read the page
+
+[`FORMWORK.md`](../FORMWORK.md). One page, **after** doing the work rather than
+before.
+
+Everything on it now refers to something you have already seen.
+
+---
+
+## 6. What to read when you need it
+
+Nothing else is required today. These are the pages for when the situation
+arrives:
+
+| | |
+|---|---|
+| [`loop.md`](loop.md) | the working loop in full: brief, work, check, report, stop |
+| [`round.md`](round.md) | how to run a round, and when one is worth the money |
+| [`templates/`](templates/) | the brief, the report, the decision record, the round |
+| [`roles/HOW-TO-ADD-A-ROLE.md`](roles/HOW-TO-ADD-A-ROLE.md) | adding your own |
+| [`COSTS.md`](COSTS.md) | what this costs, and the number nobody has |
+| [`limits.md`](limits.md) | what the guards cannot do. Read before trusting them |
+| [`glossary.md`](glossary.md) | any word here you did not recognise |
+| [`troubleshooting.md`](troubleshooting.md) | when something goes wrong |
+
+---
+
+## What you have not been told
+
+Forty-six rules exist, in [`rules/`](rules/). Thirteen you meet daily,
+thirty-three for particular situations. You have seen three of them, by
+watching them catch something.
+
+Reading them now would be reading a list. You would agree with all of them and
+remember none.
+
+## Some of it will look like fussiness
+
+It will. Several of these rules came from failures you have not had.
+
+Each one says what it catches. **If you never hit that, delete it** from
+`formwork/rules/core.md`, so that losing a rule is a line in your version
+control with your name on it. There is no switch for this in `.formwork.toml`
+on purpose. What that file tunes is how hard the guards bite: `block`, `warn`
+or `off`.
+
+A rule followed without understanding gets dropped quietly later anyway.
+
+## If your agent cannot block
+
+**Only Claude Code has been watched refusing a real command.** The other three
+document a way and nobody has tried it. Their adapter pages say so in one word:
+untested.
+
+If yours is one of those three:
+
+**Step 2 may do nothing.** Ask for the commit anyway. If it is refused, you
+have established something nobody had established before, and it is worth
+saying so. If it goes through, you now know that on day one rather than on a
+bad day.
+
+**Steps 3 and 4 work either way.** `formwork demo` is a program you run
+yourself. The loop, the brief and the stop are things the agent does because
+the rules say so.
+
+> [!WARNING]
+> **The checks are yours whatever you run. None of the three guards is, until
+> the hooks are wired.**
+
+A rule an agent follows most of the time is worth having. It is not the same as
+one it cannot break, and this kit will not blur the two.

formwork_cli/kit/fw

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""One command for everything in this kit.
+
+    formwork/fw                 what you can do
+    formwork/fw install         set this project up
+    formwork/fw check           run every check
+    formwork/fw demo            watch every check refuse a broken input
+    formwork/fw roles           rebuild the role files after editing one
+    formwork/fw record          write down what the kit looks like now
+    formwork/fw test            run every test
+
+WHY THIS EXISTS
+---------------
+Before this, you had to remember `formwork/install --runtime claude-code` and
+`formwork/check/run` and `formwork/build`. Three paths and a flag, for five
+things you do every day.
+
+A Makefile at your project root would have been the obvious answer. It is also
+a file name your project may already be using, and overwriting somebody's build
+to save them typing is exactly what this kit exists to prevent.
+
+So: one file, inside the kit's own folder, where nothing can collide.
+
+Exit status is whatever the program underneath returned, so this can be used in
+a script the same way as the programs it calls.
+"""
+import os
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+COMMANDS = [
+    ("install", "set this project up. Add --runtime <name> to pick your agent"),
+    ("check",   "run every check on this project"),
+    ("demo",    "watch every check refuse a broken input"),
+    ("roles",   "rebuild the role files after editing one"),
+    ("record",  "write down what the kit looks like now, after you changed it"),
+    ("test",    "run every test in the kit"),
+]
+
+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",
+]
+
+
+PROJECT = os.path.dirname(HERE)
+
+
+def run(path, args):
+    full = os.path.join(HERE, path)
+    if not os.path.isfile(full):
+        print("ERROR: %s is missing from this kit" % path, file=sys.stderr)
+        return 2
+    try:
+        # From the project, always. Run from a subfolder without this and
+        # `install` wrote a second configuration into that subfolder and
+        # called it a success.
+        return subprocess.run([full] + args, cwd=PROJECT).returncode
+    except OSError as e:
+        print("ERROR: could not run %s: %s" % (path, e), file=sys.stderr)
+        return 2
+
+
+def run_tests():
+    failed = []
+    for t in TESTS:
+        full = os.path.join(HERE, t)
+        if not os.path.isfile(full):
+            continue
+        print("\n%s" % t, flush=True)
+        if subprocess.run([sys.executable, full], cwd=PROJECT).returncode != 0:
+            failed.append(t)
+    print("")
+    if failed:
+        print("FAILED: %s" % ", ".join(failed), file=sys.stderr)
+        return 1
+    print("every test passed")
+    return 0
+
+
+def usage():
+    print("formwork/fw <command>")
+    print("")
+    for name, what in COMMANDS:
+        print("  %-9s %s" % (name, what))
+    print("")
+    print("Nothing here is hidden. Each one runs a program in this folder that")
+    print("you can also run directly.")
+    return 0
+
+
+def main(argv):
+    if len(argv) < 2 or argv[1] in ("help", "-h", "--help"):
+        return usage()
+    cmd, rest = argv[1], argv[2:]
+    if cmd == "install":
+        return run("install", rest)
+    if cmd == "check":
+        return run(os.path.join("check", "run"), rest)
+    if cmd == "demo":
+        return run(os.path.join("check", "run"), ["--demo-fail"] + rest)
+    if cmd == "roles":
+        return run("build", rest)
+    if cmd == "test":
+        return run_tests()
+    if cmd == "record":
+        return run(os.path.join("check", "checks", "kit-integrity"),
+                   ["--record", os.path.dirname(HERE)] + rest)
+    print("ERROR: no such command: %s" % cmd, file=sys.stderr)
+    print("", file=sys.stderr)
+    usage()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

formwork_cli/kit/glossary.md

@@ -0,0 +1,160 @@
+# Words this kit uses
+
+Plain meanings, collected so you never have to go looking.
+
+---
+
+## The main ones
+
+**Agent**
+A program that does work for you using an AI model. You tell it what you want
+in plain words. It reads files, writes files and runs commands. Claude Code,
+Codex, Cursor and Gemini CLI are agents.
+
+**Runtime**
+The particular agent tool you use. This kit supports four of them. You tell it
+which one you have in `.formwork.toml`.
+
+**Role**
+A job description for an agent. One file. It says what that job owns, what it
+does not own, when it should stop, and what bad work from it would look like.
+This kit ships twenty seven.
+
+**Guard**
+A small program that refuses. Two of the three stop a command before it runs.
+The third stops a turn from ending while the gate is red. Not a warning.
+
+**Check**
+A small program that reads your project and says green or red. Checks look at
+what is there. Guards stop what is about to happen.
+
+**The gate**, also called **the aggregate**
+All nine checks, run together, with one answer at the end. Green or red.
+
+You will see the word aggregate in a refusal: *the aggregate is red, so this
+turn cannot conclude*. It means the same thing.
+
+**Adapter**
+The instructions for wiring the guards into one particular agent. One folder
+per agent, in `formwork/adapters/`.
+
+**Frontmatter**
+The block at the very top of a role file, between two lines of three dashes.
+It holds the name, the pack, the owns slug and the tools. A role without it
+does not load.
+
+**Slug**
+A short name with no spaces, used as an identifier. `owns: what-runs-on-a-
+server` is a slug. Two roles may not use the same one.
+
+**Turn**
+One exchange. You ask for something, the agent works, the agent replies. The
+gate runs at the end of every turn where something changed.
+
+---
+
+## Words about the work
+
+**Brief**
+What you want, written down before any work starts. Six short headings. The
+template is in `formwork/templates/brief.md`.
+
+**Report**
+What came back. What was done, what was skipped, what the agent thinks you
+should know. The template is in `formwork/templates/report.md`.
+
+**Round**
+Several agents looking at the same question at once, arguing, and one document
+coming out. Expensive. Only worth it for a decision you cannot easily undo. See
+`formwork/round.md`.
+
+**Predictions**
+What the challenger expects to go wrong, written before anybody proposes anything.
+Written after the fact it is not a prediction, it is agreement.
+
+**Decision record**
+One page saying what was decided, why, and what follows from it. Numbered.
+Never edited afterwards. If it changes later, a new one replaces it and both
+are kept.
+
+---
+
+## Words about the guards
+
+**Blocked** or **refused**
+The command did not run. You will see the word REFUSED and a reason.
+
+**The version-control boundary**
+The rule that your agent never commits, pushes or merges. You do that. It is
+enforced by a guard, not by asking nicely.
+
+**Self-protection**
+The rule that your agent cannot quietly change the kit's own files. The guards,
+the checks and the settings.
+
+**Strength**
+How hard a guard bites. Three settings: `block` refuses, `warn` lets it through
+and tells you, `off` does nothing. Set in `.formwork.toml`.
+
+**Refusal budget**
+The turn-end gate refuses a red gate three times in one session, then steps
+aside and says so loudly. Without this, a genuinely stuck turn would be stuck
+for ever.
+
+**Fingerprint**
+A short code worked out from the exact contents of a file. Change one character
+and the code changes. The kit keeps one for each file that enforces something,
+outside your project, so a change to a guard cannot be hidden.
+
+---
+
+## Words about the checks
+
+**Fixture**
+A small fake project used to test a check. Every check ships two kinds: one it
+must reject, and one it must accept.
+
+**Must-fail** and **must-pass**
+Those two kinds. A check has to tell them apart. Being able to complain is not
+enough.
+
+**Green** and **red**
+Green means every check passed. Red means at least one found something and
+named it.
+
+**Cannot run**
+A third answer, and the most important one. The check could not do its job.
+This is never treated as a pass.
+
+---
+
+## Words you will see in role files
+
+**Owns**
+The one thing that job is responsible for. No two roles own the same thing.
+
+**Does not own**
+What to hand to somebody else, and who.
+
+**Stops when**
+The moment that job should stop and ask you instead of guessing.
+
+**Tools**
+Which abilities a role may use: reading, writing, running commands, searching
+the web, starting other agents. Only the lead may start other agents.
+
+**Pack**
+A group of related roles. The software pack, the design pack, and so on. All
+roles are available today. There is no switch yet, and the kit says so.
+
+---
+
+## Two phrases worth knowing
+
+**NOT ESTABLISHED**
+Nobody has measured this or checked it. It is not a guess dressed up as a fact.
+Where you see this, treat the thing as unknown.
+
+**Catches**
+Every rule has a line saying what it catches. If a rule cannot say what goes
+wrong without it, it is an opinion, not a rule.