Repository setup
What a repository needs beyond proviso init, so that every amendment goes through its check, whoever made it and however.
Run proviso verify in CI
proviso verify tells whether the spec tree on a branch may be the baseline as it stands: either it is what the manifest records and no check is left over, or a coherence check covers the amendment’s final state, with every candidate judged and no finding open; and in either case, no element of the tree is left undecided. It judges nothing itself and needs no agent.
| Exit status | Meaning |
|---|---|
| 0 | the tree may be the baseline |
| 1 | something is still to check: the check is missing or left over, an element is undecided, or a candidate is unjudged, an element stale or a finding open |
| 2 | it could not run, such as for an error in the tree |
Run it wherever the project’s checks run:
- In CI, on every branch and every pull request, not only on the default branch: every target branch holds a manifest of its own. On an amendment’s branch it fails until the check covers the amendment, so make it required where you merge, not for every push.
- In the local checks, through whatever the project already uses, such as make, npm scripts, Gradle or a pre-push hook.
Proviso needs no build tool and calls none; its exit status is the whole interface. Put the binary from the releases on the CI runner’s path, and run:
proviso verify
What it catches. A hand edit committed straight to the target, or a merge that skipped acceptance, turns the target red: its tree no longer matches the manifest, and no check covers it. The remedy is the skipped step: check the amendment on the target and accept it there.
What makes it a gate. CI alone only detects. With pull requests, branch protection that requires the CI check stops an unchecked amendment before the merge. Teams that merge directly get detection only. A git hook is no gate either: a clone does not install it, and it can be skipped; an agent host’s hook fires only inside that host.
Trunk-based teams keep an amendment’s branch short: the tree change waits on it only until it is built and accepted. Whatever the trunk changed meanwhile, verify reports as stale, and the check looks at it again.
Write the engineers’ notes
The files in .proviso/ belong to the engineers. proviso init writes stubs and never touches them again.
build.md, for the skills: the commands that build the system, run its unit tests and run its acceptance tests, in that order; how to run the acceptance tests of a list of element identifiers, if your tests are named so that they can be selected, which lets a build run only the tests an amendment concerns until its last round; the commands of your checks, which acceptance runs, naming the one that runs the acceptance tests, so that acceptance can let the build’s full run stand when the merge changed only the spec tree; skips that are expected; Proviso’s command, if it is notprovisofrom the path, as a command rather than a path, so that it can build Proviso as it runs it; where the tests are, as folders, files or name patterns, which the mutating agent ofproviso-mutatemust never read; the folder that keeps the records of mutation runs, if you keep them, which belongs in.gitignore; the lineAcceptance: pull requestif acceptance goes through one; and your convention for commit messages, if it is not Conventional Commits withdocs(spec):for edits of the spec tree. A commit convention is working practice, like your commands, so yours wins.tester.md, for the testing agent: how the acceptance tests are written, named after the elements they check, run and kept fast, and commit conventions.coder.md, for the coding agent: code conventions, commands, and commit conventions.
Notes hold working practice only. A decision about the system, such as a library to use or a limit to keep, is a constraint in the spec tree, where the element diff and the check see it. Where notes contradict the context pack, the pack wins. The checking agent gets no notes, so that nothing steers its judgement.
Commit what Proviso installs
Commit the installed skills and agent definitions in .claude/, so that the whole team works with the same ones. Do not edit them: Proviso owns them, and they match the version of Proviso that installed them. Keep that version on everyone’s path and in CI. proviso version, run in the repository’s root, names every one that another version installed.
Keep the tree readable everywhere
-
Keep the tree beside the code, in the same repository. One amendment is then one branch and one history, and the agents find tree and code in one checkout. A git submodule would split every amendment into two repositories, two commits and a pointer update.
- Run
proviso initin the repository’s root. It refuses anywhere else, and puts the spec tree inproviso/. - Keep the settings
initwrites intoproviso/..gitattributeschecks the tree out with line feeds on every platform, aslintrequires;.markdownlint.jsoncmakes markdownlint accept the notation. - No symbolic links in the tree.
lintnever follows one and stops instead. - Names starting with a dot are skipped: a hidden file never holds spec content.
- Elements cannot be shared between trees, and a system spanning several repositories is not supported yet.
- Keep the checkout outside a synced folder, such as OneDrive, Dropbox or Google Drive. A sync tool and git get in each other’s way: conflicted copies inside
.git, files locked while they upload, changes that arrive late. Proviso reads a synced file as the file it holds, but the repository is safer where only git moves its files.
Conflicts in the manifest
A conflict in proviso/manifest.sum means two amendments met. Never resolve it by running proviso manifest: that would record a tree nobody checked. Take the amendment’s side, and let the check show what the two did to each other; proviso-accept does exactly that.