Conformance
An app implements one edition of Pauta, says how fully it conforms (Complete, Core or Partial), and shows both in its
About window. The rules it does not meet are not hidden: each one is an exception, written down once in the app’s pauta.json, shown in the app’s
Pauta window and listed in its user docs. Its conformance is worked out from that list,
never typed in by hand, so the claim and the evidence can’t drift apart.
No app does this yet. The audit in Coding agents and LLMs produces the first list:
its fail and n/a lines are the exceptions.
Complete, Core and Partial
Section titled “Complete, Core and Partial”| Conformance | The app meets… | About says |
|---|---|---|
| Complete | every MUST of its edition, met or not applicable, and every SHOULD, met, not applicable or a recorded deviation | Built to Pauta 4.1.0 · Pauta conformance: Complete |
| Core | every MUST in the same way; one or more SHOULDs are still pending | Built to Pauta 4.1.0 · Pauta conformance: Core |
| Partial | not every MUST: one or more MUSTs are still pending | Working toward Pauta 4.1.0 · Pauta conformance: Partial |
“Built to an edition” keeps its meaning: the app meets that edition’s MUSTs. Core and Complete are the two ways to be built to it; a Partial app is working toward it and says so. MAY rules never count. A deviation, which only a SHOULD can have, leaves the conformance as it is but is always on show: About gives the number of exceptions, and the Pauta window lists every one.
Partial is how an app that already ships says it is on its way: it took up an edition after its first release, or moved to a newer one with new MUSTs. A new app is not released at Partial.
- PAUTA-01 MUST Every app implements Pauta: it names one edition (the
pauta.versionof ABOUT-08) and states its conformance, Complete, Core or Partial, as defined above.- Why: an app that is in the family answers to these rules; saying which ones, and how far, is the first of them.
- Check (code):
pom.xmldefinespauta.versionandsrc/main/resources/com/<app>/pauta.jsonexists. - Reference: no app yet.
- PAUTA-02 MUST The conformance is computed, never stored: one pure helper reads the exceptions and returns Partial
when any MUST is pending, Core when any SHOULD is pending, and Complete otherwise. About, the Pauta window and the
docs page take it from there; the README, which can’t call the helper, is held to it by a test (PAUTA-15).
- Why: One source of truth for each fact. A conformance typed in by hand stays “Complete” after a pending exception is added.
- Check (test): a unit test of the helper (
PautaConformance, or the app’s equivalent) covers all three and shows that deviations and not-applicable entries leave the result alone. - Reference: no app yet.
- PAUTA-03 MUST A new app’s first release is at Core or Complete: the New app checklist’s
MUSTs are release blockers, and recording one as pending does not lift that.
- Check (by hand): the About window of the app’s first release says Core or Complete.
- Reference: no app yet.
Exceptions
Section titled “Exceptions”An exception is one rule the app does not meet as written. There are three kinds, and each one asks for something different.
| Kind | Means | Needs |
|---|---|---|
not-applicable | The rule applies to every app, but its subject does not exist in this one: no tabs to reopen, no setting to sync | A reason |
deviation | A SHOULD only: the app does it differently on purpose, and would make the same choice again | A reason and a decision record |
pending | The app does not do it yet | A reason and an issue |
- PAUTA-04 MUST Every rule of the edition that the app does not meet has an exception, and every exception
names a rule the app does not meet. An unmet rule with no entry is a failed audit, not an exception; an entry for
a rule the app now meets is removed in the same change that meets it.
- Why: Never claim what is not true. The list is the app’s claim; it has to be whole and current.
- Check (by hand): audit the app against its edition (Coding agents and LLMs);
every
failandn/aline is inpauta.json, and no entry is for a rule that passes. - Reference: no app yet.
- PAUTA-05 MUST A rule whose own text or page limits it to apps with a feature (“An app with user data worth
carrying between computers…”, the Tray and background page) needs no entry in an app
without that feature.
not-applicableis for a rule that reads as applying to every app.- Check (code): no
not-applicableentry names a rule whose text or page already scopes it. - Reference: no app yet.
- Check (code): no
- PAUTA-06 MUST A
deviationis a choice, not a gap, and only a SHOULD can have one: a SHOULD is expected unless the app has a stated reason, and the deviation is that reason. It links a decision record indocs/decisions/(DOCS-13) that gives the context, what the app does instead, and what it costs. A MUST the app does not meet ispending, as is any work it has not done yet.- Why: a deviation keeps the conformance; a deviation from a MUST, or missing work called a deviation, would let the app say it is built to an edition it does not meet.
- Check (code): every
deviationentry names a SHOULD, and itslinkopens a file underdocs/decisions/that names the rule’s ID. - Reference: no app yet.
- PAUTA-07 MUST A
pendingexception links an open issue in the app’s repository that names the rule’s ID and edition, “MENU-14 (Pauta 4.1.0)”. Closing the issue removes the entry.- Check (code): every
pendingentry’slinkis an issue URL in the app’s repository. - Reference: no app yet.
- Check (code): every
- PAUTA-08 MUST Each exception’s
reasonis one plain sentence for the person using the app, in English like the changelog: what is different and, for a deviation, what they get instead. No rule text, no class names.- Check (by hand): read each reason in the Pauta window as a user would.
- Reference: no app yet.
The file
Section titled “The file”The exceptions live in one file, bundled with the app so the Pauta window can read it:
src/main/resources/com/<app>/pauta.json. The edition stays in pom.xml (ABOUT-08). Each entry copies the rule’s
level and url from the edition’s rules.json so the app needs nothing else at run time, and
a test keeps the copies honest.
{ "exceptions": [ { "rule": "MENU-14", "level": "MUST", "url": "https://pauta-project.dev/4.1.0/menus/#menu-14", "kind": "pending", "reason": "Some menu rows have no icon yet.", "link": "https://github.com/adriandeleon/<App>/issues/212" }, { "rule": "TABS-06", "level": "MUST", "url": "https://pauta-project.dev/4.1.0/tabs-and-panels/#tabs-06", "kind": "not-applicable", "reason": "<App> has no tabs: it shows one library in one window." }, { "rule": "WIN-06", "level": "SHOULD", "url": "https://pauta-project.dev/4.1.0/window-shell/#win-06", "kind": "deviation", "reason": "<App> opens straight to your library instead of a Welcome page; its empty state names the ways in.", "link": "https://github.com/adriandeleon/<App>/blob/master/docs/decisions/0007-no-welcome-page.md" } ]}- PAUTA-09 MUST The exceptions have one source,
pauta.jsonas above:rule,level,url,kindandreasonon every entry,linkon every deviation and pending entry, one entry per rule.- Check (code): the file exists at that path, and each entry has the fields its kind needs.
- Reference: no app yet.
- PAUTA-10 MUST A test reads
pauta.jsonagainst a copy of the edition’srules.jsoninsrc/test/resources/pauta-rules.jsonand fails when the copy’seditionis notpauta.version, when an entry names a rule the edition does not have, when itslevelorurldiffers from the edition’s, when a rule appears twice, when a deviation names a MUST, or when a deviation or pending entry has nolink.- Why: moving to a newer edition changes levels and retires IDs; the test turns each stale entry into a failure.
- Check (test):
PautaConformanceTest, or the app’s equivalent, runs in the build. - Reference: no app yet.
- PAUTA-11 SHOULD Moving to a newer edition is one change: replace
pauta-rules.json, run the audit again, updatepauta.json, then changepauta.version, the README andAGENTS.mdtogether.- Check (by hand): the change that raises
pauta.versionalso replacespauta-rules.jsonand touchespauta.jsonwhere the audit found something new. - Reference: Move an app to a newer edition.
- Check (by hand): the change that raises
Where it shows
Section titled “Where it shows”The same list reaches three readers: the person using the app, the person reading its docs, and whoever reviews the repository.
- PAUTA-12 MUST In the app: About names the edition and the conformance (ABOUT-09),
and the Pauta window, opened from About, the Help menu and the Command Palette, lists every exception
(Pauta window).
- Check (code):
help.pautais registered and About’s Pauta conformance link runs it. - Reference: no app yet.
- Check (code):
- PAUTA-13 MUST In the user docs: the app’s website has a Pauta conformance page under
/docs/(DOCS-02) with the edition, the conformance and every exception, grouped by kind, each with its rule ID linked to the edition’s rule, its reason and its link. The Pauta window links to it.- Check (code): the website’s
src/content/docs/has the page, and it lists the same rules aspauta.json. - Reference: no app yet.
- Check (code): the website’s
- PAUTA-14 SHOULD The docs page is generated from
pauta.json, like the Commands page (DOCS-04), so it cannot list a different set from the app.- Check (code): the website’s
scripts/has a generator that reads the app’spauta.json, and its output is committed. - Reference: no app yet; editora-website’s
scripts/GenCommands.javais the pattern.
- Check (code): the website’s
- PAUTA-15 MUST In the repository: the README’s Pauta badge (README badges)
and its “Built to” line (at Partial, “Working toward”) name the edition and the conformance, and both link to the
docs page.
- Check (test):
PautaConformanceTestfails when the README’s badge or line names another edition thanpauta.versionor another conformance thanPautaConformancereturns. - Reference: no app yet; the app template’s README names its edition.
- Check (test):
Pauta 4.1.0 · · Changelog · This page in the latest edition