feat: expose surface validation stage

[flyingrobots]

Summary

• add validate_surface as the explicit source/surface compiler stage after parsing
• keep validate_module as a compatibility alias for the same stage
• add deterministic boundary tests proving surface validation defers import/name resolution, contextual typing, loop-bound proof, and obstruction exhaustiveness
• update the semantic-validation and syntax topic shelves to reflect the stage split
• document the PR body auto-close rule in AGENTS.md

Closes #10

Verification

• RED: cargo test -p edict-syntax --test semantic_validation -- --nocapture failed before implementation because validate_surface was not exported
• cargo test -p edict-syntax --test semantic_validation -- --nocapture
• cargo test -p xtask contract_graph_is_valid -- --nocapture
• npx markdownlint-cli2 AGENTS.md CHANGELOG.md docs/topics/README.md docs/topics/semantic-validation/README.md docs/topics/semantic-validation/test-plan.md docs/topics/syntax/README.md docs/topics/syntax/test-plan.md
• cargo xtask verify
• git diff --check

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: cb30e836-e434-49e7-8db6-b6d59b5dcb3c

📥 Commits

Reviewing files that changed from the base of the PR and between f692ee5 and 582f756.

📒 Files selected for processing (10)

• AGENTS.md
• CHANGELOG.md
• crates/edict-syntax/src/lib.rs
• crates/edict-syntax/src/semantic.rs
• crates/edict-syntax/tests/semantic_validation.rs
• docs/topics/README.md
• docs/topics/semantic-validation/README.md
• docs/topics/semantic-validation/test-plan.md
• docs/topics/syntax/README.md
• docs/topics/syntax/test-plan.md

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (3)

**

⚙️ CodeRabbit configuration file

**: # AGENTS

Git Rules

NEVER amend git commits. Make a new commit instead.

NEVER use git rebase unless the user explicitly approves a rare exception.
Use regular merge commits.

NEVER force any git operation. If a force operation appears necessary, stop and
explain what happened and what options remain.

NEVER create draft pull requests.

NEVER use a codex prefix in branch names, PR titles, or commit messages.

Think

Think is durable memory for cross-session coordination.

• Use codex-think --remember --json when starting a new session, changing into
  this repository, or regaining context after a context shift.
• Use codex-think "..." --json when a cycle closes or a significant event
  should survive across turns.
• Treat Think as memory, not repo truth. Anchor strong claims back to files,
  commits, commands, issues, or pull requests.
• Claude memories are read-only. Use claude-think --remember --json only for
  additional context.

Topic Shelves

docs/topics/ contains the living contract graph for landed behavior. Topic
shelves are not proposals, retrospectives, or design archaeology.

Each shelf may contain:

• README.md: what is true in HEAD.
• test-plan.md: how those truths are verified, including requirements, cases,
  fixtures, oracles, implemented evidence, planned cases, and known gaps.
• architecture.md: optional structure or dataflow notes when the machinery
  earns a separate page.
• rationale.md: optional still-relevant tradeoffs and rejected approaches.

When To Update Topic Shelves

For every nontrivial behavior, contract, workflow, release, schema, validation,
or public-surface change:

1. Identify the owning topic shelf before editing code.
2. If no shelf owns durable behavior, create one.
3. Update test-plan.md before or alongside tests with requirement IDs, case
   IDs, fixtures, and oracles.
4. Write executable evidence: deterministic tests, fixtures, doctests, or
   contract checks as appropriate.
5. Upd...

Files:

• docs/topics/README.md
• AGENTS.md
• docs/topics/syntax/README.md
• CHANGELOG.md
• crates/edict-syntax/src/lib.rs
• docs/topics/semantic-validation/README.md
• crates/edict-syntax/src/semantic.rs
• docs/topics/syntax/test-plan.md
• crates/edict-syntax/tests/semantic_validation.rs
• docs/topics/semantic-validation/test-plan.md

