📝 docs: refine vision, SEP process, and signature surface#45
Open
zrr1999 wants to merge 24 commits into
Open
Conversation
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1497fde779
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
5 tasks
## Proposal summary - Add `seps/SEP-0010-compiler-as-documentation.md` as a standalone Standards Track SEP for compiler-owned explain surfaces, concept docs, and diagnostic teaching metadata. - Reconnect the SEP suite around that split by adding minimal cross-references from `README.md`, `GLOSSARY.md`, `SEP-0005`, `SEP-0006`, and `seps-index.json`. - Keep this stacked PR narrowly scoped to the design document and SEP cross-links; concrete schema/catalog rollout can follow separately once the design boundary settles. ## Linked discussion Canonical discussion thread: #46 This PR is intentionally stacked on top of #45: - base PR: #45 ## Checklist - [x] I opened or linked a public Discussion or Issue for the pitch before submitting this draft SEP. - [x] I linked the canonical discussion thread. - [x] I used the correct SEP template for this proposal type. - [x] I updated front matter metadata and required sections. - [x] I considered the SEP-0000 guiding questions in the relevant proposal sections. ## Notes for reviewers ### Review focus 1. Does SEP-0010 stay clearly in the teaching/explain layer rather than drifting back into SEP-0006 compiler-core responsibilities? 2. Are the SEP-0005 and SEP-0006 forward references to SEP-0010 at the right boundary? 3. Is it reasonable to land this PR as a doc-and-cross-reference slice first, leaving concrete schema/catalog artifacts for a later follow-up if needed? ### Validation - `prek run -a`: passed
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
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.
Proposal summary
This PR realigns the Spore documentation stack from vision to SEP process to the root language surface.
VISION.mdas principle-level language vision only, centered on theSignature -> Property -> Hole -> Realization -> Evidencepipeline, and adds a synchronized Simplified Chinese vision document.seps/SEP-0000-process.md, including the Pitch -> Draft -> Accepted / Rejected lifecycle, review inside Draft status, canonical guiding questions, and merge-check expectations.uses,budget,properties, body), a compact root item grammar, and explicit delegation of type/effect/budget/hole/concurrency/module/std semantics to later SEPs.seps-index.json, templates, PR checks, dependency metadata, and validation paths with the updated SEP layering and terminology.uses [...]terminology around effects:usesis now the effect surface, HoleReport exposeseffect_context, and the previous capability/checker-capability wording is removed from core docs.README.md,GLOSSARY.md, terminology checks, and style terms; removes the stale rootROADMAP.mdin favor of the SEP-centered reading path.Linked discussion
SEP front matter links the existing public discussion threads for the affected documents:
Canonical review for this combined amendment remains this PR. Because this directly amends already Accepted SEP-0000 and moves SEP-0001 back to Draft, the review focus below explicitly asks whether any part should instead become a follow-up Process or Standards Track SEP.
Checklist
Notes for reviewers
Review focus
Please review this as a documentation/process change with unusually high impact because it edits Accepted SEPs:
VISION.mdstay principle-level while SEP-0000 owns guiding questions and process mechanics?capability->effectterminology consolidation correct, includingeffect_context,EffectContext, andF0xxxeffect diagnostics?Spore->孢子andAgent->智能体?Risks / open questions
Acceptedunder a one-time direct amendment exception; SEP-0001 returns toDraftbecause this PR changes it substantially. Reviewers should decide whether that is acceptable in one PR or whether a separate process/standards amendment is required.ROADMAP.mdmay affect external links; the intended replacement is the README/vision/SEP-index reading path.uses [...]; if needed, it should receive a separate future tooling surface instead of reusing effect terminology.Validation
prek run: passedprek run --all-files: passedgit diff --check: passedgit commit: passedPR title,PR body,prek,repo-checks)