Repository navigation
docs: mark the type descriptor spec as settled but living - #157
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
I reviewed this PR's documentation and process changes to the type descriptor spec and AGENTS.md.
- Spec header: The leading doc comment in
spec/type-descriptor.tsgets a new paragraph. It says the spec is a living document but a settled one: a change to it is a design decision agreed with a maintainer first, and a limitation found while implementing it is raised instead of worked around. No types change. AGENTS.md"What is where": Thespec/type-descriptor.tsrow now carries the same note.AGENTS.md"Where to change what": There is a new row for the type descriptor format, whichnub run typecheckchecks. I confirmed this is accurate:tsconfig.jsonlists"spec"ininclude, sotsc --noEmittype-checks the spec's examples.
The wording matches how the .reylo.yaml row already describes a design decision, and it follows the repo's Markdown rules (no hard wraps, no people named).
claude-opus-5-5 ｜ 𝕏
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues remain for the documentation updates clarifying the specification’s change policy and contributor guidance.
No open issues 🎉
What changed in this PR
Clarifies that Reylo’s type descriptor specification is settled but can evolve through agreed design changes. This PR changes documentation only; types and runtime behavior are unchanged.
Changes:
- Documents maintainer agreement before spec changes and requires implementation limitations to be raised rather than worked around.
- Adds contributor guidance identifying the spec’s location and its type-check command.
| File | Description |
|---|---|
spec/type-descriptor.ts |
Expands the introductory comment with the spec’s design-change policy. |
AGENTS.md |
Clarifies the spec’s status and adds a “Where to change what” entry. |
Review effort: Balanced
States, at the top of
spec/type-descriptor.tsand inAGENTS.md, that the type descriptor spec is a living document but a settled one: a change to it is a design decision, agreed with a maintainer before it is written, and a limitation that implementing it shows is raised rather than worked around.AGENTS.mdalso gains a "Where to change what" row for it.