Repository navigation
Releases
v0.7.0
New
- The skill
proviso-simplifyfinds where the spec tree could say
the same more simply, such as rules restating one another or a promise
held only in a Rationale, or where its behaviour could be simpler. A
fresh agent that reads only the tree proposes; you decide, and each
proposal you take becomes an amendment throughproviso-integrate.
Runproviso updateto install it. - A contract element can say what it builds on, in the field
- Builds on: `concept-summary`. A rule that refers to the element
is then changed through every change of what it builds on, and the
check is led to it; before, a member made of another contract's
members depended on nothing but the terms it represents. ABuilds on
field without a backtick reference is the errorbuilds-on-empty.
This is model 1; trees of model 0 read as before. Runproviso update
so the skills write the field where it applies.
Changed
- A checked element turns stale when what it rests on changes again.
A rule changed through a contract, once checked, stayed covered when
the contract changed a second time;proviso verifynow reports it
stale, so the check reads it again. A check recorded by an earlier
release may show such elements stale after the upgrade. - Proviso reads every model version from the oldest it still
supports, not only its own. A change that only adds to the notation,
such as a new optional field, raises the model version without a
migration: a tree accepted under an older model version reads as it
did, with the same fingerprints and no new lint error. When a tree's
manifest names a model version outside that range,proviso lintand
proviso versionname the range this binary reads. - A
?inside a literal or a backtick reference is a value, as
lint always took it:proviso diffandproviso verifyno longer
count it as undecided. pack,impactandshowwrite nothing but their output to
stdout, aslint,diff,verifyandrehomealready promised,
so a script can read it whole.- Every command but
initandupdatepromises to leave the git
repository as it was,lintandshowincluded, and to change
nothing under the spec root but what it is for; a command refused
because lint finds an error changes nothing at all. - A stale skill or agent is named with the model version its release
writes ("installed by 0.5.0, which writes model 0"), no longer
"reads".
Upgrading
- When a release raises the model version, upgrade everyone who works
on the tree. The first acceptance with that release writes the
manifest under the new model version, and from then on an older
Proviso refuses the tree, naming the model version it needs. Until
then, an older Proviso on a branch whose tree already uses the new
notation reports it as an unknown field.
v0.6.0
New
- Lint asks about an identifier that names no place: one whose
first segment is neithersystemnor a capability's identifier, such
as a contract identified by its name alone (okf-get). The new ask
identifier-unhomedstops no command, so an amendment that gives a
capability another identifier, or removes one whose elements move
elsewhere, still goes through, and a later rehome repairs what it left. proviso rehome --rename <old>=<new>gives an element of the plan
another new identifier than the one derived, for each element whose
new identifier would be taken or awkward, such as an invariant moved
to the system whose name a system term already holds. The new
identifier must be well-formed and start with the element's place, is
checked for collisions as a derived one is, and works with or without
--write, so you see the plan before anything is written. Before, a
collision stopped the rehome, and the only way on was an amendment.
Changed
proviso rehomeputs the place in front of an identifier that
names no place, instead of replacing its first segment:okf-get
in the capabilityaccessbecomesaccess.okf-get, and its member
okf-get.inputbecomesaccess.okf-get.input. Before, every contract
of a capability identified by its name alone was renamed to the
capability's own identifier, so a tree with such contracts could not
be rehomed at all. An identifier whose first segment names another
place is renamed as before.- The skill
proviso-rehomeasks you for another identifier on a
collision, or when a test name derived from the new one is taken, and
passes it as--rename, instead of stopping. Runproviso updateto
bring it into an existing repository. - The writing guide the skills follow now says that contract
identifiers carry their place too (cash.customer.id, referred to in
rules ascustomer.id), soproviso-recoverandproviso-integrate
no longer write contract identifiers without one.
Documentation
- The mutation report
compares Proviso's own mutants with a mechanical tool: against
Gremlins' 1,100 mutants, the acceptance tests catch 81.2%, the unit
tests 79.9%, and either 86.7%.
v0.5.0
New
proviso show <query>shows the elements an identifier or name
stands for, as you meet it in the tree: an identifier, a term or one
of its aliases, or a contract element or parameter as a rule writes it
in backticks. Each element comes with its text and a frontmatter
naming its type, file, line and the element it belongs to;--json
writes the same as JSON, and--in <capability>narrows the lookup to
one capability and the system level. It reads the tree even where
lint finds errors, so it works in the middle of an amendment.- The skill
proviso-explainanswers questions about your system
from its spec tree, such as "What does spec tree mean?" or "What
happens when …?", looking every element up withproviso showand
naming where each answer stands. It edits nothing.proviso init
installs it in new repositories; runproviso updateto add it to an
existing one. proviso rehomelists the mentions of every identifier it renames
that the notation does not mark, such as an identifier in an Examples
cell, and renames those you pick with--write --mentions, so a
rehome no longer leaves stale identifiers behind for a follow-up
amendment. The skillproviso-rehomeproposes which to rename and
which to keep.
Fixed
proviso-checkno longer misses the amendment itself when a
system-level change splits the check into one run per capability: an
extra run now reads the changed elements against their frames, even
where their capability holds no candidate.
v0.4.3
What's new
The notation
- A backslash escape works in fields as in Markdown. In a
Definition,DeviationsorRepresentsfield, a bracket escaped
with a backslash (\[x]) marks nothing, and an escape within a mark
stands for the character it escapes ([U\.S\. law]), as CommonMark
reads backslash escapes. Nothing else of CommonMark's inline reading
applies to a mark: a character reference stays as written. Rule
blocks are unchanged. - A contract element may represent several terms. When its
Representsfield marks more than one, it depends on each of them: a
changed meaning of any reaches the contract element and the rules
referring to it. Proviso already behaved so; it is now specified and
tested, and the guide to writing specs says so.
Element diff and pack
- One chain per changed element. An element changed through a
dependency now names, for each changed element that reaches it, only
the shortest chain, and of equally short ones the first by
identifiers. Naming every chain grew factorially once glossary
definitions mark each other: eight such entries gave over 200,000
chains (31.5 MB) in one diff, now 122.
Skills and agents
proviso-acceptchecks that the check's record is committed on
the amendment's branch, untracked files included, so the record of a
coherence check is never lost.proviso-buildstops on an amendment that only rewords
Rationales: there is nothing to build; it goes toproviso-accept
once checked.- The testing and coding agents name the prefix of each commit
(test:for the tester;feat:,fix:,refactor:ortest:for
the coder), unless the engineers' notes name another convention. - The testing and coding agents report only what their commits
hold: a scripted edit fails when it matches nothing, and each edit
is checked in the diff before it is reported.
Run proviso update in a repository to bring its skills and agent
definitions to this version.
v0.4.2
What's new
The notation
- A glossary definition may mark the terms it relies on. Write
[term]in a Definition or Deviations field where its meaning rests on
another term; lint resolves the mark, and when that term changes,
diffandimpactlist the definition and every rule marking it,
andpackbrings the marked term along. Marks there are optional.
Brackets within a code span in any field mark nothing. A changed
Deviations field now passes its change on, as a changed Definition
does.
Skills
proviso-acceptno longer repeats the acceptance tests the build
just ran.proviso-buildreports the commit its full run passed
on; when the merge has changed only the spec tree since, such as the
manifest, accept runs your other checks and lets that run stand. Run
proviso updateto install the new skills.
Documentation
- Writing specs
says when a definition marks a term, and why only the terms its
meaning rests on.
v0.4.1
What's new
Fixes
lintorders findings within a line by where they stand. Several
findings of one kind on one line, such as an open term and a?, or
two misplaced anchors, came out in an order that depended on the
kind; they now appear from the start of the line to its end.lintreads no fields of an element of no type. A heading with
an anchor where the layout allows no element is reported once as
element-unplaced; a field under it, such as- Contact: ?, no
longer adds anundecidedask.
The model, stated more precisely
- The spec tree's Markdown is read as CommonMark 0.31.2 with GitHub's
tables, through the terms heading, table and link and the places
Proviso departs from them: a byte order mark at the start of a file
is ignored, and only headings and tables at the top level of a file
count. Rules and rows now state the corners lint already handled: the
label of a fence is the first word of its info string,ID=is an
anchor, only a-list is fields,\|is a pipe in a cell, the
first table after a rule block is its Examples table,[text](makes
no term mark, and placeholder names may use letters of either case. - Only a rule block's marks of an open term hold an element back from
being built. updatereads the stamp of a skill or agent installed as a symbolic
link through the link, but never writes through it or replaces it: a
stale linked file is not written, andupdateexits with 2.version
reads such a stamp asupdatedoes. A folder linked on the way to a
skill or agent, such as a shared skills folder, is the engineers'
setup, which the system's design boundary now names.
Documentation
- Tests with teeth:
the first mutation run on Proviso itself, its 23 survivors, and how
each was decided.
v0.4.0
New
- The skill
proviso-mutatemeasures whether your tests have
teeth. A new agent,proviso-mutator, reads the spec tree and the
code, never the tests, and writes one small slip per rule (a guard
inverted, a refusal skipped, a boundary moved by one), plus a few in
code no rule covers. The skill runs your tests against each slip in a
worktree of its own, reports the share caught and every survivor, and
proposes for each whether it is a hole in the tests, a hole in the
tree or a change nobody could observe. You decide each: holes in the
tests go to the testing agent, holes in the tree become a request for
proviso-integrate. Records of runs are kept only in a folder you
name in.proviso/build.md.proviso updateinstalls the skill and
the agent. proviso pack --element <identifier>writes the context pack of
one element as the tree holds it, under a new heading# Element,
for a test written outside any amendment. It derives no element diff
and reads neither the amendment note nor git history.
Changed
proviso diff --jsonandproviso packlist the text of each added
or changed part as it stands now (text, and aNowblock before
eachFormerblock), so an added Examples row can be told from the
others, not only by its fingerprint.- The checking agent never reads the coherence file, so that a fresh
check does not lean on earlier runs. - The testing agent can also be started by
proviso-mutate, with the
pack of one rule whose tests miss a case. - The notes for the skills,
.proviso/build.md, now also ask where the
tests are and where records of mutation runs are kept.initnever
overwrites your notes; add the lines yourself if you want them.
Fixed
proviso diff --sinceandproviso pack --sinceno longer run on a
spec tree whosemanifest.sumnames another model version: like
every other command, they now exit 2 wherelintrefuses the tree.
The tree at the revision gets the same check. A merge conflict after
the manifest's first line still does not stop them.- With
--since, a symbolic link in the spec tree at the revision now
refuses the comparison, aslintrefuses a link on disk; it used to be
skipped silently.
v0.3.2
New
proviso rehomegives the elements that moved to another
capability, or to the system, the identifiers of their place. Without
--writeit lists the renames and any collision; with--writeit
renames every anchor, hand-over, link fragment and question tag that
names an old identifier and rewrites the manifest in the same step,
so the tree is again what the manifest records. It runs only after an
amendment is accepted, and renames all or nothing.- The skill
proviso-rehomecarries the same renames into your
code, tests and documents, shows you every rename before anything is
written, and commits it all as onerefactor:.proviso update
installs it.
Changed
- An identifier is no longer permanent: its first segment names where
the element stands. Moving an element still keeps its identifier;
rehoming follows after acceptance. lintreports an error for a capability whose identifier has more
than one segment (capability-identifier).- The skills' writing guide says so; only skills that write decisions
into the tree carry it. proviso-rehomelists every mention of an old identifier it leaves in
the tree, telling references from data, and recommends a small
amendment for the references.- The writing guide says where an algorithm goes; the documentation
also names the one case the notation does not cover yet.
Documentation
- The home page and the README state Proviso's design goal: a
specification that stays coherent across many changes, traded for
development speed, and who that trade is meant for. - Repository setup advises keeping the checkout outside a synced
folder, such as OneDrive, Dropbox or Google Drive.
Fixed
- On Windows, a file in a OneDrive (or other cloud-synced) folder is no
longer reported as unreadable for the half minute after it was moved.
v0.3.1
Proviso 0.3.1
Reads the Proviso Model, version 0. The model version is unchanged, so
spec trees written for earlier versions work as they are.
This release narrows what the testing and the coding agent do on their
own initiative. Run proviso update in every repository that uses
Proviso, so that its agents and skills follow these instructions.
The agents build and test only what the pack decides
- The testing agent writes tests for the Examples rows, the
invariants and the contracts' shapes, and nothing beyond them. A case
no row covers is no longer a test of its own: the agent lists it as a
decision the pack did not make, and the spec tree decides whether it
earns a row. Before, the agent derived extra tests on its own, often
for what the platform guarantees, and the suite grew with cases
nobody had decided. - The coding agent adds no handling of its own for a case no rule
names, and lists such a case the same way. - Neither agent tests or handles what the system's Design boundary
takes as given, such as the operating system beneath it.
Decide the design boundary early
What the Design boundary names, such as the operating system, a
database or the network, the agents take as given. The writing guide
that every tree-editing skill carries now asks for it early, with the
border where it stops: which cases stay the system's to decide, such as
a missing permission, and which it takes as given, such as a full disk.
proviso-recover names it when it writes a system frame. Writing
specs and Getting started say the same.
proviso-check notices a chain of ever-finer findings
When successive check runs keep finding finer cases of one concern,
each edit opening the next edge, proviso-check says so and recommends
deciding the concern once: in one element the rules refer to, or in a
line of the Design boundary that names its border.
Proviso's own spec tree
Proviso's tree now states several things its code already did: which
runs the lint exit status covers, what init and update report and
leave behind for a file they could not write, what a regular file and a
symbolic link are on Windows (a OneDrive placeholder is a file, a
junction is a link), and which former text the baseline commands check.
The commands behave as in 0.3.0.
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.