formwork-kit 0.1.0__py3-none-any.whl

formwork_cli/kit/troubleshooting.md

@@ -0,0 +1,247 @@
+# When something goes wrong
+
+Find the message you saw. Every entry says what happened, why, and what to do.
+
+> [!TIP]
+> **`command not found: formwork`?**
+>
+> Everything on this page also works with `formwork/fw` from the top of your
+> project, and that needs nothing installed:
+>
+> ```
+> formwork/fw check
+> formwork/fw record
+> ```
+>
+> **If you did install it and still get this**, pip put the command somewhere
+> your shell does not look. It says so in a warning when it installs. Add that
+> folder to your PATH, or use `pipx install formwork-kit` instead, which
+> handles this for you.
+
+
+
+If your problem is not here, it belongs here. Open an issue with the exact
+message and it will be added.
+
+---
+
+## The gate is red
+
+### `kit-integrity: N protected file(s) differ from the record`
+
+**What happened.** A file that enforces something has changed since the last
+time you recorded it.
+
+**Why.** Either you changed it on purpose, or something else did.
+
+**What to do.** Look at what changed first:
+
+```
+git diff <the file it named>
+```
+
+If you meant it, record the new state:
+
+```
+formwork record
+```
+
+**Why you and not the agent.** Recording says every one of these files is as
+you intend it. An agent that could do that could change a guard and then tell
+the kit it was fine.
+
+### `no fingerprints recorded at ~/.formwork/fingerprints.txt`
+
+**What happened.** There is no record to compare against.
+
+**Why.** A fresh machine, a fresh clone, or you moved `FORMWORK_STATE_DIR`.
+
+The record lives outside your project, one file per project, in
+`~/.formwork/fingerprints/`. It does not travel with a clone, which is the
+point: a record kept beside the thing it describes protects nothing.
+
+**What to do.** Run the installer again. It takes the first record for you:
+
+```
+formwork install --runtime claude-code
+```
+
+### `guard-wired: runtime 'X' is declared, but .../hooks.json does not exist`
+
+**What happened.** Your settings say you use tool X, and the hooks for X are
+not wired up.
+
+**Why.** The kit ships a wiring file for Claude Code only.
+
+**What to do.** Open your agent's page in `formwork/adapters/`. It says what to
+put in that file. Red is correct until then: nothing is guarding you yet.
+
+### `doc-links: N link(s) point at nothing`
+
+**What happened.** A markdown link points at a file that is not there.
+
+**What to do.** Fix the link or create the file. The message gives you the file
+and the line number.
+
+### `generated-current: N generated file(s) are not current`
+
+**What happened.** You edited a role, or edited a generated copy by hand, or
+deleted a role and left its copy behind.
+
+**What to do.**
+
+```
+formwork roles
+```
+
+**If you edited a generated file by hand**, move your change into the source
+file in `formwork/roles/` first. The next regeneration will throw your edit
+away.
+
+**If you deleted a role**, `formwork roles` will not clean up after you. Delete
+the generated copy too, then run it:
+
+```
+rm .claude/agents/<the role>.md
+formwork roles
+```
+
+### `role-shape: N problem(s) across N role(s)`
+
+**What happened.** A role is missing something, or two roles claim the same
+job.
+
+**What to do.** The message names the file and the problem. Every role needs
+four frontmatter fields and five sections. Copy `formwork/roles/TEMPLATE.md` if
+you are unsure.
+
+### `N check(s) present but not executable`
+
+**What happened.** A check file lost its execute permission.
+
+**What to do.**
+
+```
+chmod +x formwork/check/checks/*
+```
+
+**Why this stops everything.** A check that cannot run has not passed. Before
+this was caught, the gate reported green while quietly skipping it.
+
+---
+
+## A command was refused
+
+### `REFUSED by the version-control boundary`
+
+**What happened.** The agent tried to commit, push, merge or something like it.
+
+**This is working correctly.** You do those, not the agent.
+
+**What to do.** Run the command yourself.
+
+**If it refused something read-only**, that is a bug and worth reporting. The
+guard should allow anything that only looks.
+
+**To turn it off for one session:**
+
+```
+FORMWORK_GIT_BOUNDARY=off
+```
+
+### `REFUSED by self-protection`
+
+**What happened.** Something tried to change a file that enforces a rule.
+
+**What to do.** If you meant it, make the change yourself in your editor, then
+record the new state with `kit-integrity --record .`.
+
+**To turn it off for one session:**
+
+```
+FORMWORK_PROTECT_FILES=warn
+```
+
+### `REFUSED: the aggregate is red, so this turn cannot conclude`
+
+**What happened.** The gate is red and the turn tried to end.
+
+**What to do.** Read what the gate said and fix that.
+
+**It gives up after three.** Then it stands aside and says so in capitals, so
+a stuck turn is not stuck for ever.
+
+---
+
+## The installer
+
+### `Cannot tell which runtime this project uses`
+
+**What happened.** There is no `.claude`, `.codex`, `.cursor` or `.gemini`
+folder, so it cannot guess.
+
+**What to do.** Tell it:
+
+```
+formwork install --runtime claude-code
+```
+
+### `more than one runtime is set up here`
+
+**What happened.** You have folders for several tools.
+
+**What to do.** Same as above. Say which one.
+
+### `NOT FINISHED` after installing
+
+**What happened.** It did what it could and stopped.
+
+**What to do.** Read the list it printed. It names the file you need to write
+and the page that tells you what goes in it.
+
+---
+
+## Nothing is being blocked at all
+
+**Check the hooks are wired.**
+
+```
+formwork check
+```
+
+If `guard-wired` passes, the hooks are in place.
+
+**Check the strength setting.** Look in `.formwork.toml`. If it says `warn` or
+`off`, that is why.
+
+**Check your shell.** An environment variable overrides the file:
+
+```
+echo $FORMWORK_GIT_BOUNDARY $FORMWORK_PROTECT_FILES $FORMWORK_GATE
+```
+
+**Check your tool.** Only Claude Code has been watched refusing a real command.
+On the other three, wiring is documented and untried.
+
+---
+
+## Something is being blocked that should not be
+
+**This matters as much as the opposite.** A guard that is wrong about ordinary
+work gets switched off, and then nothing is guarded. Report it: the command you
+ran is all anybody needs.
+
+Meanwhile:
+
+```
+FORMWORK_GIT_BOUNDARY=off
+FORMWORK_PROTECT_FILES=off
+```
+
+---
+
+## Nothing here matches
+
+Run `formwork check` and `formwork demo`. If both look right and the problem
+is still there, it is probably a real bug. Open an issue with the exact message
+and what you ran.