docs/topics/*/README.md

📄 CodeRabbit inference engine (AGENTS.md)

Topic README.md files in docs/topics/ must not describe intended behavior before it lands.

Files:

• docs/topics/syntax/README.md
• docs/topics/semantic-validation/README.md

docs/topics/*/test-plan.md

📄 CodeRabbit inference engine (AGENTS.md)

test-plan.md in topic shelves may include planned cases and known gaps.

Files:

• docs/topics/syntax/test-plan.md
• docs/topics/semantic-validation/test-plan.md

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
Repo: flyingrobots/edict

Timestamp: 2026-06-21T20:26:54.310Z
Learning: NEVER amend git commits. Make a new commit instead.

Learnt from: CR
Repo: flyingrobots/edict

Timestamp: 2026-06-21T20:26:54.310Z
Learning: NEVER use `git rebase` unless the user explicitly approves a rare exception. Use regular merge commits.

Learnt from: CR
Repo: flyingrobots/edict

Timestamp: 2026-06-21T20:26:54.310Z
Learning: NEVER force any git operation. If a force operation appears necessary, stop and explain what happened and what options remain.

Learnt from: CR
Repo: flyingrobots/edict

Timestamp: 2026-06-21T20:26:54.310Z
Learning: NEVER create draft pull requests.

Learnt from: CR
Repo: flyingrobots/edict

Timestamp: 2026-06-21T20:26:54.310Z
Learning: NEVER use a `codex` prefix in branch names, PR titles, or commit messages.

Learnt from: CR
Repo: flyingrobots/edict

Timestamp: 2026-06-21T20:26:54.310Z
Learning: Pull request bodies for issue work MUST include GitHub auto-close text such as `Closes `#123`` for every issue the PR is intended to close.

Learnt from: CR
Repo: flyingrobots/edict

Timestamp: 2026-06-21T20:26:54.310Z
Learning: Use `codex-think --remember --json` when starting a new session, changing into this repository, or regaining context after a context shift.

Learnt from: CR
Repo: flyingrobots/edict

Timestamp: 2026-06-21T20:26:54.310Z
Learning: Use `codex-think "..." --json` when a cycle closes or a significant event should survive across turns.

Learnt from: CR
Repo: flyingrobots/edict

Timestamp: 2026-06-21T20:26:54.310Z
Learning: Treat Think as memory, not repo truth. Anchor strong claims back to files, commits, issues, or pull requests.

Learnt from: CR
Repo: flyingrobots/edict

Timestamp: 2026-06-21T20:26:54.310Z
Learning: Claude memories are read-only. Use `claude-think --remember --json` only for additional context.

Learnt from: CR
Repo: flyingrobots/edict

Timestamp: 2026-06-21T20:26:54.310Z
Learning: Topic shelves in `docs/topics/` must contain `README.md` describing current behavior in HEAD, and may optionally contain `test-plan.md`, `architecture.md`, and `rationale.md`.

Learnt from: CR
Repo: flyingrobots/edict

Timestamp: 2026-06-21T20:26:54.310Z
Learning: For nontrivial behavior, contract, workflow, release, schema, validation, or public-surface changes: identify the owning topic shelf before editing code, create a new shelf if none exists, update test-plan.md before or alongside tests, write executable evidence, update README.md only after behavior exists, and run `cargo xtask verify` before claiming the shelf is current.

Learnt from: CR
Repo: flyingrobots/edict

Timestamp: 2026-06-21T20:26:54.310Z
Learning: Do not churn topic shelves for purely mechanical edits such as formatting, typo fixes, dependency pin updates with no observable behavior change, or internal refactors with no contract changes.

Learnt from: CR
Repo: flyingrobots/edict

Timestamp: 2026-06-21T20:26:54.310Z
Learning: Release, CI, and publication workflows count as behavior contracts and should be documented in topic shelves alongside code changes.

Learnt from: CR
Repo: flyingrobots/edict

Timestamp: 2026-06-21T20:26:54.310Z
Learning: Run `cargo xtask verify` before claiming a branch is ready for review.

🔇 Additional comments (10)

crates/edict-syntax/src/semantic.rs (1)

1-2: LGTM!

