Skip to content

Fix 25 spec review issues across core and extensions#32

Merged
gvonness-apolitical merged 1 commit intomainfrom
fix/spec-review-remediation
Feb 22, 2026
Merged

Fix 25 spec review issues across core and extensions#32
gvonness-apolitical merged 1 commit intomainfrom
fix/spec-review-remediation

Conversation

@gvonness-apolitical
Copy link
Collaborator

Summary

Comprehensive remediation of 25 issues identified during spec review, organized by priority:

P0 — Correctness (6 issues)

  • Replace undefined attachment block example with link mark approach
  • Add formal definitions for forms:form and forms:submit block types (field tables + schema)
  • Document locatorType field on citation mark (spec-schema alignment)
  • Add legal extension to extension index (available extensions, compatibility matrix, data files)
  • Fix footnote number/symbol as conditional (not unconditionally required)
  • Add cross-extension footnote model guidance (semantic = canonical)

P1 — Consistency (10 issues)

  • Document extension mark naming convention (new Section 5.1 in content blocks)
  • Add CRDT metadata to hash boundary table (excluded from content hash)
  • Change resetOn from chapter/section to heading1-heading6 (schema + prose)
  • Clarify Person identity field divergence (userId, keyId are additive, not replacements)
  • Rename presentation numbering to numberingConfig to resolve type mismatch with core
  • Add cross-reference mechanism selection guidance table
  • Add formal field tables for change records and reply objects (collaboration)
  • Add field tables for all 7 form field types
  • Document ACL enforcement model as declarative/advisory

P2 — Quality (9 issues)

  • Document glossary discovery mechanism and sort enum values
  • Add semantic:term field table + plain-string rationale
  • Note both CSL date formats as valid for bibliography issued field
  • Add presentation extension file paths section
  • Clarify forms:signature (visual) vs security extension (cryptographic)
  • Document "today" as only supported relative date keyword
  • Document phantom cross-reference limitations
  • Renumber section 1.5a → 1.6
  • Clarify Dublin Core version 1.1 vs Codex version 0.1

Test plan

  • npm test — all schemas compile, all examples validate
  • npm run check:sync — 65 block types synchronized
  • npm run check:refs — 71 cross-references valid
  • npm run check:coverage — all 8 extensions and 15 schemas covered

P0 (Correctness):
- Replace undefined attachment block with link mark example
- Add forms:form and forms:submit formal definitions and schema entries
- Document locatorType field on citation mark
- Add legal extension to extension index tables
- Fix footnote number/symbol as conditional requirement
- Add cross-extension footnote model guidance

P1 (Consistency):
- Document extension mark naming convention (Section 5.1)
- Add CRDT metadata to hash boundary table
- Change resetOn from chapter/section to heading levels
- Clarify Person identity field divergence across extensions
- Rename presentation figure numbering to numberingConfig
- Add cross-reference mechanism selection guidance
- Add change record and reply object field tables
- Add field tables for all form field types
- Document ACL enforcement model as advisory

P2 (Quality):
- Document glossary discovery and sort enum values
- Add semantic:term field table and plain-string rationale
- Note both CSL date formats as valid
- Add presentation extension file paths section
- Clarify forms:signature vs security digital signatures
- Document "today" as only relative date keyword
- Document phantom cross-reference limitations
- Renumber section 1.5a to 1.6
- Clarify Dublin Core version vs Codex version
@gvonness-apolitical gvonness-apolitical merged commit 00a5532 into main Feb 22, 2026
2 checks passed
@gvonness-apolitical gvonness-apolitical deleted the fix/spec-review-remediation branch February 22, 2026 13:46
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