Skip to content

📝 docs: refine vision, SEP process, and signature surface#45

Open
zrr1999 wants to merge 24 commits into
mainfrom
refine-vision-sep-process
Open

📝 docs: refine vision, SEP process, and signature surface#45
zrr1999 wants to merge 24 commits into
mainfrom
refine-vision-sep-process

Conversation

@zrr1999

@zrr1999 zrr1999 commented May 22, 2026

Copy link
Copy Markdown
Member

Proposal summary

This PR realigns the Spore documentation stack from vision to SEP process to the root language surface.

  • Reframes VISION.md as principle-level language vision only, centered on the Signature -> Property -> Hole -> Realization -> Evidence pipeline, and adds a synchronized Simplified Chinese vision document.
  • Moves process mechanics and design-review prompts into seps/SEP-0000-process.md, including the Pitch -> Draft -> Accepted / Rejected lifecycle, review inside Draft status, canonical guiding questions, and merge-check expectations.
  • Materially revises the already Accepted SEP-0000: SEP now means Spore Evolution Proposal, SEP-0000 becomes the stronger owner of governance/process mechanics, and bootstrap amendment rules make direct accepted-SEP edits explicit rather than silent.
  • Moves SEP-0001 back to Draft while revising the signature/root surface grammar: Base Signature + Intent Signature clauses, fixed clause order (uses, budget, properties, body), a compact root item grammar, and explicit delegation of type/effect/budget/hole/concurrency/module/std semantics to later SEPs.
  • Aligns SEP-0002 through SEP-0009, seps-index.json, templates, PR checks, dependency metadata, and validation paths with the updated SEP layering and terminology.
  • Unifies the public uses [...] terminology around effects: uses is now the effect surface, HoleReport exposes effect_context, and the previous capability/checker-capability wording is removed from core docs.
  • Updates README.md, GLOSSARY.md, terminology checks, and style terms; removes the stale root ROADMAP.md in 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

  • I opened or linked a public Discussion or Issue for the pitch before submitting this draft SEP.
  • I linked the canonical discussion thread.
  • I used the correct SEP template for this proposal type.
  • I updated front matter metadata and required sections.
  • I considered the SEP-0000 guiding questions in the relevant proposal sections.

Notes for reviewers

Review focus

Please review this as a documentation/process change with unusually high impact because it edits Accepted SEPs:

  1. Accepted SEP governance: Are the changes to SEP-0000 appropriate as a direct update, or should some of this be split into a follow-up Process SEP?
  2. Draft language surface: Is the SEP-0001 rewrite acceptable as the draft root surface grammar, or should it be treated as a replacement Standards Track proposal instead?
  3. Responsibility boundaries: Does VISION.md stay principle-level while SEP-0000 owns guiding questions and process mechanics?
  4. Signature scope: Does SEP-0001 correctly specify only the root surface and delegate deeper semantics to SEP-0002 through SEP-0009?
  5. Effect terminology: Is the capability -> effect terminology consolidation correct, including effect_context, EffectContext, and F0xxx effect diagnostics?
  6. Bilingual terminology: Are the Chinese vision and core glossary mappings correct, especially Spore -> 孢子 and Agent -> 智能体?

Risks / open questions

  • SEP-0000 remains Accepted under a one-time direct amendment exception; SEP-0001 returns to Draft because this PR changes it substantially. Reviewers should decide whether that is acceptable in one PR or whether a separate process/standards amendment is required.
  • Removing ROADMAP.md may affect external links; the intended replacement is the README/vision/SEP-index reading path.
  • The signature grammar is intentionally a root-surface contract. Follow-up SEPs still need to preserve the delegation boundaries introduced here.
  • Non-effect checker or Agent guidance is now explicitly out of uses [...]; if needed, it should receive a separate future tooling surface instead of reusing effect terminology.

Validation

  • prek run: passed
  • prek run --all-files: passed
  • git diff --check: passed
  • zendev title validation: passed
  • zendev body validation: passed
  • commit hook suite via git commit: passed
  • GitHub PR checks after latest push: passed (PR title, PR body, prek, repo-checks)

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread scripts/check_surface_consistency.py Outdated
Comment thread scripts/check_surface_consistency.py Outdated
@zrr1999 zrr1999 changed the title Refine vision, SEP process, and Signature v2 surface 📝 docs: refine vision, SEP process, and Signature v2 surface May 22, 2026
@zrr1999 zrr1999 changed the title 📝 docs: refine vision, SEP process, and Signature v2 surface 📝 docs: refine vision, SEP process, and signature surface May 24, 2026
zrr1999 and others added 14 commits May 28, 2026 09:56
## 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant