Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Create firmament-author-rules.md
Yuechen Li76ef72301de4
diff --git a/docs/firmament-author-rules.md b/docs/firmament-author-rules.mdnew file mode 100644index 00000000..839f520c--- /dev/null+++ b/docs/firmament-author-rules.md@@ -0,0 +1,172 @@+# Firmament Author Rules++These rules apply to **any LLM or developer generating or editing `.firmament` files** in the Aetheris repository.++The goal is to maintain **stable canonical examples** of the Firmament DSL.++---++# Rule 1 — Never emit JSON++`.firmament` files must not contain JSON object literals.++### Forbidden++```json+{+ "firmament": { "version": "1" },+ "ops": []+}+````++Always use canonical indentation syntax.++---++# Rule 2 — Follow canonical section order++Top-level sections must appear in this order:++```+firmament+model+schema (optional)+ops+pmi (optional)+```++Do not reorder sections.++---++# Rule 3 — Use explicit array length syntax++Arrays must include their length.++### Correct++```+ops[0]:+```++```+size[3]:+ 1+ 2+ 3+```++### Incorrect++```+ops: []+size: [1,2,3]+```++---++# Rule 4 — Operation entries must use object blocks++Each operation must appear as a block under `ops[n]`.++### Correct++```+ops[1]:+ -+ op: box+ id: base+```++### Incorrect++```+ops:+ box:+ id: base+```++---++# Rule 5 — Always use `op:` field++Operations must explicitly declare the operation type.++### Correct++```+op: box+```++### Incorrect++```+box:+```++---++# Rule 6 — Do not invent new syntax++LLM authors must not introduce:++* new keywords+* alternate field names+* shorthand operation syntax+* JSON literals++Use only documented shapes.++---++# Rule 7 — Preserve canonical examples++Files in:++```+testdata/firmament/fixtures/+```++serve as language examples.++When editing them:++* maintain canonical formatting+* keep them minimal and readable+* avoid stylistic variation++---++# Rule 8 — If unsure, emit the smallest valid structure++When generating new examples:++1. follow canonical section order+2. emit minimal valid fields+3. avoid guessing additional syntax++---++# Rule 9 — Do not mix languages++`.firmament` files must not include:++* C#+* JSON+* YAML comments+* scripting code+* host-language constructs++---++# Rule 10 — Treat language-shape.md as authoritative++Before generating or modifying `.firmament` source, read:++```+docs/firmament-language-shape.md+```++That document defines the canonical syntax.++```