docs: one authoritative spec (SPEC / LANGUAGE_CONTRACT / GRAMMAR / SYNTAX overlap)
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 45/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Domain
- documentation
Research direction
The issue mentions four documents in the docs/ directory: SPEC.md, LANGUAGE_CONTRACT.md, GRAMMAR.md, and SYNTAX.md. Start by reading these files to understand their current content and overlaps. Look for duplicated normative statements. The goal is to consolidate them into one authoritative spec, ensuring all executable examples still run and updating references in llms.txt and the mentioned skills.
Written by the indexing model from the issue text.
Description
Problem. Four documents cover overlapping ground on what the language IS: docs/SPEC.md (2,272 lines), docs/LANGUAGE_CONTRACT.md, docs/GRAMMAR.md and docs/SYNTAX.md. Overlap means copies, and copies disagree. The 2026-09-22 prompt audit found write-eigenscript teaching three semantics the language had since changed (loop-body scope, observer keying, constant convergence), because it summarised a copy rather than the contract.
What mature languages do. There is exactly one authoritative specification, separate from the tutorial: the Go spec (a single page), Python's Language Reference, the Rust Reference.
Bar.
- One document is THE spec. It carries the grammar (or includes GRAMMAR by reference) and the contract rules. Every normative statement lives there exactly once.
- The other three are either folded in, or turned into explanation that links to spec sections instead of restating them. Checked: no normative rule text appears in two documents (a duplication grep, or the docs-claims NAMES class).
- Every executable example in the merged spec still runs.
llms.txtand thewrite-eigenscript/eigenscript-lang-reviewskills point at the one spec.
Ranked #4 of the docs follow-ups (2026-09-22 comparison with other languages).
- Dominant language
- C
- Stars
- 3
- Forks
- 7
- Avg merge
- 3h 56m
- Merged PRs (30d)
- 102
Getting set up
Starts the project's dev container in your browser, under your own GitHub account.
- Ships a Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from InauguralSystems/EigenScript
-
area:lint-tooling bug
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
InauguralSystems/EigenScript#1340 ·
Maintainers usually reply within 1 day
-
area:stdlib found-by:code-review kind:silent-wrong
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
InauguralSystems/EigenScript#1338 ·
Maintainers usually reply within 1 day
-
area:lint-tooling found-by:critic kind:docs-drift
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
InauguralSystems/EigenScript#1335 ·
Maintainers usually reply within 1 day
-
area:ci found-by:critic kind:gate-defect
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
InauguralSystems/EigenScript#1311 ·
Maintainers usually reply within 1 day
-
enrolment: decide test_gc_runner_controls.py (exempt vs enrol) and whether floors need a ratchetOpenarea:gates found-by:critic kind:decision
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
InauguralSystems/EigenScript#1280 · 1 comment ·
Maintainers usually reply within 1 day
All issues in InauguralSystems/EigenScript
Similar issues
-
[Bug]: chunk_span_bounds and _validated_chunk_spans reject Pydantic models ChunkSpan and AudioFileOpen
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
BasedHardware/omi#19047 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
obsproject/obs-studio#13936 · 2 comments ·
Maintainers usually reply within 1 day
-
category:port-update
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 88/100
Maintainers usually reply within 1 day