docs(dx): make the Stripe-grade DX rubric a binding review gate#43
Conversation
…lden example The architecture-principles.md rubric already exists but is only 'a discussion'; DX is aspirational while security is blocking — so DX gets skipped under pressure. This gives it teeth, at the Security-Requirements tier: - architecture-principles.md: add Principle 12 'the example IS the DX test' — write it first; if it needs a plumbing block, fix the API not the example — with the DelegatedGate raw-seams→facade before/after as the worked golden example (~104→36 lines). Mark the doc a BINDING review lens. - CLAUDE.md: new 'Developer experience — Stripe-grade (DO NOT regress)' section at the same tier as the security invariants; the automated claude-review now checks the rubric; the example-is-the-test rule surfaced. - constitution Principle I: the example is the acceptance test; the rubric is applied in every Constitution Check + PR review; a DX regression is blocking. Version 1.0.0→1.1.0 (reconcile to 1.2.0 vs the concurrent HNP amendment, noted inline). Signed-off-by: Diego Zuluaga <dfzuluaga@gmail.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3582ebb7ca
ℹ️ 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".
| await completeOrder({ order, mandateId, amount, currency, method, gates: [], draw: { intent, draw } }, gate); | ||
|
|
||
| // AFTER — the ceremony lives in the library; the example is the story | ||
| const gate = new DelegatedGate({ catalog: { coffee: 18, wine: { price: 20, minAge: 21 } } }); |
There was a problem hiding this comment.
This binding DX rubric makes DelegatedGate the golden “AFTER” API, but a repo-wide search (rg "DelegatedGate|preApprove|class DelegatedGate") finds it only in these newly added docs, with no implementation or export in the packages. Because this doc is now required for Constitution Checks and PR reviews, contributors will be directed to preserve or use an API that does not exist in the current codebase; either land the facade with the docs or mark this as a proposed/future shape instead of a current tested package surface.
Useful? React with 👍 / 👎.
… on main) Codex review on PR #43 (accurate): the binding rubric cited DelegatedGate as the golden AFTER API, but a repo-wide search on this branch finds it only in the docs — the facade lands via the concurrent PR #41 (005-hnp-seams). Note it as a companion change cited as the worked pattern, not a claim the class is already in the merged tree, so contributors aren't directed to a nonexistent surface. Signed-off-by: Diego Zuluaga <dfzuluaga@gmail.com>
…eams # ------------------------ >8 ------------------------ # Do not modify or remove the line above. # Everything below it will be ignored. # # Conflicts: # .specify/memory/constitution.md
…seams+facade (#41), next increment = intent rail → wallet server Resolved decisions moved to Done (Group-A/Option-B/Decision-13 ratified; rename shipped; 0.2.0 published). Open decisions: approve+merge #41, CLAUDE_CODE_OAUTH_TOKEN, counsel brief. Added the DX-is-blocking standing constraint and the next-increment pointer (HTTP intent rail → wallet server). Signed-off-by: Diego Zuluaga <dfzuluaga@gmail.com>
1 participant
In plain terms
Right now, security is enforced but good API design is only encouraged — the 6 security invariants are blocking (bypass tests, required review), while "Stripe-grade DX" is one paragraph with no gate. So under pressure, DX gets skipped. This PR gives the existing DX rubric the same teeth as the security invariants, so contributors (human and AI) build toward SDKs that are a pleasure to use — by default, not by luck.
The lesson it encodes came straight from PR #41's example work: the example was ugly because the API wasn't Stripe-grade. That's the rule — the example is the DX test; if it needs plumbing, fix the API, not the example.
What you're approving: three doc/governance edits (no code). Nothing changes at runtime; it changes what a PR review is allowed to block on.
What changed
docs/reference/architecture-principles.md— adds Principle 12: "the example IS the DX test" with theDelegatedGateraw-seams→facade before/after as the worked golden example (~104→36 lines: the example got shorter because the API got better). Marks the doc a binding review lens.CLAUDE.md— new "Developer experience — Stripe-grade (DO NOT regress)" section at the security-invariant tier; the automatedclaude-reviewnow checks the rubric; the example-is-the-test rule + a quick 4-point gate..specify/memory/constitution.md— Principle I sharpened: the example is the acceptance test; the rubric is applied in every Constitution Check + PR review; a DX regression is blocking. Version 1.0.0 → 1.1.0.The concurrent PR #41 branch (
005-hnp-seams) also bumps the constitution 1.0.0 → 1.1.0 (the HNP Principles-II/III/VII amendment). The two amendments are independent and additive — whichever merges second must renumber to 1.2.0 and fold both sync-impact entries. Flagged inline in the sync-impact header so it's handled consciously, not discovered at merge.🤖 Generated with Claude Code