RIGOR.md format specification — v0.3

This document specifies the RIGOR.md file: its layout, its stamp fields, the validation rules a conforming tool applies, and the prose a conforming tool generates.

A stamp declares its version with spec: "0.3". That is the only accepted value. rigor.schema.json, shipped beside this document and identified by https://rigor.diaconou.com/0.3/rigor.schema.json, is the canonical structural schema; where prose and schema disagree, the schema wins.

1. File layout

A RIGOR.md is a Markdown document. Two regions are defined:

• The stamp: a fenced YAML block carrying the machine-readable claims.
• The summary block: generated prose between the markers of section 4.1.

All other content is free prose. A tool must not read it.

1.1 Locating the stamp

1. Find every line matching ^##\s+Stamp\s*$. The last one is the stamp heading.
2. After that line, the first line matching ^```ya?ml\s*$ opens the block.
3. After the open, the first line matching ^```\s*$ closes it.
4. The lines between the fences are the stamp.

Scanning is line by line, never a regular expression applied across the whole file. A missing heading, open fence, or close fence is the error No stamp found. Expected a '## Stamp' section with a fenced yaml block.

1.2 Parsing the stamp

The stamp is YAML 1.2 under the core schema. A conforming parser must reject:

The anchor and alias check runs before the tree is materialized, so an expansion attack cannot detonate during validation.

Under the core schema, bare yes and no are already strings, and a bare date is a string. Three normalizations follow the parse:

• rigor is trimmed and downcased. If the result is a known level name, it replaces the original; otherwise the original passes through unchanged, so section 3.1 reports it.
• true and false become yes and no inside checks and inside vouch (an author may write comprehended: true). A non-mapping checks keeps its real type, so the schema rejects it.
• spec and assessed are re-printed as their literal text, so an unquoted 0.3 stays the string "0.3".

2. Stamp fields

Unknown keys are rejected at every level of the stamp.

2.1 rigor

Five level names, in order: unexamined, skimmed, comprehended, engineered, owned. The name is the canonical encoding; a tool must emit the name and must not emit an ordinal. comprehended and above are above the comprehension line.

2.2 vouch

Either a scalar — yes, neutral, or withheld — or a mapping with the required key claim holding one of those three, and the optional key why holding a string.

2.3 checks

Keys: comprehended, quality_reviewed, security_reviewed, tested, owned. Any subset may appear.

Each value is one of six strings, never a boolean:

The first four are the done states.

2.4 stages

3. Validation

Validation checks form and consistency. It does not check truth. Every value in a stamp is a self-report.

A validator reports errors, which make the stamp invalid, and warnings, which do not. Strict mode promotes one case noted in 3.2.

3.1 Structural

The stamp must satisfy rigor.schema.json: required fields present, no unknown keys, every value drawn from its vocabulary. Structural errors stop validation; semantic rules do not run against a malformed stamp.

3.2 Semantic

A headline level implies checks. The summary may not exceed the details.

comprehended excludes ai: an AI that comprehends code does not put a human above the comprehension line.

Three rules apply to each required check:

1. Present with an unacceptable value — error: rigor 'L' requires 'K' to be one of ["a", "b"], but it is 'v'. The value list is bracketed, comma and space separated, each element double quoted.
2. Absent while rigor is engineered or owned — error: rigor 'L' claims 'K' but it is not surfaced — show your working (add 'K:' under checks:). Above the line, a claim must show its working.
3. Absent otherwise — warning in strict mode, silent by default. At or below comprehended, a terse stamp stays legal.

One further semantic error: stages.maintenance.by is none while activity is present. No one responds, so activity does not apply.

3.3 Warnings

The first names every affected check in one warning, not one warning per check.

3.4 Drift

The generated prose of section 4 is derived from the stamp, so the two can never be allowed to disagree.

• If the summary markers are present in the RIGOR.md, the enclosed text must equal the composed block. A difference is an error.
• If a README is supplied, and the line markers are present in it, the enclosed text must equal the composed line block. A difference is an error.
• If the markers are absent, no check runs. The guarantee is opt-in.

Comparison is exact after trimming surrounding whitespace.

4. Generated prose

The sentences below are fixed. A conforming tool must reproduce them byte for byte, because section 3.4 compares generated text against stored text.

4.1 Summary block

<!-- rigor:summary -->
**<summary>**
<!-- /rigor:summary -->

<summary> is the sentences of 4.2, in this order, joined by one space. A sentence whose source field is absent is omitted:

1. The idea was <stage phrase>.
2. The plan was <stage phrase>.
3. the implementation sentence
4. the level sentence — always present
5. the checks sentence
6. the maintenance sentence
7. This assessment is as of <assessed>.
8. the vouch sentence — always present
9. Why: <why>

4.2 Sentence tables

Level, from rigor:

Vouch, from the claim:

Stage phrase, for idea and plan. With both keys it is the owner phrase followed by the depth tail; with by alone it is the owner phrase; with depth alone it is the depth-alone phrase; with neither the sentence is omitted.

Implementation, from stages.implementation.by:

Checks. The sentence is It was <list>., built from the done checks among quality_reviewed, security_reviewed, and tested, in that order. Each contributes its phrase plus its actor parenthetical. The list joins as a, a and b, or a, b and c. No other check contributes a phrase, and the sentence is omitted when the list is empty.

Maintenance. When activity is dormant, the sentence is:

Nothing has needed changing lately; I still use this and would respond if it broke.

Otherwise, when by is present:

4.3 README line

The README line is the level sentence and the vouch sentence, plus Why: when the stamp carries one. It is not the full summary.

<!-- rigor:line -->
> "<level sentence> <vouch sentence>[ Why: <why>]" — [RIGOR.md](RIGOR.md)
<!-- /rigor:line -->

5. Conformance

A conforming validator must:

1. Locate and parse the stamp by section 1, with every rejection in 1.2.
2. Enforce rigor.schema.json (3.1) and the semantic rules (3.2).
3. Report the warnings of 3.3 without invalidating the stamp.
4. Compose the prose of section 4 byte for byte, and enforce the drift rules of 3.4 wherever the markers are present.

A conforming author tool must additionally regenerate the summary block in place, so a stamp and its prose stay in agreement.