Also applies to: 44-53, 75-85

crates/edict-syntax/src/lib.rs (1)

8-12: LGTM!

Also applies to: 27-27

crates/edict-syntax/tests/semantic_validation.rs (1)

3-3: LGTM!

Also applies to: 12-92, 206-206, 301-301, 324-324

docs/topics/README.md (1)

34-35: LGTM!

docs/topics/semantic-validation/README.md (1)

5-36: LGTM!

Also applies to: 65-78, 90-90

docs/topics/semantic-validation/test-plan.md (1)

9-13: LGTM!

Also applies to: 34-44, 58-61, 75-78

docs/topics/syntax/README.md (1)

67-70: LGTM!

docs/topics/syntax/test-plan.md (1)

40-40: LGTM!

Also applies to: 76-77

AGENTS.md (1)

17-19: LGTM!

CHANGELOG.md (1)

11-20: LGTM!

---

Summary by CodeRabbit

• New Features

  • Introduced explicit semantic validation stage for source/surface level verification.
  • Implemented requirement for pull requests addressing issues to include GitHub auto-close text (e.g., Closes Deferred: full WARP TTD counterfactual model for obstruction planning #123``) in PR body.

• Documentation

  • Updated semantic validation documentation to clarify validation scope, contracts, and deferred checks.

• Tests

  • Updated validation test suite to reflect new validation stage boundaries.

Walkthrough

Introduces validate_surface as the explicit named compiler stage for context-free source/surface semantic validation in edict-syntax. validate_module is retained as a compatibility alias that delegates to validate_surface. Tests are updated to use the new entry point and new tests assert stage-boundary deferral. All related documentation is aligned. A Git workflow rule requiring GitHub auto-close text in PR bodies is also added.

Changes

validate_surface compiler stage

Layer / File(s)	Summary
validate_surface public API and compatibility alias crates/edict-syntax/src/semantic.rs, crates/edict-syntax/src/lib.rs	validate_surface becomes the named context-free semantic validation entry point; validate_module is demoted to a compatibility wrapper that delegates to it. Crate-level docs and re-exports updated to expose the new symbol.
Test suite updated to validate_surface crates/edict-syntax/tests/semantic_validation.rs	Imports, semantic_kinds() helper, and all existing call sites migrated to validate_surface. New tests assert deferral of import/name/callee resolution, contextual typing, loop-bound proof, obstruction exhaustiveness, and equivalence of the validate_module alias.
Documentation aligned to validate_surface docs/topics/README.md, docs/topics/semantic-validation/*, docs/topics/syntax/README.md, docs/topics/syntax/test-plan.md	All topic docs, README examples, and test-plan requirement/test-case rows updated to reference validate_surface. SEMVAL-REQ-008–010, SEMVAL-TP-009–012, SYNTAX-REQ-011, and SYNTAX-TP-021 marked as implemented.

PR auto-close workflow rule

Layer / File(s)	Summary
Auto-close PR body rule AGENTS.md, CHANGELOG.md	New Git Rule requiring Closes #N`` text in PR bodies for issue work. Entry logged in CHANGELOG.md under `[Unreleased] ### Added`.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

A stage named surface rises from the mist,
Where validate_module once kept the list.
Now aliases bow to the new entrypoint,
Deferred facts stay deferred — every check in joint.
✨ The compiler spine grows one spine-knob more —
Closes #10``, shut the door. 🚪

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: expose surface validation stage' directly summarizes the main change: adding a new public compiler stage.
Description check	✅ Passed	The description accurately relates to the changeset, covering validate_surface exposure, compatibility alias, boundary tests, and documentation updates.
Linked Issues check	✅ Passed	The PR fully implements issue #10 requirements: exposes validate_surface as explicit source/surface stage, maintains validate_module as compatibility alias, adds deterministic boundary tests for deferred operations, and documents the stage.
Out of Scope Changes check	✅ Passed	All changes are within scope of issue #10: validate_surface public API, compatibility alias, boundary tests, and documentation updates reflecting the stage split.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}