formwork_cli/kit-page/FORMWORK.md

@@ -0,0 +1,182 @@
+# Formwork
+
+A way of running a project with coding agents.
+
+---
+
+## The loop
+
+Everything is one loop. Only the size changes.
+
+```
+BRIEF → WORK → CHECK → REPORT → STOP → you say go → BRIEF …
+```
+
+| Size | How long | The brief is | The report is |
+|---|---|---|---|
+| task | minutes | one line | files changed, 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 | — |
+
+Each one answers four questions: what it produces, what must be true before it
+starts, who says go, and **what would tell us it failed.**
+
+---
+
+## What is blocked
+
+These do not ask you. They refuse.
+
+| Rule | Enforced by |
+|---|---|
+| The agent never writes to version control | `formwork/guard/git-boundary` |
+| One command runs every check | `formwork check` |
+| Every check ships with an input that breaks it | `formwork check` |
+| Every rule is labelled, and names a real check | `formwork/check/checks/rule-labels` |
+| Documents link only to files that exist | `formwork/check/checks/doc-links` |
+| A declared runtime is actually wired up | `formwork/check/checks/guard-wired` |
+| The agent does not quietly alter the kit's own files | `formwork/guard/protected-files` |
+| A turn does not end while the aggregate is red | `formwork/guard/quality-gate` |
+
+> [!NOTE]
+> **The last one refuses three times in a session, then stands aside**, so a
+> genuinely stuck turn is not trapped for ever. Change it with `gate_budget`.
+
+Run them:
+
+```
+formwork check              everything, on your project
+formwork demo  watch each check refuse a broken input
+formwork check --list       what exists
+```
+
+**If you did not install the command**, every one of these works by path
+instead: `formwork/fw check`, `formwork/fw demo`, `formwork/fw roles`. Run
+`formwork/fw` on its own to see the list.
+
+---
+
+## What is advice
+
+Everything else. **46 rules**, in two files.
+
+- `formwork/rules/core.md` — 13. You meet these every day.
+- `formwork/rules/full.md` — 33. Read one when you hit the situation it covers.
+
+> [!TIP]
+> Every rule says what it catches. None of them tells you a story, because the
+> stories belong to somebody else's project.
+
+---
+
+## Some of this will look like fussiness
+
+Several of these rules were learned from failures you have not had.
+
+Each one states what it catches. **If you never hit that, delete it** from
+`formwork/rules/core.md`, so losing a rule is a line in your version control
+with your name on it.
+
+There is no `[rules]` switch in `.formwork.toml`, and a check refuses one if you
+add it. A rule switched off in a settings file disappears quietly. A rule
+deleted from the rules file does not.
+
+A rule you follow without understanding gets dropped quietly later anyway.
+
+---
+
+## Settings
+
+This is the whole file, and the installer writes it for you:
+
+```toml
+[bindings]
+runtime = "claude-code"          # which tool you use
+
+[strength]
+git_boundary = "block"           # block | warn | off
+protect_files = "block"          # block | warn | off
+```
+
+`[strength]` tunes how hard the enforced guards bite. `[bindings]` is your
+setup. There is no third section: see above.
+
+**Two more keys exist and both live in `[strength]`:**
+
+```toml
+aggregate_gate = "block"   # block | warn | off. The turn-end gate
+gate_budget = 3            # how many times it refuses before standing aside
+```
+
+For one session only:
+
+```
+FORMWORK_GIT_BOUNDARY=off
+FORMWORK_PROTECT_FILES=warn
+FORMWORK_GATE=off
+```
+
+---
+
+## Your team
+
+`formwork/roles/` holds 27 roles. Six run the method. Twenty-one do the work,
+grouped into packs.
+
+**All of them are available. There is no switch yet**, and this page says so
+rather than describing one that does not exist.
+
+Adding your own is copying `TEMPLATE.md`, filling in five sections and four
+frontmatter fields. A role missing any of them does not load.
+
+The installer generates them for your runtime. To regenerate after an edit:
+
+```
+formwork roles
+```
+
+---
+
+## What it cannot do
+
+The guards are pattern matching over a command line. They stop the ordinary
+path and not a determined one.
+
+[`formwork/limits.md`](formwork/limits.md) lists exactly what got past an audit, what
+was closed afterwards, and what cannot be closed this way. Read it before
+trusting any of this further than it deserves.
+
+---
+
+## Two things here you will not find elsewhere
+
+**A check that refuses rather than advises.** Most tooling tells you something
+is wrong and lets the work continue. This stops the turn.
+
+**Rules about what counts as evidence.** A figure is reported together with the
+command behind it. Anything unmeasured says so in capitals. A check that nobody has
+watched fail is not treated as proof of anything.
+
+Both came out of real use. Neither has been tried by anybody else yet, and the
+kit would rather say that than imply a crowd that does not exist.
+
+---
+
+## What it costs
+
+Nobody has measured what one round costs in money. Not once. `formwork/COSTS.md`
+says so plainly, gives the part that can be measured for free, and says what
+would establish the rest.
+
+---
+
+## Where to start
+
+[`formwork/first-run.md`](formwork/first-run.md). Fifteen minutes, on your own
+project.
+
+Then [`formwork/loop.md`](formwork/loop.md) for the working loop, and
+[`formwork/round.md`](formwork/round.md) when a decision is expensive enough to
+be worth a round.