formwork-kit 0.1.0__py3-none-any.whl

formwork_cli/kit/templates/brief.md

@@ -0,0 +1,68 @@
+# Brief
+
+Copy this. Fill it in. Hand it over.
+
+**For a task, one line is the whole brief.** Do not use this page for a rename.
+Scale the paperwork to the work, or the work stops happening.
+
+---
+
+## 1. Goal
+
+What this is for, and why it exists. One paragraph.
+
+**And one line that is easy to skip and should not be: what happens if we do
+not do this at all?** If the honest answer is "nothing much", you have saved
+yourself the work.
+
+## 2. Scope
+
+What may be changed, file by file where you can name them.
+
+This is also the fence. What is listed is what may be touched.
+
+**Out of scope:** name the things that must not be touched, not only the things
+that may. "Everything else" is not an answer — name the ones somebody might
+reasonably assume were included.
+
+## 3. Must not happen
+
+What is forbidden here. The standing ones always apply:
+
+- do not write to version control
+- do not decide anything; stop and report instead
+- do not change a check because it failed
+- where something cannot be established, say so rather than estimating
+
+Add the ones specific to this work.
+
+## 4. Done when
+
+How anyone can tell it is finished — testable, not a matter of opinion.
+
+**Something that cannot come out false is not a criterion.** Where a check
+requires a clean working tree and yours will be dirty, record that here.
+
+## 5. Checked by
+
+`formwork check`, named as the whole thing.
+
+You may add commands on top. You may never swap in a hand-picked few instead.
+
+If the gate cannot prove the thing this work changes, say so here and name what
+the real evidence will be.
+
+## 6. The report must contain
+
+The standing list in `formwork/templates/report.md`, plus anything else you
+want back.
+
+---
+
+## The task version
+
+```
+Rename `foo` to `bar` in the parser. Nothing else.
+```
+
+That is a complete brief. It has a goal, a scope, and a fence.

formwork_cli/kit/templates/decision.md

@@ -0,0 +1,93 @@
+# Decision record
+
+One file per decision, in `docs/decisions/`, numbered in the order you accepted
+them.
+
+**This shape is borrowed, not invented.** It follows the widely used Markdown
+decision-record format. The survey found decision records already solved, twice
+over, so this kit does not design its own. If you want the fuller original, go
+and take it — it has four sizes and translations.
+
+**Only you write these.** An agent may copy in wording you have accepted, word
+for word. It may never author one.
+
+---
+
+```markdown
+---
+status: accepted
+date: 2026-09-12
+deciders: [who actually decided]
+consulted: [who was asked, and answered]
+informed: [who was told afterwards]
+---
+
+<!-- Save as docs/decisions/0007-short-title.md — the number and the hyphen
+     are required. `formwork check` verifies the numbering. For the next free
+     number, run `formwork/check/checks/decision-ids --next .` and ignore any
+     other output it prints: run on its own it also scans the kit's test
+     fixtures. Do not count the files yourself, because gaps are allowed and
+     counting collides. -->
+
+# 0007. Short title in plain words
+
+## What made this a decision
+
+The situation. What forced a choice. Keep it to what a stranger needs.
+
+## What matters here
+
+The two or three things any answer has to satisfy. Name them before the
+options, or you will pick an option and then invent the reasons.
+
+## Options we looked at
+
+- **Option A** — one line.
+- **Option B** — one line.
+- **Do nothing** — one line. Always include this one.
+
+## What we chose, and why
+
+Chose **Option B**, because …
+
+The "because" is the whole point of the file. A record without it is a note
+saying what happened, and in six months you will not be able to tell whether
+the reasoning still holds.
+
+## What follows
+
+**Good:**
+- …
+
+**Bad:**
+- …
+
+Both lists. A decision with no bad column was not a decision, it was a
+preference.
+
+## What would make us revisit this
+
+The thing that would have to become true. If you cannot name one, say so.
+```
+
+---
+
+## Numbering
+
+The number comes from the check, not from counting:
+
+```
+formwork/check/checks/decision-ids --next .
+```
+
+**Do not count the files.** Gaps are allowed, and counting collides with a
+number that is already taken. Nobody
+assigns it by hand and nobody guesses.
+
+Gaps are fine. **Renumbering is never fine**, because references break quietly.
+
+## Superseding
+
+Do not delete and do not rewrite. Change the status to say it is superseded,
+naming the number of the record that replaces it, and
+leave the rest alone. The old reasoning is the useful part.

formwork_cli/kit/templates/predictions.md

