RFC-0012 · Reference catalog
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
Generated reference catalog. This page renders structured Lean data for RFC-0012: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0012.This page is generated from the
lean/Gnomon/Spec/module for RFC-0012. Edit that source and regenerate this catalog.
Title: Gnomon Tooling
Status: draft
Owners: Compiler, DX
Proof citations in source: 13 / 13. Standalone proof verification is pending.
Definitions
(none defined)
Diagnostics
| Code | Severity | Description |
|---|---|---|
F12700 | Warning | Unrecognized property encountered during formatting; property preserved at end of block. |
F12701 | Error | File does not end with newline; auto-corrected by gnomon fmt; exit code 2 for —check. |
F12702 | Info | File contains a tab character; converted to 2 spaces. |
F12800 | Error | Grammar conformance CI: extracted grammar fails PEG validation. |
F12801 | Error | Grammar conformance CI: conformance fixture produces unexpected parse result. |
F12802 | Warning | Grammar conformance CI: production has no conformance fixture (warning in draft, error in accepted). |
Invariants
- —print-* flags MUST NOT execute any user-defined code or invoke any runtime component. (enforced by: tooling)
- Each non-trivial grammar production MUST have at least one conformance fixture pairing an .gnm snippet with its expected canonical AST. (enforced by: CI)
- Every MCP tool and AI agent that writes .gnm files MUST pipe output through gnomon fmt before writing. (enforced by: tooling)
- The —print-desugared flag MUST produce the exact AST that the compiler passes to the semantic analysis phase; any divergence is a compiler defect. (enforced by: compile-time)
- The —print-desugared output MUST be valid .gnm source that passes gnomon fmt —check without modification. (enforced by: tooling)
- The normative EBNF grammar in RFC-0008 §8 MUST be extracted as a standalone PEG grammar file and validated in CI on every RFC commit. (enforced by: CI)
- gnomon fmt —check MUST be a required CI step; failure to enforce it is a project governance violation. (enforced by: CI)
- gnomon fmt MUST NOT change the semantic meaning of any declaration. (enforced by: tooling)
- gnomon fmt MUST NOT execute any code from the formatted file; it is a pure syntactic transformation. (enforced by: tooling)
- gnomon fmt MUST be sugar-preserving and MUST NOT desugar source files; the canonical formatted form is human-readable source, not the IR. (enforced by: tooling)
- gnomon fmt MUST handle every syntactically valid .gnm file, including files with only partial declarations, and MUST NOT refuse to format a valid file. (enforced by: tooling)
- gnomon fmt MUST produce identical output for any two .gnm files with the same semantic content, regardless of original formatting. (enforced by: tooling)
- gnomon fmt applied twice produces the same result as applied once. (enforced by: tooling)
- gnomon fmt is non-configurable: no .gnomon-fmt.yaml, no per-project options; one canonical form across all projects and teams. (enforced by: tooling)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Compatibility and Migration
- MUST — Changing the canonical property ordering is a breaking change and MUST increment the formatter version.
Compiler Flags
- MUST — —print-desugared output MUST be valid .gnm source that passes gnomon fmt —check without modification.
Grammar Conformance CI
- MUST — A CI step MUST extract all ebnf code blocks from RFC-0008 §8 and RFC-0011 §4 into grammar/gnomon.peg. (proof citation:
rfc0012_b31_grounded; verification pending) - MUST — Each non-trivial grammar production MUST have at least one successful conformance fixture pairing a snippet with its expected canonical AST; failing fixtures MUST pair snippets with expected diagnostics and require rejection. (proof citation:
rfc0012_b26_grounded; verification pending) - MUST — The extracted grammar MUST be validated by a PEG parser generator on every RFC commit. (proof citation:
rfc0012_b10_grounded; verification pending) - MUST — The normative EBNF grammar in RFC-0008 §8 MUST be extracted as a standalone PEG grammar file and validated in CI. (proof citation:
rfc0012_b18_grounded; verification pending)
Invariants
- MUST — —print-desugared MUST produce the exact AST passed to semantic analysis. (proof citation:
rfc0012_b22_grounded; verification pending) - MUST — Every MCP tool and AI agent writing .gnm files MUST pipe output through gnomon fmt before writing. (proof citation:
rfc0012_b33_grounded; verification pending) - MUST — gnomon fmt —check MUST be a required CI step.
- MUST_NOT — gnomon fmt MUST NOT change the semantic meaning of any declaration.
- MUST — gnomon fmt MUST be sugar-preserving and MUST NOT desugar source files.
- MUST — gnomon fmt MUST produce identical output for any two .gnm files with the same semantic content.
Scope
- MUST_NOT — Tooling MUST NOT introduce behavior that contradicts any normative statement in the RFC suite. (proof citation:
rfc0012_b24_grounded; verification pending) - MUST — Tooling defined here MUST be consistent with the language grammar in RFC-0008 §8. (proof citation:
rfc0012_b3_grounded; verification pending)
Security and Authorization
- MUST_NOT — —print-* flags MUST NOT execute any user-defined code or invoke any runtime component.
- MUST_NOT — gnomon fmt MUST NOT execute any code from the formatted file.
gnomon fmt: Canonical Formatter
- MUST — //compiled: and //compiled-by: structured comments MUST be preserved verbatim immediately after the rule statement. (proof citation:
rfc0012_b16_grounded; verification pending) - MUST — Every MCP tool, AI agent, or automated process producing .gnm content MUST pass that content through gnomon fmt before writing or returning it. (proof citation:
rfc0012_b5_grounded; verification pending) - MUST — Every file MUST end with a single trailing newline.
- MUST_NOT — gnomon fmt —check MUST NOT suppress or hide epistemic modifier presence. (proof citation:
rfc0012_b29_grounded; verification pending) - MUST — gnomon fmt —check MUST be a required CI step and exit code 2 MUST fail the CI build.
- MUST_NOT — gnomon fmt MUST NOT refuse to format a valid file. (proof citation:
rfc0012_b7_grounded; verification pending) - MUST — gnomon fmt MUST handle every syntactically valid .gnm file, including partial declarations. (proof citation:
rfc0012_b0_grounded; verification pending) - MUST — gnomon fmt MUST remove intra-body blank lines to produce canonical output.
Linked References
(no cross-RFC dependencies)