formwork-kit 0.1.0__py3-none-any.whl

formwork_cli/kit/install

@@ -0,0 +1,395 @@
+#!/usr/bin/env python3
+"""Set this project up to use the kit.
+
+    formwork install                    detect the runtime and wire it
+    formwork install --runtime cursor   say which runtime, rather than guessing
+    formwork/install --dry-run          say what would change, change nothing
+
+Exit status:
+    0   installed, or already installed and nothing to do
+    1   installed as far as it can go, and the rest needs your hand
+    2   could not run
+
+WHAT IT ADDS, AND ITS THREE LIMITS
+----------------------------------
+It adds three things:
+
+    .formwork.toml                  which runtime this project uses
+    the hook wiring for your runtime    so the guards are called at all
+    the role files for that runtime     generated from formwork/roles/
+
+The third one used to be a separate program nobody was told about. A fresh
+install passed, and then the very next command — the one this installer
+prints — reported a red gate. Generating them here is the fix.
+
+That is all. It has three limits, and they are the point:
+
+  * **It never needs a clean working tree.** It does not read git, does not
+    look at your changes, and does not care what is uncommitted. Installing a
+    tool should not make you stop what you were doing.
+  * **It never moves or deletes a file.** Only adds. If it has to change an
+    existing file, it writes a copy of the original next to it first.
+  * **It never demands a document.** No brief, no decision record, no
+    structure imposed on a project that already has one.
+
+Running it twice changes nothing the second time.
+
+WHY IT SOMETIMES EXITS 1
+------------------------
+Only one of the four runtimes ships a wiring file in this kit. For the other
+three the wiring is documented by their publishers and **has never been run by
+anybody**, so this installer writes nothing for them. It names the file you
+must write yourself, points at the adapter README that says what goes in it,
+and exits 1 rather than 0.
+
+**Their gate stays red until that file exists.** That is the correct answer:
+nothing is guarding yet, and reporting green would be a lie.
+
+Exit 1 means: you are not finished. Go and look.
+
+Python 3, standard library only.
+"""
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+
+DONE, PARTIAL, CANNOT_RUN = 0, 1, 2
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.dirname(HERE)
+ADAPTERS = os.path.join(HERE, "adapters")
+
+# Where each runtime keeps its hooks. Must agree with the guard-wired check,
+# which fails the gate when a runtime is declared and its wiring is missing.
+WIRING = {
+    "claude-code": ".claude/settings.json",
+    "codex":       ".codex/hooks.json",
+    "cursor":      ".cursor/hooks.json",
+    "gemini-cli":  ".gemini/settings.json",
+}
+
+# A directory that means "this runtime is in use here".
+FOOTPRINT = {
+    "claude-code": ".claude",
+    "codex":       ".codex",
+    "cursor":      ".cursor",
+    "gemini-cli":  ".gemini",
+}
+
+# Only this one has a wiring file in the kit, watched refusing a real command.
+TESTED = {"claude-code"}
+
+CONFIG = """\
+# Formwork configuration. Three layers, kept apart on purpose.
+
+[bindings]
+# One person's setup. Change freely.
+runtime = "%s"
+
+[strength]
+# How hard each enforced rule bites: block | warn | off.
+# Strict by default. A team may need warn; somebody working alone should not.
+git_boundary = "block"
+protect_files = "block"
+
+# [rules] is deliberately absent, and that is the point.
+# Rules are not switched off here. Dropping one is an edit to
+# formwork/rules/core.md, which leaves a line in version control with your
+# name on it.
+"""
+
+
+class Plan(object):
+    """Everything that would change, decided before anything is written."""
+
+    def __init__(self, dry_run):
+        self.dry_run = dry_run
+        self.writes = []          # (path, text, why)
+        self.backups = []         # (path, copy_path)
+        self.notes = []
+        self.unfinished = []
+
+    def write(self, path, text, why):
+        self.writes.append((path, text, why))
+
+    def apply(self):
+        for path, copy in self.backups:
+            if self.dry_run:
+                continue
+            if not os.path.exists(copy):
+                shutil.copy2(path, copy)
+            else:
+                # A second install used to overwrite the file while leaving
+                # the first backup in place, so anything added in between
+                # existed in neither. Keep both.
+                stamp = "%s.%d" % (copy, int(time.time()))
+                shutil.copy2(path, stamp)
+        for path, text, _ in self.writes:
+            if self.dry_run:
+                continue
+            parent = os.path.dirname(path)
+            if parent:
+                os.makedirs(parent, exist_ok=True)
+            open(path, "w", encoding="utf-8").write(text)
+
+
+def detect(root):
+    """(runtime, why). runtime is None when it cannot be told from the outside."""
+    found = [r for r, d in sorted(FOOTPRINT.items())
+             if os.path.isdir(os.path.join(root, d))]
+    if len(found) == 1:
+        return found[0], "found %s/" % FOOTPRINT[found[0]]
+    if len(found) > 1:
+        return None, ("more than one runtime is set up here: %s"
+                      % ", ".join(found))
+    return None, "no runtime directory found"
+
+
+def declared(root):
+    path = os.path.join(root, ".formwork.toml")
+    if not os.path.exists(path):
+        return None
+    text = open(path, encoding="utf-8", errors="ignore").read()
+    m = re.search(r'^\s*runtime\s*=\s*["\']([^"\']+)["\']', text, re.M)
+    return m.group(1) if m else None
+
+
+def plan_config(plan, root, runtime):
+    path = os.path.join(root, ".formwork.toml")
+    already = declared(root)
+    if already == runtime:
+        plan.notes.append(".formwork.toml already says runtime = \"%s\"" % runtime)
+        return
+    if os.path.exists(path):
+        # Somebody's configuration, which may carry settings this installer
+        # knows nothing about. Overwriting it would throw those away.
+        plan.unfinished.append(
+            ".formwork.toml exists and says runtime = %s, not \"%s\". Left "
+            "alone. Change that line yourself if you meant to switch."
+            % ('"%s"' % already if already else "nothing", runtime))
+        return
+    plan.write(path, CONFIG % runtime, "declares the runtime")
+
+
+def merge_claude_hooks(existing, adapter):
+    """Add the kit's hooks to whatever is already there. Removes nothing."""
+    out = json.loads(json.dumps(existing))          # copy, leave the original
+    hooks = out.get("hooks")
+    if not isinstance(hooks, dict):
+        # A "hooks" key holding a list, or anything else, used to crash here.
+        hooks = {}
+        out["hooks"] = hooks
+    added = 0
+    for event, entries in adapter.get("hooks", {}).items():
+        current = hooks.get(event)
+        if not isinstance(current, list):
+            current = []
+            hooks[event] = current
+        for entry in entries:
+            matcher = entry.get("matcher")
+            mine = [e for e in current
+                    if isinstance(e, dict) and e.get("matcher") == matcher]
+            if not mine:
+                current.append(json.loads(json.dumps(entry)))
+                added += len(entry.get("hooks", []))
+                continue
+            target = mine[0]
+            if not isinstance(target.get("hooks"), list):
+                target["hooks"] = []
+            have = {h.get("command") for h in target["hooks"]
+                    if isinstance(h, dict)}
+            for h in entry.get("hooks", []):
+                if h.get("command") not in have:
+                    target.setdefault("hooks", []).append(
+                        json.loads(json.dumps(h)))
+                    added += 1
+    return out, added
+
+
+def plan_wiring(plan, root, runtime):
+    rel = WIRING[runtime]
+    path = os.path.join(root, rel)
+    source = os.path.join(ADAPTERS, runtime, "settings.json")
+
+    if not os.path.isfile(source):
+        plan.unfinished.append(
+            "%s has no wiring file in this kit, so nothing was written to %s. "
+            "Its hooks are documented in formwork/adapters/%s/README.md and "
+            "nobody has run them."
+            % (runtime, rel, runtime))
+        return
+
+    adapter = json.load(open(source, encoding="utf-8"))
+
+    if not os.path.exists(path):
+        plan.write(path, json.dumps(adapter, indent=2) + "\n",
+                   "wires the guards")
+        return
+
+    try:
+        existing = json.load(open(path, encoding="utf-8"))
+    except ValueError as e:
+        plan.unfinished.append(
+            "%s exists and is not valid JSON (%s), so it was left untouched. "
+            "Fix it, or merge formwork/adapters/%s/settings.json in by hand."
+            % (rel, e, runtime))
+        return
+
+    if not isinstance(existing, dict):
+        plan.unfinished.append(
+            "%s exists and is not an object, so it was left untouched. Merge "
+            "formwork/adapters/%s/settings.json in by hand." % (rel, runtime))
+        return
+
+    merged, added = merge_claude_hooks(existing, adapter)
+    if not added:
+        plan.notes.append("%s already calls the guards" % rel)
+        return
+    plan.backups.append((path, path + ".before-formwork"))
+    kept = 0
+    old_hooks = existing.get("hooks")
+    if isinstance(old_hooks, dict):
+        for entries in old_hooks.values():
+            if isinstance(entries, list):
+                for e in entries:
+                    if isinstance(e, dict) and isinstance(e.get("hooks"), list):
+                        kept += len(e["hooks"])
+    plan.write(path, json.dumps(merged, indent=2) + "\n",
+               "adds %d hook(s), keeping the %d you already had"
+               % (added, kept))
+
+
+def record_fingerprints(root, dry_run):
+    """Take the first integrity record, if there is not one already.
+
+    The integrity check refuses to pass until something is recorded, and the
+    self-protection guard refuses to let an agent re-record. Without this step
+    a fresh fork was deadlocked: the gate said run --record, and the guard
+    said no.
+
+    Only the FIRST record happens here. Re-recording after a change stays a
+    human decision, which is the whole point of the record.
+    """
+    checker = os.path.join(HERE, "check", "checks", "kit-integrity")
+    if not (os.path.isfile(checker) and os.access(checker, os.X_OK)):
+        return None
+    # Ask the checker where this project's record lives. A single machine-wide
+    # file meant the second project on a machine inherited the first one's
+    # fingerprints and was told its untouched guards had been tampered with.
+    probe = subprocess.run([checker, root], capture_output=True, text=True)
+    if "no fingerprints recorded" not in (probe.stdout + probe.stderr):
+        return "already"
+    if dry_run:
+        return "would"
+    try:
+        p = subprocess.run([checker, "--record", root], capture_output=True,
+                           text=True, timeout=120)
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    return "done" if p.returncode == 0 else None
+
+
+def generate_roles(root, runtime, dry_run):
+    """Write the role files for one runtime. Returns how many, or None.
+
+    Roles are the kit's headline feature and the installer used not to place
+    any of them. The generator lives beside this program; it is run rather
+    than reimplemented, so there is one source of truth for the format.
+    """
+    build = os.path.join(HERE, "build")
+    if not (os.path.isfile(build) and os.access(build, os.X_OK)):
+        return None
+    args = [build, "--runtime", runtime]
+    if dry_run:
+        args.append("--check")
+    try:
+        p = subprocess.run(args, capture_output=True, text=True, cwd=root,
+                           timeout=120)
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    m = re.search(r"(\d+)\s+(?:role|generated) file", p.stdout or "")
+    return int(m.group(1)) if m else None
+
+
+def main(argv):
+    args = argv[1:]
+    dry_run = "--dry-run" in args
+    root = os.getcwd()
+
+    if "--runtime" in args:
+        i = args.index("--runtime")
+        if i + 1 >= len(args):
+            print("ERROR: --runtime needs a name: %s"
+                  % ", ".join(sorted(WIRING)), file=sys.stderr)
+            return CANNOT_RUN
+        runtime, why = args[i + 1], "you said so"
+        if runtime not in WIRING:
+            print("ERROR: '%s' is not a runtime this kit can wire. Known: %s"
+                  % (runtime, ", ".join(sorted(WIRING))), file=sys.stderr)
+            return CANNOT_RUN
+    else:
+        runtime, why = detect(root)
+        if runtime is None:
+            print("Cannot tell which runtime this project uses: %s." % why)
+            print("Say which, and run again:")
+            for r in sorted(WIRING):
+                print("  formwork/install --runtime %s" % r)
+            return CANNOT_RUN
+
+    plan = Plan(dry_run)
+    plan_config(plan, root, runtime)
+    plan_wiring(plan, root, runtime)
+    plan.apply()
+    generated = generate_roles(root, runtime, dry_run)
+    recorded = record_fingerprints(root, dry_run)
+
+    verb = "would write" if dry_run else "wrote"
+    print("runtime: %s (%s)" % (runtime, why))
+    for path, _, reason in plan.writes:
+        print("  %s  %s — %s" % (verb, os.path.relpath(path, root), reason))
+    for path, copy in plan.backups:
+        print("  %s  %s — a copy of the original, before the merge"
+              % ("would keep" if dry_run else "kept",
+                 os.path.relpath(copy, root)))
+    if generated is not None:
+        print("  %s  %d role file(s) for %s"
+              % ("would generate" if dry_run else "generated", generated,
+                 runtime))
+    if recorded == "done":
+        print("  recorded  what every guard and check looks like right now")
+    elif recorded == "would":
+        print("  would record  what every guard and check looks like right now")
+    elif recorded == "already":
+        print("  already done  an integrity record exists; not touching it")
+    for note in plan.notes:
+        print("  already done  %s" % note)
+    if not plan.writes and not plan.notes:
+        print("  nothing to write")
+
+    if runtime not in TESTED:
+        plan.unfinished.append(
+            "This runtime is untested. Its wiring is documented by its "
+            "publisher and nobody has watched it refuse anything. Read "
+            "formwork/adapters/%s/README.md before relying on it." % runtime)
+
+    if plan.unfinished:
+        print("")
+        print("NOT FINISHED:")
+        for item in plan.unfinished:
+            print("  - %s" % item)
+        print("")
+        print("Then check it took:  formwork check")
+        return PARTIAL
+
+    print("")
+    print("Check it took:  formwork check")
+    print("Then:           formwork/first-run.md")
+    return DONE
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

