Commands

Every command of proviso, with what it is for, its options and its exit statuses. Engineers run help, init, update, version, lint, diff, impact, verify and show; the skills run all of them, pack, judge, manifest and rehome included.

Every command but help, init, update and version runs anywhere inside the repository and works on the nearest spec root. The commands that compare with the baseline, manifest, diff, impact, pack, judge, verify and rehome, run only on a tree that lint finds no error in, and exit with 2 otherwise. show reads the tree as lint does but runs none of its checks, so it works in the middle of an amendment too.

The exact behaviour of each command is specified in Proviso’s own spec tree: the command line contract, with every option, exit status and JSON format, and the feature linked under each command below, with every rule and its examples.

help

proviso help

Prints one page naming every command and option; proviso --help and proviso -h do the same. proviso without a command prints the page to standard error and exits with 2. Every command refuses an argument it does not take, and proviso a command it does not know, with one line on standard error that points to proviso help; it then exits with 2, having checked and written nothing.

Exit status Meaning
0 the page was written
2 an argument was given, or proviso was run without a command or with an unknown one

Specified in cli/features/help.md.

init

proviso init

Writes the files a repository needs: the start of a spec tree and its settings, the skills, the agent definitions, and stubs for the engineers’ notes. It never replaces an existing file, and says file by file what it wrote and what it skipped, so a second run writes only what is missing. It runs only in the root of a git repository.

Exit status Meaning
0 every file is in place
2 a file could not be written, or the directory is not a repository’s root

Specified in install/features/init.md.

update

proviso update

Brings the skills and agent definitions to the version of the binary, after an upgrade. Each skill and agent carries the version that wrote it; update writes one that is missing, replaces one written by an older version, by a local build or with an unreadable stamp, and leaves one of its own version or a newer one alone, warning about a newer one. It says file by file what it wrote, updated and skipped. It touches nothing else: the spec tree, its settings and the notes in .proviso/ stay as they are.

A skill or agent you changed by hand is replaced without a question. Copy it first if you want to keep your changes; your own notes belong in .proviso/, which update never touches.

update runs only with a release, only in the root of a git repository, and only where init has installed something.

Exit status Meaning
0 every skill and agent is in place
2 a file could not be written, the binary is no release, the directory is not a repository’s root, or nothing is installed

Specified in install/features/update.md.

version

proviso version

Prints two lines: Proviso’s own version, which follows semantic versioning, and the version of the Proviso Model it writes, a whole number. It also reads every older model version from the oldest it still supports: a change that only adds to the notation raises the model version, and a tree accepted under an older one reads as it did, without a migration. The first acceptance with a newer release writes the manifest under its model version, after which older releases refuse the tree.

proviso 0.1.0
model 1

A local build through the Taskfile names the next patch after the latest release, such as 0.1.1-dev; a build given no version says dev.

Run in the root of a git repository, it also checks what init installed there, and warns on standard error about every skill or agent that is missing, carries no version stamp or more than one, or was installed by another version, naming the model version that one writes where it can tell; and about a proviso/manifest.sum that is missing, cannot be read, or records a model version it does not read, or none, naming the model versions it reads. Silence means everything fits. Anywhere else it prints a hint instead. It never changes a file.

Exit status Meaning
0 the version was written, warnings or not
2 an argument was given

Specified in install/features/version.md.

lint

proviso lint [--json]

Checks the spec tree against the notation: layout, identifiers, the fields and sections of each element, rule blocks, Examples tables and glossary entries. It reports errors, and asks about every undecided place and about every unmarked word in a rule block that is a term of another capability. It never writes the tree.

Exit status Meaning
0 no error
1 at least one error
2 lint could not run: no spec root was found, a file of the tree cannot be read (a folder where the layout lists a file counts), or the manifest records a model version lint does not read, or none

Specified in the features of lint.

diff

proviso diff [--json] [--since <revision>]

Writes the element diff: what the amendment added, changed, removed, or changed through a dependency, compared with the baseline, with the text of each added or changed part as it stands now and the former text of what changed, so that an added Examples row can be told from the others. It lists the elements not to be built yet, because they hold an undecided place. --since <revision> compares with the tree at that git revision instead.

Exit status Meaning
0 the tree is as the manifest records it
1 the element diff lists at least one element
2 the command could not run

Specified in baseline/features/diff.md.

impact

proviso impact [--json]

Writes the candidates of the amendment’s impact set: the existing rules and invariants it may affect without having edited them, each with the reasons it is one.

Exit status Meaning
0 the candidates were found, whether there are any or none
2 the command could not run

Specified in coherence/features/impact.md.

pack

proviso pack [--json] [--since <revision> | --element <identifier>]

Writes the context pack of the amendment: the system, the element diff, what the amendment note says the amendment leaves out, and every element needed to read it. --since <revision> writes the pack of what changed since that revision, for an agent’s later round. A note that is not a readable file in UTF-8 stops it, rather than drop out of the pack. --element <identifier> writes the pack of that one element as the tree holds it, under # Element, for a test written outside any amendment. Lint runs first, as for every baseline command; beyond what lint checks, it reads neither the manifest, the amendment note nor git history.

