Establish initial Evert design - #6
Open
leynos wants to merge 8 commits into
Open
Conversation
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Sorry @leynos, your pull request is larger than the review limit of 150000 diff characters
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
Summary
WalkthroughThe change establishes Evert’s project documentation. It replaces generated-project text, adds language and compiler design documents, records architectural decisions, defines implementation references and roadmap phases, updates contributor guidance, and adjusts spelling validation. ChangesEvert documentation foundation
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 19 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (19 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![codescene-access[bot]](https://avatars.githubusercontent.com/in/3755875?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Remove planning-tool citation wrapper tags from `evert-plan.md` while preserving the referenced prose. Add a document title to the inciting incident reference and demote the embedded ECLP sections so Markdown linting accepts the file structure.
Define Evert's terms, architecture, ADRs, and roadmap from the inciting incident, planning input, prior art, and literature scan. Record an interpreter-first compiler boundary, query-based workspace architecture, and local-power semantic staging so implementation work can proceed in review-sized slices. Validation: make fmt; make nixie.
Absorb the Elicit follow-up and Firecrawl-verified paper metadata into the design documentation. Add ADRs for the effect-interface sealing gate and capability authority staging, narrow the first executable effect set to Throw and Console, stage Clock behind the authority model, and put typed-Core growth on the critical path. Validation: make fmt; make nixie.
Rewrite the README in the df12 house style as a research-project introduction and design-spine signpost. Update the documentation index, repository layout, and developer guide so the visitor-facing README and normative design documents stay aligned. Validation: make fmt; make nixie.
Add a concise README section naming the papers behind Evert's effects, handlers, laziness, local state, and typed-Core design choices. Point readers to the full design bibliography and make clear the project is not presenting prior art as original invention. Validation: make fmt; make nixie.
Refresh the generated `typos.toml` from the shared en-GB-oxendict dictionary in `leynos/agent-helper-scripts`. The refreshed policy withdraws the `artifact`/`artifacts` allowance and adds further Oxford-spelling entries, so the previously green reference documents now fail the gate. Correct the affected prose in `docs/references/evert-plan.md` and `docs/references/inciting-incident.md` to house style rather than adding local exceptions: `artifacts` to `artefacts`, `behaviors` to `behaviours`, `optimiser` to `optimizer`, `tokenisation` to `tokenization`, and `ritualized` to `ritualised`. Normalize the blank-line spacing `make fmt` reports in the developer guide after merging the upstream spelling-policy section. Validation: make check-fmt; make lint; make typecheck; make test; make markdownlint; make nixie. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
lodyai
Bot
force-pushed
the
initial-design
branch
from
August 4, 2026 14:53
2e46a83 to
6a18904
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
leynos
marked this pull request as ready for review
August 7, 2026 00:12
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
There was a problem hiding this comment.
Sorry @leynos, your pull request is larger than the review limit of 150000 diff characters
Owner
Author
|
@coderabbitai full review |
✅ Action performedFull review finished. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/context.md`:
- Around line 11-28: Caption every table: add a clear caption to the
language/specification table in docs/context.md lines 11-28, the
compiler-architecture table in docs/context.md lines 32-46, the dependency
matrix in docs/references/evert-plan.md lines 425-433, the command-line API
table in docs/references/evert-plan.md lines 806-813, and the deliverable
mapping table in docs/references/evert-plan.md lines 1093-1126.
In `@docs/references/evert-plan.md`:
- Around line 1024-1030: Update the “Evaluation semantics through the
interpreter” MVP effect list to include only Throw<E> and Console, removing
Clock and the duplicate Throw reference. Keep Clock staged until
capability-authority fixtures are available.
- Around line 531-549: Add a figure caption immediately after the Mermaid
compiler-stage diagram, while preserving the preceding prose as its
screen-reader description. Use a concise caption identifying the diagram as the
Evert compiler pipeline, and keep the Mermaid syntax valid for Nixie validation.
- Around line 1031-1032: Clarify the heap-management requirements in the Runtime
section and reconcile the earlier tracing-collector and later reference-counting
statements. Explicitly designate the MVP heap model, identify the alternative as
future work, and state how reference cycles are handled for each applicable
model.
- Around line 328-339: Update the Logos reference prose to remove second-person
pronouns, including the “for you to create a Lexer” wording and the related “you
must have LLVM installed” text near the referenced section. Replace them with
neutral, impersonal phrasing while preserving the original technical meaning.
In `@docs/repository-layout.md`:
- Around line 3-9: Update the canonical tree in the repository-layout document
to include the spelling-tooling paths typos.toml and
scripts/generate_typos_config.py, alongside the required top-level directories
and critical contributor paths. Alternatively, explicitly state that tooling
paths are intentionally omitted, but do not describe the tree as the complete
current structure.
In `@docs/roadmap.md`:
- Around line 257-260: Add “Requires 3.2.6” to roadmap task 4.3.1 and update its
success or dependency notes to record the effect-interface sealing gate decision
before implementing the Throw<E> and Console handlers.
- Around line 348-352: Update roadmap tasks 6.2.1 and 6.3.2 to declare an
explicit dependency or shared RFC covering task-scope capture rules and
capability authority together. Require the design to specify capture,
propagation, and non-escape, and add negative fixtures for hidden authority,
handler-provided authority, and capability escape before Clock or richer
authority advances toward execution.
- Around line 3-13: Update docs/roadmap.md to expand GIST, ECLP, and ADR at
their first appearances, or link each to its governing convention where
appropriate. Preserve the existing roadmap hierarchy and references while
ensuring subsequent acronym usage remains consistent.
In `@README.md`:
- Around line 38-44: Update the README validation command list to include make
markdownlint alongside make fmt and make nixie, preserving the existing
documentation validation instructions.
- Around line 25-32: Replace the normative bullet list in the README with a
concise project summary that avoids specifying effect rows, handler/monad
semantics, or execution rules. Add links to docs/evert-design.md and
docs/context.md as the sources for those details.
- Around line 46-55: Expand project acronyms at their first occurrence in
README.md: write “Evert Core Language Proposal (ECLP)” before later ECLP
references, “Architecture Decision Record (ADR)” before later ADR references,
and introduce “concrete syntax tree (CST)” wherever CST first appears. Keep
subsequent uses abbreviated consistently.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 7227f618-2187-4e92-bd02-c75e768e4138
⛔ Files ignored due to path filters (1)
Cargo.lockis excluded by!**/*.lock
📒 Files selected for processing (17)
README.mddocs/adr-001-query-based-compiler-workspace.mddocs/adr-002-interpreter-first-backend-boundary.mddocs/adr-003-local-power-language-semantics.mddocs/adr-004-effect-interface-sealing-gate.mddocs/adr-005-capability-authority-staging.mddocs/contents.mddocs/context.mddocs/developers-guide.mddocs/evert-design.mddocs/references/evert-plan.mddocs/references/inciting-incident.mddocs/repository-layout.mddocs/roadmap.mddocs/terms-of-reference.mddocs/users-guide.mdtypos.toml
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
leynos/shared-actions(auto-detected)
Comment on lines
+11
to
+28
| | Term | Definition | | ||
| | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | Evert | A strict-by-default functional systems language and its reference compiler. | | ||
| | ECLP | An Evert Core Language Proposal: a compact specification document for one language capability, invariant, or refusal. | | ||
| | Power | Any capability that changes evaluation, effects, mutation, ownership, concurrency, unsafe code, or abstraction machinery. Evert's rule is that power stays local, explicit, and non-contagious. | | ||
| | Pure function | A function whose inferred effect row is empty. `pure fn` asserts and locks this property. | | ||
| | Effect row | The structural set of effects attached to a function arrow or expression. | | ||
| | Effect interface | The named set of operations and operation signatures that introduce one effect into an effect row. | | ||
| | Effect-interface sealing | A restriction that prevents polymorphic effect interfaces or operation handles from leaking authority or abstraction details beyond their intended boundary. | | ||
| | Handler | A construct that interprets, eliminates, transforms, or re-emits operations from an effect row. | | ||
| | Capability | A value that grants authority to perform an operation, such as filesystem, network, clock, or unsafe system access. Capabilities are distinct from the resource values they may operate on. | | ||
| | Monadicity | Evert's support for `Functor`, `Applicative`, `Monad`, and `do M { ... }` as ordinary data-level abstractions rather than the only way to perform effects. | | ||
| | Lazy value | A pure suspended computation that is forced on demand and memoized after successful evaluation. | | ||
| | Black hole | The runtime state of a lazy value currently being forced; re-entering the same thunk reports recursive forcing instead of looping silently. | | ||
| | Mutate region | A lexical region that permits local mutable cells while preventing those cells from escaping. | | ||
| | Resource value | A linear or affine value with deterministic finalization rules. | | ||
| | Structured concurrency | A concurrency model where child tasks cannot outlive the lexical task scope that spawned them. | | ||
| | Edition | A declared language compatibility boundary that can change parsing defaults or reserve syntax without silently changing runtime meaning. | |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Caption every table in the documentation set.
The changed documentation adds five tables without captions.
docs/context.md#L11-L28: Caption the language/specification table.docs/context.md#L32-L46: Caption the compiler-architecture table.docs/references/evert-plan.md#L425-L433: Caption the dependency matrix.docs/references/evert-plan.md#L806-L813: Caption the command-line API table.docs/references/evert-plan.md#L1093-L1126: Caption the deliverable mapping table.
As per coding guidelines, every table must have a caption.
🧰 Tools
🪛 LanguageTool
[style] ~22-~22: Consider using the typographical ellipsis character here instead.
Context: ... Functor, Applicative, Monad, and do M { ... } as ordinary data-level abstractions ...
(ELLIPSIS)
📍 Affects 2 files
docs/context.md#L11-L28(this comment)docs/context.md#L32-L46docs/references/evert-plan.md#L425-L433docs/references/evert-plan.md#L806-L813docs/references/evert-plan.md#L1093-L1126
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/context.md` around lines 11 - 28, Caption every table: add a clear
caption to the language/specification table in docs/context.md lines 11-28, the
compiler-architecture table in docs/context.md lines 32-46, the dependency
matrix in docs/references/evert-plan.md lines 425-433, the command-line API
table in docs/references/evert-plan.md lines 806-813, and the deliverable
mapping table in docs/references/evert-plan.md lines 1093-1126.
Source: Coding guidelines
Comment on lines
+328
to
+339
| **Lexing with Logos.** Logos is a derive-driven lexer generator whose stated | ||
| goals are to make it easy to create a Lexer, so you can focus on more complex | ||
| problems, and to make the generated Lexer faster than anything you'd write by | ||
| hand. It achieves this because it combines all token definitions into a single | ||
| deterministic state machine, optimizes branches into lookup tables or jump | ||
| tables, prevents backtracking inside token definitions, unwinds loops and | ||
| batches reads to minimize bounds checking, and does all of that heavy lifting | ||
| at compile time. The current line emits tokens as a `Result`: the Lexer | ||
| produces a Result<Token, Token::Error> which removes the need for the #[error] | ||
| variant, and whitespace/trivia are declared with the #[logos(skip …)] | ||
| attribute. This directly supports FR-1 (spanned tokens) and the | ||
| trivia-retention requirement. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Remove second-person pronouns from reference prose.
Rewrite phrases such as “for you to create a Lexer” and “you must have LLVM installed” with neutral wording.
Triage: [type:docstyle]
As per path instructions, Markdown documentation must avoid first- and second-person pronouns outside README.md.
Also applies to: 438-440
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/references/evert-plan.md` around lines 328 - 339, Update the Logos
reference prose to remove second-person pronouns, including the “for you to
create a Lexer” wording and the related “you must have LLVM installed” text near
the referenced section. Replace them with neutral, impersonal phrasing while
preserving the original technical meaning.
Source: Path instructions
Comment on lines
+531
to
+549
| ```mermaid | ||
| flowchart TD | ||
| SRC["Source text (.evt)"] --> LEX["evert_syntax: Logos lexer<br/>spanned tokens + trivia"] | ||
| LEX --> LAYOUT["Layout pass<br/>inject Indent / Dedent / Newline"] | ||
| LAYOUT --> PARSE["evert_syntax: Chumsky parser<br/>lossless CST + typed AST"] | ||
| PARSE --> HIR["evert_hir: name resolution<br/>desugaring + stable DefIds"] | ||
| HIR --> TYPES["evert_types: HM inference<br/>effect rows + traits + coherence"] | ||
| TYPES --> CORE["evert_core: typed Core IR"] | ||
| CORE --> LOWER["evert_lower: closures, thunks,<br/>dictionaries, handler/effect lowering"] | ||
| LOWER --> INTERP["evert_interpreter: tree-walking<br/>Core interpreter (semantic oracle)"] | ||
| LOWER --> CGAPI["evert_codegen_api: Backend trait"] | ||
| CGAPI -. deferred .-> LLVM["evert_codegen_llvm:<br/>textual IR, then Inkwell"] | ||
| INTERP --> RT["evert_runtime: values, thunks,<br/>Text, capabilities, GC"] | ||
| LLVM -. links .-> RT | ||
| DB[("evert_db: Salsa database<br/>memoization + early cutoff")] -.orchestrates.-> HIR | ||
| DB -.orchestrates.-> TYPES | ||
| DB -.orchestrates.-> CORE | ||
| DRIVER["evert_driver: CLI + diagnostics"] --> DB | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Caption the Mermaid diagram.
Add a figure caption for the compiler-stage diagram. Keep the preceding prose as the screen-reader description.
Triage: [type:docstyle]
As per coding guidelines, every diagram must have a caption and Mermaid diagrams must pass Nixie validation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/references/evert-plan.md` around lines 531 - 549, Add a figure caption
immediately after the Mermaid compiler-stage diagram, while preserving the
preceding prose as its screen-reader description. Use a concise caption
identifying the diagram as the Evert compiler pipeline, and keep the Mermaid
syntax valid for Nixie validation.
Source: Coding guidelines
Comment on lines
+1024
to
+1030
| - **Evaluation semantics through the interpreter**: typed Core IR and lowering | ||
| (FR-13); the tree-walking Core interpreter as the semantic oracle (FR-14); | ||
| laziness with pure-only thunks, memoization, and black-hole detection (FR-9); | ||
| `Functor`/`Monad` traits and `do` notation (FR-10); algebraic effects with | ||
| resumable handlers and `Throw<E>` (FR-11) for the MVP effect set (e.g., | ||
| `Console`, `Clock`, `Throw`); and `mutate` regions with escape checking | ||
| (FR-12). |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Keep Clock out of the first executable effect slice.
Remove Clock from this MVP effect list. The first executable effect set is Throw<E> and Console; Clock must remain staged until capability-authority fixtures exist. This sentence also lists Throw twice.
Based on learnings, the first executable effect MVP is limited to Throw<E> and Console, while Clock waits for authority-model conformance fixtures.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/references/evert-plan.md` around lines 1024 - 1030, Update the
“Evaluation semantics through the interpreter” MVP effect list to include only
Throw<E> and Console, removing Clock and the duplicate Throw reference. Keep
Clock staged until capability-authority fixtures are available.
Source: Learnings
Comment on lines
+1031
to
+1032
| - **Runtime**: immutable values, thunks, real Unicode `Text`, | ||
| capability-mediated I/O, and a non-moving reference-counted heap (FR-15). |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Resolve the heap-management model before implementation.
This section requires a non-moving reference-counted heap, while earlier text requires a non-moving tracing collector and later text repeats reference counting. State which model belongs to the MVP and which model is future work, including cycle handling.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/references/evert-plan.md` around lines 1031 - 1032, Clarify the
heap-management requirements in the Runtime section and reconcile the earlier
tracing-collector and later reference-counting statements. Explicitly designate
the MVP heap model, identify the alternative as future work, and state how
reference cycles are handled for each applicable model.
Comment on lines
+257
to
+260
| - [ ] 4.3.1. Implement basic `Throw<E>` and `Console` handlers. | ||
| - Requires 4.2.1 and 3.2.2. | ||
| - Success: direct-style effect examples execute through handlers and | ||
| unhandled effects remain visible in the effect row. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Make effect-interface sealing a prerequisite for handlers.
Add Requires 3.2.6 and the resulting gate decision to task 4.3.1. This task introduces executable handlers and broadens effect support, but it currently depends only on effect inference.
As per coding guidelines, roadmap tasks that broaden effect support must depend on completion of the effect-interface sealing gate.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~259-~259: Possible missing comma found.
Context: ...t-style effect examples execute through handlers and unhandled effects remain visibl...
(AI_HYDRA_LEO_MISSING_COMMA)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/roadmap.md` around lines 257 - 260, Add “Requires 3.2.6” to roadmap task
4.3.1 and update its success or dependency notes to record the effect-interface
sealing gate decision before implementing the Throw<E> and Console handlers.
Source: Coding guidelines
Comment on lines
+348
to
+352
| - [ ] 6.2.1. Accept an RFC for nurseries, task cancellation, and `Task<T, E>`. | ||
| - Requires phase 4. | ||
| - See `docs/evert-design.md` §§8 and 16. | ||
| - Success: the RFC states static capture rules, cancellation propagation, and | ||
| interpreter/runtime staging. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift
Couple task-scope authority to capability staging.
Link tasks 6.2.1 and 6.3.2 through an explicit dependency or shared RFC. Task-scope capture rules and capability authority must define capture, propagation, and non-escape together. Add negative fixtures for hidden authority, handler-provided authority, and capability escape before Clock or richer authority moves towards execution.
Based on learnings, structured concurrency and capabilities must be designed together where task scopes capture authority.
Also applies to: 368-373
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/roadmap.md` around lines 348 - 352, Update roadmap tasks 6.2.1 and 6.3.2
to declare an explicit dependency or shared RFC covering task-scope capture
rules and capability authority together. Require the design to specify capture,
propagation, and non-escape, and add negative fixtures for hidden authority,
handler-provided authority, and capability escape before Clock or richer
authority advances toward execution.
Source: Learnings
Comment on lines
+25
to
+32
| - **Strict by default:** laziness is explicit, pure-only, and memoized. | ||
| - **Effects are typed:** `pure fn` means an empty inferred effect row. | ||
| - **Handlers, not monads, carry effects:** monads remain ordinary data | ||
| abstractions. | ||
| - **Compiler evidence first:** a typed Core interpreter becomes the semantic | ||
| oracle before LLVM or native execution. | ||
| - **Systems power is staged:** mutation, structured concurrency, capabilities, | ||
| ownership, and unsafe work have to earn their semantics before they execute. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Keep normative semantics out of the README.
Move exact rules such as the empty effect row for pure fn and the handler/monad distinction to the design documents. Keep a short project summary here and link to docs/evert-design.md and docs/context.md. This prevents source-of-truth drift.
As per coding guidelines, the README must remain concise and link-oriented, with normative semantics in the designated documentation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 25 - 32, Replace the normative bullet list in the
README with a concise project summary that avoids specifying effect rows,
handler/monad semantics, or execution rules. Add links to docs/evert-design.md
and docs/context.md as the sources for those details.
Source: Coding guidelines
Comment on lines
+38
to
+44
| There is nothing to install as a language user yet. From a checkout, validate | ||
| the current research documentation with: | ||
|
|
||
| ```shell | ||
| make fmt | ||
| make nixie | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Document the Markdownlint check.
Add make markdownlint to this validation list. The section currently runs formatting and Mermaid validation, but it claims to validate the documentation.
As per coding guidelines, Markdown changes must use make markdownlint, make fmt, and make nixie where applicable.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 38 - 44, Update the README validation command list to
include make markdownlint alongside make fmt and make nixie, preserving the
existing documentation validation instructions.
Source: Coding guidelines
Comment on lines
+46
to
+55
| Then start with the design spine: | ||
|
|
||
| - [Terms of reference](docs/terms-of-reference.md): the problem, scope, | ||
| stakeholders, constraints, and open questions. | ||
| - [Evert design](docs/evert-design.md): the proposed language semantics and | ||
| Rust reference compiler architecture. | ||
| - [Roadmap](docs/roadmap.md): the planned implementation order, from ECLP | ||
| split to interpreter-backed compiler slices. | ||
| - [ADRs](docs/contents.md#architecture-decisions): accepted decisions that | ||
| constrain the design and roadmap. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Expand project acronyms on first use.
Write Evert Core Language Proposal (ECLP), Architecture Decision Record (ADR), and concrete syntax tree (CST) before using the abbreviations. The README is the visitor entry point.
Triage: [type:docstyle]
As per coding guidelines, uncommon acronyms must be expanded on first use.
Also applies to: 65-74
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 46 - 55, Expand project acronyms at their first
occurrence in README.md: write “Evert Core Language Proposal (ECLP)” before
later ECLP references, “Architecture Decision Record (ADR)” before later ADR
references, and introduce “concrete syntax tree (CST)” wherever CST first
appears. Keep subsequent uses abbreviated consistently.
Source: Coding guidelines
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This branch establishes Evert as a research and compiler-foundation project. It turns the generated Rust scaffold into a documented language-design workspace by adding the problem frame, semantic design, delivery roadmap, initial ADR set, and preserved reference inputs needed before implementation work starts.
Roadmap task: none. This branch creates the roadmap and initial design spine rather than completing a numbered roadmap task.
Execplan: none present for this branch.
Review walkthrough
Validation
make check-fmt: passed.make lint: passed (rustdoc, Clippy, Whitaker Dylint).make typecheck: passed.make test: passed.make markdownlint: passed (includes the en-GB-oxendict spelling gate).make nixie: passed.git diff --name-status origin/main...HEAD: inspected the full branch scope; the PR contains 18 changed files.Notes
No issue is linked to this branch. No pre-implementation execplan is present; this branch is the initial design and roadmap package that future implementation tasks should derive from.
The branch has been rebased onto
origin/mainand force-pushed. Two conflicts were resolved by hand:README.md: keptmain's Ask DeepWiki badge alongside this branch's research-project pitch.docs/developers-guide.md: keptmain's new "Spelling policy" and "Workflow pins and Dependabot" sections alongside this branch's "Normative design sources" and "Design workflow" sections.Rebasing also brought in
main's newtyposspelling gate. The generatedtypos.tomlrefreshed from the sharedleynos/agent-helper-scriptsdictionary, which withdraws theartifact/artifactsallowance. The affected prose in the preserved reference documents was corrected to house style rather than suppressed with local exceptions.References