formwork_cli/kit/limits.md

@@ -0,0 +1,141 @@
+# What this kit cannot do
+
+**Everything below was confirmed by running it, not guessed.** A guard you
+trust further than it deserves is worse than no guard at all.
+
+---
+
+## The short version
+
+**The guards stop the ordinary path, not a determined one.** They are pattern
+matching over a command line. An agent that wants past them can get past them.
+The value is that an agent not trying to, which is nearly always, is stopped
+from doing the everyday thing that should have been your decision.
+
+> [!WARNING]
+> **If you need containment, this is not it.** Use a sandbox.
+
+---
+
+## Ways past the version-control boundary
+
+These were all closed during the audit, and are now tested:
+
+`bash -c "git commit"` · `eval` · backticks · `$(...)` · `nice -n 5 git push` ·
+`timeout 60 git push` · `env -u FOO git push` · `git config core.hooksPath` ·
+`git checkout <file>`
+
+**These are still open, and are not closable by pattern matching:**
+
+- **Building the command out of pieces.** `g="git"; $g push`
+- **Encoding it.** Base64 into a shell, a string reversed, a character at a time.
+- **A script.** Writing `deploy.sh` and running it. The guard sees `./deploy.sh`.
+- **A different tool.** A git library in Python, a language binding, an editor's
+  built-in version control.
+- **`xargs`.** `echo <path> | xargs rm` — the path is an argument to `echo`.
+
+**Why these stay open.** Each fix is a longer pattern, and a longer pattern
+refuses more ordinary work. A guard that does that gets switched off, and then
+nothing is guarded.
+
+---
+
+## Ways past self-protection
+
+Closed during the audit: writing through a pipe, `chmod` in every spelling,
+deleting or moving the folder that holds the guards, re-recording the integrity
+fingerprints, hiding a path inside a here-document.
+
+**Still open:** everything in the list above, for the same reason. Plus:
+
+- **Symbolic and hard links.** A link to a protected file is a different path,
+  and the guard compares paths.
+- **A long-running program.** Approved once, then doing whatever it likes.
+
+---
+
+## What the checks cannot tell you
+
+**`predictions-first`** fails a round that has reports and no predictions file.
+Beyond that it only warns: modification times are weak evidence and it says so.
+**It cannot tell you the predictions were any good.**
+
+**The fixture shuffle hides the case name and nothing else.** Before a check
+runs, its test folder is copied somewhere with a meaningless name, so a check
+cannot pass by spotting the word "must-fail". **Names inside the folder are
+left alone**, because several checks read them for real reasons: a decision
+record is identified by its numbered filename, a role by its `.md` ending.
+
+So a check that looks for one particular file inside a fixture can still pass
+while examining nothing. An audit wrote one and it worked. Scrambling the
+contents was tried and broke the checks that read names legitimately.
+
+**What this means in practice:** the pair of fixtures proves a check can tell
+two inputs apart. It does not prove the check looked at what is in them.
+
+**`rule-labels`** checks that a rule naming a check names one that exists. It
+matches on the name only.
+
+**`doc-links`** resolves links. It does not know whether the page it reached
+says what the link promised.
+
+**`kit-integrity`** notices that a file changed. **It has no opinion about
+whether the change was good**, and re-recording is a human decision for exactly
+that reason.
+
+**`generated-current`** compares generated files with what the source produces.
+It now also reports generated files with no source at all.
+
+---
+
+## The gate gives up
+
+The turn-end gate refuses a red gate **three times in a session**, then stands
+aside with a loud message.
+
+**That is deliberate and it is a real hole.** Without it, a genuinely stuck turn
+is trapped for ever. With it, an agent that fails three times can proceed.
+
+Three refusals in one session is not a subtle signal. It is the point at which
+you should be reading, not the point at which the kit should keep refusing.
+
+`gate_budget` in `.formwork.toml` changes the number.
+
+---
+
+## What the privacy scanners cannot see
+
+Both ship outside the repository, and this matters to anyone forking the method
+rather than the code.
+
+**The word scan finds words.** The overlap scan finds eight words in a row.
+
+**Neither can see a paraphrase.** A fact from a private project, retold in fresh
+words, passes both cleanly. That happened while this kit was being built: both
+scans were green and a fresh reader still reconstructed a great deal. It is
+written up as entry 7 of `docs/dogfood.md`, in the source repository.
+
+**A clean scan proves the absence of what it looked for. It proves nothing
+about what it cannot see.**
+
+---
+
+## Three of the four runtimes are untested
+
+Only Claude Code has been watched refusing a real command.
+
+Codex, Cursor and Gemini CLI all document a way to block, and their adapters say
+`untested` at the top. **Their hook payload shapes are assumed**, not verified.
+The guards now refuse rather than allow when they cannot read a payload, so a
+wrong assumption shows up as a refusal rather than as silent permission.
+
+---
+
+## The honest summary
+
+This kit will stop an agent doing the wrong thing by habit. **It will not stop
+one doing the wrong thing on purpose**, and nothing built out of pattern
+matching would.
+
+If that is not enough for your situation, the answer is not a better pattern.
+It is a sandbox.

