Skip to content

Releases

v0.7.0

Choose a tag to compare

@github-actions github-actions released this 15 Nov 17:47

New

  • The skill proviso-simplify finds 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 through proviso-integrate.
    Run proviso update to 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. A Builds on
    field without a backtick reference is the error builds-on-empty.
    This is model 1; trees of model 0 read as before. Run proviso 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 verify now 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 lint and
    proviso version name the range this binary reads.
  • A ? inside a literal or a backtick reference is a value, as
    lint always took it: proviso diff and proviso verify no longer
    count it as undecided.
  • pack, impact and show write nothing but their output to
    stdout,
    as lint, diff, verify and rehome already promised,
    so a script can read it whole.
  • Every command but init and update promises to leave the git
    repository as it was,
    lint and show included, 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

Choose a tag to compare

@github-actions github-actions released this 13 Nov 17:26

New

  • Lint asks about an identifier that names no place: one whose
    first segment is neither system nor a capability's identifier, such
    as a contract identified by its name alone (okf-get). The new ask
    identifier-unhomed stops 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 rehome puts the place in front of an identifier that
    names no place,
    instead of replacing its first segment: okf-get
    in the capability access becomes access.okf-get, and its member
    okf-get.input becomes access.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-rehome asks 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. Run proviso update to
    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 as customer.id), so proviso-recover and proviso-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

Choose a tag to compare

@github-actions github-actions released this 07 Nov 23:59

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-explain answers questions about your system
    from its spec tree, such as "What does spec tree mean?" or "What
    happens when …?", looking every element up with proviso show and
    naming where each answer stands. It edits nothing. proviso init
    installs it in new repositories; run proviso update to add it to an
    existing one.
  • proviso rehome lists 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 skill proviso-rehome proposes which to rename and
    which to keep.

Fixed

  • proviso-check no 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

Choose a tag to compare

@github-actions github-actions released this 06 Nov 22:15

What's new

The notation

  • A backslash escape works in fields as in Markdown. In a
    Definition, Deviations or Represents field, 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
    Represents field 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-accept checks 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-build stops on an amendment that only rewords
    Rationales:
    there is nothing to build; it goes to proviso-accept
    once checked.
  • The testing and coding agents name the prefix of each commit
    (test: for the tester; feat:, fix:, refactor: or test: 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

Choose a tag to compare

@github-actions github-actions released this 05 Nov 21:45

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,
    diff and impact list the definition and every rule marking it,
    and pack brings 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-accept no longer repeats the acceptance tests the build
    just ran.
    proviso-build reports 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 update to 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

Choose a tag to compare

@github-actions github-actions released this 04 Nov 18:43

What's new

Fixes

  • lint orders 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.
  • lint reads 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 an undecided ask.

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.
  • update reads 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, and update exits with 2. version
    reads such a stamp as update does. 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

Choose a tag to compare

@github-actions github-actions released this 03 Nov 21:42

New

  • The skill proviso-mutate measures 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 update installs 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 --json and proviso pack list the text of each added
    or changed part as it stands now (text, and a Now block before
    each Former block), 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. init never
    overwrites your notes; add the lines yourself if you want them.

Fixed

  • proviso diff --since and proviso pack --since no longer run on a
    spec tree whose manifest.sum names another model version: like
    every other command, they now exit 2 where lint refuses 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, as lint refuses a link on disk; it used to be
    skipped silently.

v0.3.2

Choose a tag to compare

@github-actions github-actions released this 03 Nov 16:09

New

  • proviso rehome gives the elements that moved to another
    capability, or to the system, the identifiers of their place. Without
    --write it lists the renames and any collision; with --write it
    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-rehome carries the same renames into your
    code, tests and documents, shows you every rename before anything is
    written, and commits it all as one refactor:. 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.
  • lint reports 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-rehome lists 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

Choose a tag to compare

@github-actions github-actions released this 02 Nov 19:42

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

Choose a tag to compare

@github-actions github-actions released this 01 Nov 19:26

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.