Skip to content

v0.3.0

Choose a tag to compare

@github-actions github-actions released this 01 Nov 19:26
· 417 commits to main since this release

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.md and 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 in questions.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-integrate passes on every warning of
    proviso version at 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-check names 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.