How each check is made
How each check is made, and by which command:
| Check | How | Command |
|---|---|---|
| One key twice | the file is read as text, and the keys of each object are counted | sheriff validate |
| The schema | the file is validated against the schema with a JSON Schema validator | sheriff validate |
| Sids, ids, terms, data records | every sid, id, term and data record node's name is collected and counted, a term's and a data record node's name in lower case; the part each term node stands in is looked up | sheriff validate |
| Addresses | the addresses are computed in memory and compared with what is committed | sheriff validate |
| Confirmations | the latest line for the fingerprint of the wording of each checked node outside the SpecSheriff guidelines the project takes is looked up in the confirmations, and the owner it names is compared with the node's owner | sheriff validate |
| The archive | each sid the commit removes from the specification is looked up in the confirmations, and one a confirmation was ever given for is looked up in the archive, with the reason for its removal; one never confirmed is refused where it stands in the archive | sheriff validate |
| Links and citations in the nodes | every outgoing link's target is resolved against the sids that exist, and the citations in every node are read and set against the links it makes; a § followed by a sid and then by no lower-case letter or digit cites it, and one followed by anything else, up to a space, a comma, a semicolon or a closing parenthesis, is a citation by an address |
sheriff validate |
| Links between terms | the kind of the node at each end of every outgoing link is looked up and set against the link's type | sheriff validate |
| Headers, their indexes, incoming links | every domain's files are read for its header; the headers' indexes and the incoming links are rebuilt in memory and compared with what is committed | sheriff validate |
| Capitals | the title, text and reason of every checked node are read for three words or more in capitals, each of two characters or more, separated only by spaces or tabs, anything in backticks or double quotation marks left out | sheriff validate |
| Sections | the children of every checked section, and those of each section inside it, are read for a node that counts as a rule (§s-7445ahgjck2aefg) | sheriff validate |
| Consumes and exempts links, cycles among the domains | each consumes link is read for a domain's header at its start and a section of another domain at its end, each exempts link for a node of project.json at its start and a rule or a section at its end, and the domains are walked along the consumes links for a domain those links lead back to |
sheriff validate |
| Levels | the level each header names is looked up in the list the project's own guidelines hold | sheriff validate |
| Data record variants | each variant's refines link is resolved to the data record it refines; the fields the variant answers to are compared with those the nearest data record up its refines links names as choosing it; each value it answers to is looked up in the list of values of the field it answers for and in the lists rules of domains define for that field, each such rule's refines link resolved to a data record of contracts naming the field as choosing its variant, and a value found in two of those lists or in none is refused; the part the variant stands in is compared with the part of the node declaring its value; the fields the variant declares are compared with those of the data records up its refines links, the fields their fields of type variant hold included, and the fields of type variant along those links are counted; the values each variant answers to are compared with those of every other variant answering to the same data record's choosing fields | sheriff validate |
| Identifiers | the data record each field of type identifier of names is looked up, and the field that data record names as identifying it is looked up among its fields; where that field is itself an identifier, the data record it names is followed in the same way until a field of another type is reached, and a data record reached twice is refused | sheriff validate |
| Values of a field of type one of | the values of each field of type one of are collected from its own list and from the lists rules of domains define for it, and a field holding none is refused | sheriff validate |
| The SpecSheriff guidelines | outside the repository they are written in, a spec.json or a tools.json under specs/_guidelines/, or any file under specs/_schema/, is refused |
sheriff validate |
| Appendices and a project's own guidelines | the outgoing implements and refines links of each node but a section are resolved, and the part of the node each names is read; the name of each file of the technical appendix but stack.json and debt.json is looked up among the domains |
sheriff validate |
| Tags | every symbol of the system's code is read for its tag, an inner symbol covered by the one it stands in, and a category exempt by where it lives is not read at all; the commit's changed lines are mapped onto the symbols they fall in, a line holding a tag, before the commit or after it, onto the symbol the tag stands on, and a symbol whose every changed line holds no tag and differs from the line it replaces only in a comment, in the sid a citation names or in an identifier the commit renames throughout counts as unchanged; the sid of every tag is looked up among the nodes, and that of a tag on a changed symbol among the checked ones | sheriff binding |
| Tests | every test is read for the sid it carries, resolved against the rules and the terms, and the tests whose text the commit changes against the checked ones; the sids of the tags on the changed symbols are looked up among the sids every test carries | sheriff binding |
| Lists of code and tests, symbols, lists | the tags and the sids the tests carry are collected across the repository and compared with the metadata, and the members of a list with the declaration it names | sheriff binding |
| Addresses outside the specification | the files the repository keeps — tracked by git, or new and not ignored — outside specs/ and the tools are read for a part's name followed by a place, in any case and whether or not it names a node now |
sheriff binding |
| Generated copies | the files the technical appendix lists for the types and runtime checks (§s-pvzms7d8kxb8dk2) are generated in memory and compared with what is committed, or, while a data record node is unchecked, compared with what the last commit holds, each such node reported; a list naming a file of another extension or a path outside the repository, two rules of the stack each defining such a list, a name that cannot be generated (§s-suv42g8r3ra2h6b), and a data record holding two fields of type variant, its inherited ones counted, are refused | sheriff binding |
| Drift | the history of the node is compared with the history of the files in its metadata, a renamed file read under both its names | sheriff binding |
| Implementation | each checked rule outside the SpecSheriff guidelines, project.json and debt.json is looked up among the sids the tags on the system's code name and among those the tests carry, a test its framework is told to skip left out; a rule linked to it by implements links, followed from it to the rules implementing it and from those in turn, counts for it; one lacking a tag or a test, and not exempted by an exempts link to it or to a section it stands under, is reported, naming what it lacks |
sheriff binding |
| Citations outside the specification | each sid in the code, the tests and the documents is resolved, the archive's included, and a number naming a node refused | sheriff citations |
| Before an edit | the edit is applied to the file in memory and its changed lines are mapped onto the symbols as the Tags row maps them; the tags of each changed symbol are looked up among the sids the tests of the working tree carry, the edited file as it would stand included, and a node the edit leaves checked is looked up in the confirmations as the Confirmations row does; an edit of specs/_confirmations.jsonl is refused whatever it changes, since sheriff confirm records a confirmation and its withdrawal (§s-v4qus7raqnwzneb) |
sheriff guard |
| The message | the sids in the message are resolved and set against the tags on the changed symbols, and the kind of each node they name is looked up to refuse a domain's header or a section | sheriff message |
| The review | a runner reads the commit's change against the nodes it names | sheriff review |
| The tests | they are run | the project's test command, from the pre-push hook |
The links it makes
- implements → Where an agent writes, the checks run at each of its edits
- implements → What is checked, when, and what a failure costs
- cites → The structure of the specification is defined by its schema
- cites → A node is one rule, and a section holds rules
- cites → Where the types and runtime checks generated from the data records are written
- cites → What a data record node generates
- cites → Each value choosing a data record variant is declared once
- cites → How a confirmation is recorded
- cites → The test comes before the code
- cites → A checked rule is implemented or exempted
- cites → A link carries its type
- cites → The technical appendix stands beside the base specification
- cites → The nodes are the specification
The links made to it
The decisions taken on it
- Problem
Nothing refused a file whose object holds one key twice. JSON Schema leaves the behaviour of such a document undefined, so it escapes the check that it matches its schema (§s-eferktypcj7njt5), and a tool reading it keeps the last of the two values alone.
- Ruling
The owner: the check of the specification refuses it, so a commit cannot carry it.
- Problem
Five checks of the base's table had no row here, so no rule said which command makes them, and several rows did not say all their check does.
- Ruling
The owner: every check of the base's table has its row and its command, the new checks of terms, of names whatever their case and of capitals from three words included, so that the rule on the commands can refer to this table.
- Problem
The check of data record variants checked a value only where its choosing field held a list of values, so a variant whose field held none passed with any value; nothing held a variant to the domain declaring its value, and the fields a field of type variant holds were not counted among those a variant inherits.
- Ruling
The owner: before the first release, 0.1.0, the tools read such values from the choosing field's own list alone, refuse a value not found there, and hold a variant to the part of the data record holding that field; how a project's own guidelines name another place for such values waits past 0.1.0, and the todo stays. Following the rows of §s-jau82aq9juv9zzh on variants, the row says all the check does.
- Problem
The check of data record variants read a value from its choosing field's own list alone, held a variant to the part of the data record, and counted no fields of type variant, and no check followed an identifier to the field it takes its type from.
- Ruling
Following the owner's rulings of that day: the row reads the lists rules of domains define for a field of a data record in contracts (§s-xfu2gpzddjnmgks), holds a variant to the part declaring its value, and counts the fields of type variant; a row follows each identifier to the field identifying its data record. The todo on the other place is settled.
- Problem
No row looked for a field of type one of holding no value, or followed an identifier past the first identifying field.
- Ruling
Following the two rows the base's table of checks gained that day: the identifiers are followed until a field of another type, and the values of each field of type one of are counted.
- Problem
The row of generated copies did not name the refusal of a listed path that leaves the repository, which the tools make because each path of the list is taken from the root of the repository.
- Ruling
Carrying out the owner's rule on where the generated files are written (§s-pvzms7d8kxb8dk2): the row names that refusal.
- Problem
The check before an edit did not look at an edit of the confirmations themselves.
- Ruling
Following the owner's ruling on §s-83ev4wwesbwnhnp: an edit of the confirmations' file is refused whatever it changes, sheriff confirm being what records a confirmation and its withdrawal.
- Problem
The check resolved a test's sid against every node.
- Ruling
Following the owner's ruling on §s-rah8b37kytb682y: a test's sid is resolved against the rules and the terms.
- Problem
No row said how an exempts link is checked or how a rule not implemented is found.
- Ruling
Following the owner's rulings on §s-6fw72j65jkqrfpf and §s-sn6au3vcr9uy5pm: validate reads where each exempts link stands, and binding reports each checked rule within §s-6fw72j65jkqrfpf lacking a tag or a test, a skipped test not counting.
- Problem
No row said that the name of a file of the technical appendix is checked against the domains.
- Ruling
Following §s-vj7ercem526zd6v: each file of the technical appendix but the stack's and the technical debt's is named after a domain.
- Problem
The check compared each kept generated copy with what the nodes produce now, while code generated from the nodes now waits for them to be checked.
- Ruling
Following the owner's ruling on §s-kh8qcd5kxgh9z3j: code generated from the nodes waits until every node it is generated from is checked, no commit changing it meanwhile, and its lag is reported.
The tests bound to it
- skills/tools/test/unit/binding.test.ts · s-4kd2pave7vm4hmd holds a generated copy to what the last commit holds while a data record node is unchecked, reporting the node
- skills/tools/test/unit/binding.test.ts · s-4kd2pave7vm4hmd passes the generated copies the data record nodes produce, and refuses one edited by hand, left behind or missing
- skills/tools/test/unit/binding.test.ts · s-4kd2pave7vm4hmd reads a node's file under every name it had, so that renaming it is no change to the node's text
- skills/tools/test/unit/binding.test.ts · s-4kd2pave7vm4hmd reads the tests and the documents of the tools for citations where the SpecSheriff guidelines are written
- skills/tools/test/unit/binding.test.ts · s-4kd2pave7vm4hmd refuses a name that cannot be generated, and a second list of the files of the types
- skills/tools/test/unit/binding.test.ts · s-4kd2pave7vm4hmd refuses a sid in the code, the tests or the documents that names no node, the archive's included, and a number naming a node
- skills/tools/test/unit/code.test.ts · s-4kd2pave7vm4hmd reads a Python test marked to be skipped or expected to fail as skipped
- skills/tools/test/unit/code.test.ts · s-4kd2pave7vm4hmd reads a TypeScript test its framework is told to skip, by its call or by its options, as skipped
- skills/tools/test/unit/gates.test.ts · s-4kd2pave7vm4hmd reads the tests as the edit would leave the working tree
- skills/tools/test/unit/json-text.test.ts · s-4kd2pave7vm4hmd finds a key an object holds twice, naming the key and both lines
- skills/tools/test/unit/json-text.test.ts · s-4kd2pave7vm4hmd finds nothing where every key is held once
- skills/tools/test/unit/json-text.test.ts · s-4kd2pave7vm4hmd refuses text that is not JSON, naming the line