Exit status Meaning
0 the pack was written
2 the amendment note could not be read, --element names no element of the tree, or the command could not run

Specified in baseline/features/pack.md.

judge

proviso judge < result.json

Records a check result, read from standard input, in proviso/.coherence.json. A result is either a check, the checking agent’s judgements and new findings, or the engineer’s decisions on recorded findings, never both. Proviso numbers the findings and adds the fingerprints of what the check covered. A damaged coherence file is reported before anything wrong with the input.

Exit status Meaning
0 the result was recorded
1 the result was refused, and nothing was recorded
2 the coherence file could not be read or written, or the command could not run

Specified in coherence/features/judge.md.

verify

proviso verify [--json]

Tells whether the tree may become the baseline as it stands: either it is what the manifest records and no coherence file or amendment note is left over, or the coherence check covers the amendment’s final state; and in either case, no element of the tree is left undecided. It lists each problem: a check missing, a coherence file or note leftover, an element undecided, a candidate unjudged, an element stale, a finding open. A coherence file it cannot read stops it before anything is reported.

Exit status Meaning
0 the tree may become the baseline
1 at least one problem
2 the coherence file could not be read, or the command could not run

Specified in coherence/features/verify.md.

show

proviso show <query> [--in <capability>] [--json]

Shows the elements an identifier or name stands for, as you meet it in the tree: an identifier such as lint.run.exit, a term or one of its aliases such as spec tree, or a contract element or parameter as a rule writes it in backticks, such as diff.since. Identifiers and backtick names match exactly; terms match as lint compares them, so case and spacing do not matter. Nothing else matches: no part of a name, and no heading. Quote a name of several words for the shell: proviso show "spec tree".

Each element comes with its text as the tree holds it, under a frontmatter naming its identifier, type, heading, file and line, and the element it belongs to (parent), such as a rule’s feature. A name can stand for one element in each of two capabilities, so the result is a list: every match, in the tree’s order. --in narrows it to one capability, named by its folder, and the system level; --json writes the same as JSON.

Exit status Meaning
0 at least one element was shown
1 the query names no element
2 no query, --in names no capability of the tree, or the tree could not be read

Specified in query/features/show.md.

manifest

proviso manifest

Records the tree as the baseline in proviso/manifest.sum, and removes the coherence file and the amendment note, whatever stands under their names. Acceptance runs it; running it by hand records a tree nobody checked.

Exit status Meaning
0 the manifest was written, and the coherence file and the note removed
2 the manifest could not be written, the coherence file or the note could not be removed, or the command could not run

If a removal fails, the written manifest stays, and verify reports what is left over.

Specified in baseline/features/manifest.md.

rehome

proviso rehome [--write [--mentions]] [--json] [--rename <old>=<new>]...

Gives the elements that moved to another capability, or to the system, or whose identifiers name no place, the identifiers of their place. An identifier whose first segment names another place than the capability the element stands in, or system, is renamed to name it, keeping the rest: baseline.impact.events in the capability coherence becomes coherence.impact.events. An identifier whose first segment is neither system nor a capability’s identifier, such as a contract’s name alone, gets its place put in front: okf-get in the capability access becomes access.okf-get; lint asks about such an identifier as identifier-unhomed. With --rename <old>=<new>, given once for each such element, the engineer gives an element of the plan another new identifier than the one derived, such as --rename checks.run=coherence.run; the new identifier must be well-formed and start with the element’s place, or the run is refused, and it is checked for collisions as a derived one is. Without --write it only lists the renames, the collisions that refuse them and the mentions of the old identifiers, and changes nothing. With --write it renames every anchor, hand-over, inline link, autolink, link reference definition and question tag that names an old identifier, and writes the manifest of the rewritten tree in the same step, so the tree is again what the manifest records.

A mention is a code span that holds nothing but an old identifier, outside rule blocks and fenced blocks, such as in an Examples cell or a Rationale. It may refer to its element or be data, so the plan lists each line holding one, with its file, line, how often it stands there, and the element holding it; it is renamed only when picked. With --write --mentions, rehome reads a mention list from standard input, a JSON object whose mentions are items of the plan’s own list, and renames every mention of that identifier on each line named. A list that is no mention list, or names a line the plan does not list, refuses the run. An identifier in plain text or a fenced block is left as it is.

It runs only on a tree that is what the manifest records, with no coherence file or amendment note beside it: after an amendment is accepted, never during one. It renames all or nothing: one rename that would take an identifier refuses the run, and so does one file it cannot open for writing. The code, tests and documents beside the tree are the engineer’s; the skill proviso-rehome carries the renames into them.

Run rehome --write only through the skill proviso-rehome. The command renames the tree and the manifest, nothing else: run by hand, it leaves the code, tests and documents beside the tree naming the old identifiers, and the two no longer match. The skill finds those names, shows them to you with the plan, and renames them in the same commit.

Exit status Meaning
0 the renames were planned, any or none, and written with --write
1 a rename would take an identifier; nothing was written
2 the tree is not what the manifest records, a coherence file or note lies beside it, a file could not be opened for writing, the input of --mentions or a value of --rename could not be taken, or the command could not run; nothing was written

Specified in upkeep/features/rehome.md.


This site uses Just the Docs, a documentation theme for Jekyll.