formwork_cli/kit/loop.md

@@ -0,0 +1,82 @@
+# The loop
+
+There is one loop. Only its size changes.
+
+```
+BRIEF → WORK → CHECK → REPORT → STOP → you say go → BRIEF …
+```
+
+**Nothing continues past STOP without you.** That is the whole shape.
+
+---
+
+## Five sizes
+
+| Size | How long | Brief | Report |
+|---|---|---|---|
+| task | minutes | one line | files, check result |
+| checkpoint | one sitting | six headings | the full list |
+| round | hours to days | a question per role | a round record |
+| phase | weeks | what it settles | one document |
+| milestone | months | a direction | — |
+
+**These are names for how big a turn was.** They are not five different
+processes. A task and a phase run the same loop.
+
+---
+
+## Four questions, every size
+
+Before starting anything, answer these. A phase and a five-minute task both
+deserve them, in proportion.
+
+1. **What does it produce?** One thing.
+2. **What has to be true before it starts?**
+3. **Who says go?** You.
+4. **What would tell us it failed?**
+
+Question four is the one people skip. A piece of work that cannot fail is a
+piece of work nobody can check.
+
+---
+
+## Picking a size
+
+Start small. The cost of picking too small is one more turn of the loop. The
+cost of picking too big is work nobody can review, which is worse.
+
+**Task** — you can describe it in a sentence and it touches a file or two.
+
+**Checkpoint** — you need to state what is out of scope. Past a small number of
+files you are looking at two of them.
+
+**Round** — the answer is genuinely unclear and you want it argued. Rounds cost
+real money and nobody has measured how much. Do not run one out of habit.
+
+**Phase** — a question big enough that its answer is a document.
+
+**Milestone** — a direction, not a piece of work. It contains phases.
+
+---
+
+## Where the size comes from
+
+Not from counting files. From this question:
+
+> Could a reviewer sensibly accept one part of this and reject the next part?
+
+If yes, it is two pieces of work. Split it there.
+
+*That test comes from a published engineering-process kit, not from this
+method. A file count is arbitrary and this is not.*
+
+---
+
+## What STOP means
+
+STOP is not "finished". It is "your turn".
+
+The agent halts, reports, and waits. It does not start the next piece because
+the next piece is obvious. It does not commit. It does not tidy up first.
+
+**If you only keep one thing from this kit, keep STOP.**