@@ -0,0 +1,54 @@
+# Predictions
+
+**The challenger writes this before anybody proposes anything.**
+
+It is the file the whole round rests on. A prediction written after the answer
+is not a prediction, it is agreement.
+
+Save it as `docs/rounds/<name>/predictions.md`.
+
+---
+
+## What I expect to go wrong
+
+One line each. Be specific enough to be wrong.
+
+**Bad:** it might not scale.
+**Good:** past ten thousand rows the list screen will take more than two
+seconds, because nothing pages it.
+
+- 
+- 
+- 
+
+## What would show me I was wrong
+
+For each one above, what result would change your mind.
+
+This is the part people skip, and skipping it is how a prediction becomes a
+thing to argue about later instead of a thing to check.
+
+- 
+- 
+- 
+
+## What I think this round will decide
+
+Your guess at the outcome, before you have read anybody else's work.
+
+Write it even when you are unsure. Especially then.
+
+## What nobody has asked
+
+The question you expect to be missing from every file in this round.
+
+## How confident am I
+
+Plainly. "Fairly sure" and "guessing" are both useful and honest. A number you
+invented is not.
+
+---
+
+**When the round is over, come back and mark each prediction.** Right, wrong,
+or never tested. That record is worth more than the round itself, because it is
+the only way anybody learns whether this challenger is any good.

formwork_cli/kit/templates/report.md

@@ -0,0 +1,52 @@
+# Report
+
+What comes back when the work stops.
+
+**Scale it.** A one-line task gets a three-line report. The full list below is
+for a checkpoint.
+
+---
+
+## What changed
+
+Each file, one line on why.
+
+## What was run
+
+Every command that wrote something to disk. Installs, generated files,
+migrations, anything that touched the world outside this repository.
+
+## The check
+
+The full result of `formwork check`, named as the whole thing rather than a
+part of it.
+
+If it is red, say so first. A red gate is the headline, not a footnote.
+
+## Git status
+
+Pasted, so you can see nothing was staged.
+
+## The three that matter
+
+Everything above is routine. These are what you are actually reading for.
+
+- **Done but not asked for** — and why.
+- **Asked for but not done** — and why.
+- **Wrong in the brief** — anything that turned out not to match the files.
+
+Work that followed the brief exactly needs no defence. What you are scanning
+for happens at the edges of an instruction, and only these three show it.
+
+---
+
+## The task version
+
+```
+Renamed foo -> bar in parser.py and its two tests.
+Gate green.
+Nothing staged.
+Nothing unasked, nothing skipped, brief was accurate.
+```
+
+Four lines. Still answers all three.

formwork_cli/kit/templates/round.md

@@ -0,0 +1,77 @@
+# Round record
+
+What comes out of several agents arguing about one question.
+
+A file in the repository, not a chat summary. You will read it months later.
+
+---
+
+```markdown
+---
+question: the one thing this round was called to settle
+date: 2026-09-12
+lead: who ran it
+participants: [who argued]
+---
+
+# Round 004. The question in one line
+
+## What is proposed, and who proposed it
+
+Every part attributed to whoever put it forward.
+
+Attribution is not politeness. Being able to follow any position back to its holder, and to the grounds they
+held it on, is how you come to read the team.
+
+## Where we disagreed
+
+Per disagreement: the argument on each side, the evidence each of them carried,
+the resolution, and **whether whoever lost was convinced or simply overruled.**
+
+Where a participant shifted position, record what shifted it.
+
+**An empty section here means the round failed.** Agreement with no friction is
+the normal failure, not the normal success. Say what you did about it.
+
+## What we turned down, and why
+
+This is the section that stops a future round proposing the same thing again.
+
+## Still open, for you
+
+What the team could not settle, or should not have. Do not resolve these to
+look decisive.
+
+For each: the question, both positions, and what changes depending on the
+answer.
+
+## What this costs
+
+- What it makes harder.
+- What it rules out later.
+- What fails quietly.
+- Who maintains it in six months, and what they will have forgotten.
+
+## What the round itself cost
+
+Money, if you can read it from the tool. Time. How many exchanges.
+
+Never estimate a figure you were unable to observe. State which quantities you
+counted, and which stayed out of reach.
+```
+
+---
+
+## Before the round starts
+
+The challenger writes its predictions **first**, before reading anybody else's
+work — what each participant will propose, where each will be weak, and what
+the group will settle on without being pushed.
+
+Afterwards it records what it got right and what it got wrong.
+
+Reading somebody's work shapes any objection composed afterwards. Predictions
+escape that. One that turns out accurate shows the weakness was built in rather
+than accidental, which is a much stronger result.
+
+This ordering is checkable and will be checked.

