Repository navigation
v0.3.0
Proviso 0.3.0
Reads the Proviso Model, version 0. The model version is unchanged, so
spec trees written for 0.1.0 and 0.2.0 work as they are.
New: proviso-recover, a spec tree for a system that exists already
Most systems that could use Proviso exist already and have no spec
tree. The new skill proviso-recover writes one from what the system
does, for the business to confirm. Ask Claude Code to recover the
system's spec tree:
- The first run writes
system.mdand proposes the system's
capabilities, with their Goals and the order to recover them in:
first the capability whose words the others use. - Each later run recovers one capability as an amendment of its own,
checked and accepted like any other. - The code decides what a rule says: the tree states what the
system does, whether or not anyone meant it to. Tests give the
Examples, docs the terms and the reasons. Where a test or a doc says
otherwise, the rule stays as built, and a question asks which is
intended. - Behaviour a default decided, such as a library's rounding or an
unset timeout, gets a question of its own. - Nothing is left undecided: a recovered tree holds no
?, so it can
be accepted. What nobody has confirmed is doubted instead, as
questions inquestions.md, the agenda for confirming the tree. - Invariants only from a source: a property the code seems to keep
but no doc states becomes a question, not an invariant. Where reading
leaves a case open, the skill runs the system through its own
interface, in a scratch folder outside the repository, and says which
rows rest on reading alone. - A last amendment ties the capabilities together at system level.
- On request, the skill checks a recovered capability against the
code: the testing agent writes acceptance tests from the tree alone,
and they run against the unchanged code. A failing test is fixed in
the tree, never in the code. The tests stay and pin what the system
does today.
proviso init installs the skill in new repositories. In a repository
set up with 0.2.0, run proviso update: it writes the missing skill.
Changed: the pack keeps the tree's order
proviso pack lists the elements under each heading as the spec tree
holds them: by the path of their file, then by where they stand in it.
Before, it ordered them by identifier, so a contract element's members
reached the agents in alphabetical order instead of the order their
contract gives them, an order that can carry meaning, such as the
fields of a message. Removed elements follow the others, by identifier.
In pack --json, diff now follows the same order. diff and
impact are unchanged.
New: lint asks about another capability's term
Capabilities do not see each other's glossaries, so a rule could use a
term of another capability without lint noticing, and the impact search
would miss the rule when that term changes. proviso lint now asks
(term-foreign) wherever a rule block uses such a term unmarked. Either
the term moves up to the system's glossary and is marked, or the rule
says it in other words. Like every ask, it never fails a run.
Term names are now matched over every glossary at once: the match that
starts first wins, then the longest, and a word is a run of letters,
combining marks, digits, hyphens and underscores.
How names compare is now stated once, in the lint parameter
name_comparison, and applied everywhere lint compares them: white
space at either end does not count, a non-breaking space included; each
run of spaces and tabs counts as one space, and only those join words,
so a non-breaking space between two words no longer does; case is
ignored by Unicode's simple lower-case mapping; and names are compared
in Unicode's composed form (NFC), so a word typed with a combining mark
matches its composed form. A name with punctuation inside, such as
"U.S. law", is now also found unmarked in plain text.
Changed: what diff passes on and how it orders it
Removing a member of a contract element now lists every rule that
refers to that contract element as changed through a dependency, as
adding or changing a member already did. An element changed through a
dependency names its chains in a fixed order, and the lines diff and
pack name as not decided appear in line order, each line once, even
where it holds two undecided places.
Changed: the skills
Run proviso update to get these:
- Integrate:
proviso-integratepasses on every warning of
proviso versionat its start, such as skills installed by another
version. - Writing guide (integrate, recover, check, build): a term's name is
the business's word in its distinct form, such as daily limit
rather than limit, so that it does not claim an everyday word. - Check:
proviso-checknames a finding that repeats one already
closed in the check, and how that one was closed, before bringing it. - Request skill (
proviso-request_<version>.skill.zip): the same
guidance for requesters, asked when a term first comes up, since a
term in a request is expected to stay.
Documentation
The documentation at https://bbak.github.io/proviso/ has a new layout,
with navigation and search. "Writing specs" shows how the elements of a
spec tree relate, as a diagram. "Workflow" and "Getting started"
describe recovering the spec tree of an existing system.