Skip to content

Reorganize specification navigation#1

Open
ericfj2140 wants to merge 1 commit into
mainfrom
codex/spec-refactor-transposition
Open

Reorganize specification navigation#1
ericfj2140 wants to merge 1 commit into
mainfrom
codex/spec-refactor-transposition

Conversation

@ericfj2140

Copy link
Copy Markdown

Summary

Reorganizes the specification repository into a navigation-first structure while preserving the current protocol text and compatibility surface.

Why

The current repository stores the full marketplace protocol in the root README only. This makes it hard to distinguish normative spec text from history, compatibility guidance, future proposal space, and contributor instructions. This PR keeps the existing specification intact and adds structure around it.

What changed

  • Added SPEC.md as the contiguous compatibility snapshot of the pre-refactor README.
  • Replaced the root README with a repo map, compatibility promise, status legend, pillar links, and exact prior-work references.
  • Added AGENTS.md with guardrails for structural and semantic spec changes.
  • Added docs for the refactor plan, history, compatibility, terminology, and architecture.
  • Added four pillar files for items, orders, payments, and delivery, using copied current-spec sections without semantic changes.
  • Added the e-commerce lane as the first fully expressed lane.
  • Added examples guidance and an escrow/arbitration proposal workspace that references external work without making it canonical.

Validation

  • Confirmed SPEC.md matches the pre-refactor README.md byte-for-byte.
  • Confirmed SPEC.md matches GammaMarkets/market-spec spec.md.
  • Ran exact-block checks for 16 transposed current-spec sections across the lane and pillar files.
  • Confirmed required external links are present.
  • Confirmed kind inventory remains: 0, 14, 16, 17, 10019, 30402, 30405, 30406, 31555, 31989, 31990.

Runtime or visual evidence

Documentation-only change. No runtime surface.

Risks and follow-ups

  • The inherited spec text still has relative NIP links, trailing whitespace, duplicated note numbering, and minor typos. Those are intentionally preserved in SPEC.md for compatibility and should be cleaned up only in a later semantic/no-op editorial PR with explicit review.
  • Escrow, checkout state, agent discovery, and payment status remain proposal space only; this PR does not standardize them.

Preserve the current marketplace specification in SPEC.md while adding contributor guardrails, compatibility/history docs, pillar transpositions, the e-commerce lane, examples guidance, and an escrow proposal workspace.

Validation: SPEC.md matches the pre-refactor README and GammaMarkets/market-spec spec.md; exact-block checks passed for 16 transposed sections.
@ericfj2140 ericfj2140 marked this pull request as ready for review June 19, 2026 20:49
@ericfj2140 ericfj2140 requested a review from S7NC June 19, 2026 20:50
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.

2 participants