formwork_cli/kit/test_install.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Prove the installer keeps its three promises, and refuses when it should.
+
+The installer's promises are the reason anybody will run it on a project that
+already has work in it:
+
+    it never needs a clean working tree
+    it never moves or deletes a file
+    it never demands a document
+
+A promise nobody has tried to break is not evidence, so each one is tried here.
+
+Python 3, standard library only, no dependencies.
+"""
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+INSTALL = os.path.join(HERE, "install")
+results = []
+
+
+def check(name, got, want, output=""):
+    ok = got == want
+    results.append(ok)
+    print("  [%s] %-52s expected %s, got %s"
+          % ("pass" if ok else "FAIL", name, want, got))
+    if not ok and output:
+        for line in output.strip().split("\n")[:8]:
+            print("        %s" % line)
+
+
+# Every test runs the real installer, and the real installer writes a
+# fingerprint record outside the project. Without this the suite wrote
+# twenty-one records into the developer's own home directory, one per test.
+STATE = tempfile.mkdtemp(prefix="fw-test-state-")
+
+
+def install(project, *args):
+    env = dict(os.environ)
+    env["FORMWORK_STATE_DIR"] = os.path.join(STATE, os.path.basename(project))
+    p = subprocess.run([sys.executable, INSTALL] + list(args),
+                       capture_output=True, text=True, cwd=project, env=env)
+    return p.returncode, p.stdout + p.stderr
+
+
+def project(**dirs):
+    """A throwaway project. dirs maps a path to its contents, or None for a dir."""
+    d = tempfile.mkdtemp(prefix="fw-install-")
+    for rel, content in dirs.items():
+        full = os.path.join(d, rel)
+        if content is None:
+            os.makedirs(full, exist_ok=True)
+        else:
+            os.makedirs(os.path.dirname(full), exist_ok=True)
+            open(full, "w", encoding="utf-8").write(content)
+    return d
+
+
+def tree(root):
+    out = {}
+    for dirpath, dirnames, filenames in os.walk(root):
+        for fn in filenames:
+            full = os.path.join(dirpath, fn)
+            out[os.path.relpath(full, root)] = open(full, encoding="utf-8").read()
+    return out
+
+
+print("A fresh project")
+p = project(**{".claude/": None})
+code, out = install(p)
+check("wires a project that has .claude/", code, 0, out)
+check("wrote .formwork.toml", os.path.exists(os.path.join(p, ".formwork.toml")), True)
+settings = os.path.join(p, ".claude", "settings.json")
+check("wrote .claude/settings.json", os.path.exists(settings), True)
+check("and it calls the guard",
+      "formwork/guard/git-boundary" in open(settings).read(), True)
+
+print("Running it twice")
+before = tree(p)
+code, out = install(p)
+check("second run is happy", code, 0, out)
+check("second run changed nothing", tree(p) == before, True, out)
+
+print("It does not need a clean working tree")
+p = project(**{".claude/": None, "src/half-finished.py": "x = 1  # mid-edit\n",
+               ".git/HEAD": "ref: refs/heads/main\n"})
+code, out = install(p)
+check("installs with uncommitted work sitting there", code, 0, out)
+check("did not touch the work in progress",
+      open(os.path.join(p, "src", "half-finished.py")).read(),
+      "x = 1  # mid-edit\n")
+
+print("It adds, and never removes")
+p = project(**{".claude/settings.json": json.dumps({
+    "hooks": {"PreToolUse": [{"matcher": "Bash", "hooks": [
+        {"type": "command", "command": "my-own-hook"}]}]},
+    "somethingElse": {"kept": True}}, indent=2)})
+code, out = install(p)
+check("merges into settings that already exist", code, 0, out)
+after = json.load(open(os.path.join(p, ".claude", "settings.json")))
+commands = [h.get("command")
+            for entries in after["hooks"].values()
+            for e in entries for h in e.get("hooks", [])]
+check("kept the hook that was already there", "my-own-hook" in commands, True)
+check("kept settings it knows nothing about",
+      after.get("somethingElse"), {"kept": True})
+check("added the guard", any("git-boundary" in c for c in commands), True)
+check("kept a copy of the original",
+      os.path.exists(os.path.join(p, ".claude", "settings.json.before-formwork")),
+      True)
+
+print("It demands no document")
+p = project(**{".claude/": None})
+code, out = install(p)
+files = set(tree(p))
+check("wrote only the two things it said it would",
+      files, {".formwork.toml", ".claude/settings.json"}, out)
+
+print("When it cannot tell")
+p = project(**{"src/main.py": "pass\n"})
+code, out = install(p)
+check("no runtime anywhere: refuses rather than guessing", code, 2, out)
+check("and says how to tell it", "--runtime" in out, True, out)
+
+p = project(**{".claude/": None, ".cursor/": None})
+code, out = install(p)
+check("two runtimes: refuses rather than picking one", code, 2, out)
+
+print("An untested runtime is not reported as finished")
+p = project(**{".codex/": None})
+code, out = install(p)
+check("exits 1, not 0", code, 1, out)
+check("and says the word untested", "untested" in out, True, out)
+
+print("It will not overwrite a configuration that disagrees")
+p = project(**{".claude/": None,
+               ".formwork.toml": '[bindings]\nruntime = "cursor"\n'})
+code, out = install(p)
+check("leaves the existing .formwork.toml alone", code, 1, out)
+check("and it still says cursor",
+      'runtime = "cursor"' in open(os.path.join(p, ".formwork.toml")).read(),
+      True)
+
+print("Broken JSON is left alone rather than replaced")
+p = project(**{".claude/settings.json": "{ this is not json"})
+code, out = install(p)
+check("refuses to clobber it", code, 1, out)
+check("and it is untouched",
+      open(os.path.join(p, ".claude", "settings.json")).read(),
+      "{ this is not json")
+
+print("--dry-run")
+p = project(**{".claude/": None})
+code, out = install(p, "--dry-run")
+check("says what it would do", code, 0, out)
+check("and wrote nothing at all", tree(p), {}, out)
+
+print("")
+print("%d passed, %d failed" % (results.count(True), results.count(False)))
+sys.exit(1 if False in results else 0)