Skip to content

Rationalize proposals/: consolidate design docs into RFCs#69

Merged
akollegger merged 2 commits into
mainfrom
proposals/rationalize
Jun 18, 2026
Merged

Rationalize proposals/: consolidate design docs into RFCs#69
akollegger merged 2 commits into
mainfrom
proposals/rationalize

Conversation

@akollegger

Copy link
Copy Markdown
Contributor

Overview

Cleans up the proposals/ tree so it has a single clear organizing principle. After the earlier RFC restructure, the same designs lived in two places (older top-level proposals and the numbered RFCs that superseded them), the RFC index had a broken link, and supporting notes were mixed in with authoritative RFCs. This PR consolidates everything, with no design content lost — anything unique was migrated into RFC appendices before its source file was removed.

Final structure

proposals/
├── graph-value-instances.md   # pre-RFC stub
├── pattern-equivalence.md      # pre-RFC stub
├── research/                   # NEW: non-RFC supporting notes
│   └── (graph-lens, gram-hs-cli-*, pattern-basic-aspects-review, pattern-matching-dsl-design)
└── rfc/                        # README + RFC-001..010 only

What changed

Removed (fully superseded, nothing unique lost):

  • 8 top-level proposals already absorbed by RFCs (graph-classifier, graph-query, graph-mutation, graph-transform, pipeline-scenarios, scope-unification-proposal, representation-map-proposal, pattern-reconciliation)
  • SEMANTICS.md and EXTENDED-SEMANTICS.md (fully covered by RFC-003)

Migrated then removed (had unique content):

  • pattern-graph.mdRFC-004 Appendix A (PatternGraph container design)
  • DESIGN.mdRFC-002 Appendix B (deferred design sketches behind the open questions)
  • pattern-category.mdRFC-002 Appendix A (value magma, layered CategoryLens, worked example, applications)

Reorganized:

  • Moved 5 non-RFC docs into a new proposals/research/ directory
  • Elevated graph-value-instances.md to an indexed pre-RFC stub

Fixed references:

  • Repaired the broken RFC-001 README row (was pointing at RFC-001-strata-and-aspects.md with pre-rename "strata/aspects" terminology) — the last lingering trace of the strata→frames / aspects→spans rename
  • Rewrote the README index with an absorbed-document provenance table and a newcomer orientation section
  • De-linked all RFC Supersedes: headers that pointed at removed files (kept as plain provenance text)
  • Repointed 8 specs/ Input: provenance lines to their superseding RFCs (original prompt text preserved, accurate pointer appended)

Reviewer notes

  • This is docs-only — no source or test changes.
  • The two commits separate the mechanical proposals/design/proposals/rfc/ rename from the substantive consolidation, so the diff is easier to follow commit-by-commit.
  • Deletions of DESIGN.md and pattern-category.md were gated on a verification pass confirming their unique content was carried into RFC-002's new appendices; the specs/ Input: lines were intentionally left as historical records with the pointer appended rather than rewritten.
  • Verified: no broken internal links remain anywhere in the repo (README links, RFC cross-references, and spec→RFC links all resolve).

🤖 Generated with Claude Code

akollegger and others added 2 commits June 18, 2026 14:50
Move all design documents into a proposals/rfc/ directory and fix the
two stale "proposals/design/..." display labels in the Supersedes lines
of RFC-002 and RFC-003.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Clean up the proposals/ tree so rfc/ holds only the authoritative README +
RFC-001..010:

- Delete 8 top-level proposals fully superseded by RFCs (graph-classifier,
  graph-query, graph-mutation, graph-transform, pipeline-scenarios,
  scope-unification-proposal, representation-map-proposal,
  pattern-reconciliation).
- Migrate PatternGraph design into RFC-004 Appendix A; delete pattern-graph.md.
- Migrate DESIGN.md (deferred sketches) and pattern-category.md (categorical
  detail) into RFC-002 Appendices A/B; delete both. SEMANTICS.md and
  EXTENDED-SEMANTICS.md were fully covered by RFC-003 and are removed.
- Elevate graph-value-instances.md to an indexed pre-RFC stub.
- Move 5 non-RFC docs into new proposals/research/.
- Fix the broken RFC-001 README row (frames-and-spans), rewrite the README
  index with absorbed-document provenance and a newcomer orientation section,
  and de-link all RFC Supersedes headers that pointed at removed files.
- Repoint specs/ Input provenance lines to their superseding RFCs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@akollegger akollegger merged commit d310558 into main Jun 18, 2026
1 check 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