docs: reconcile claim implementation status with reality - #902
Merged
Conversation
ADR 046's amendment (added in #866) said the server serves the three claim endpoints. They exist in the OpenAPI contract and are routed, but the handlers fall back to api.UnimplementedHandler and answer 501 until the claim service and handlers land (#611, #612). The docs site drifted the opposite way, still denying that the zitadel claim command (#754) and the contract (#739) shipped. Reword both directions to the actual boundary. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Contributor
There was a problem hiding this comment.
Pull request overview
Aligns the repository’s documentation with the current implementation boundary of the claim lifecycle: the OpenAPI contract and CLI exist, but the server handlers remain unimplemented (501), so the end-to-end claim flow is not yet functional against a real server.
Changes:
- Update ADR 046 status to Accepted with an amendment clarifying what is shipped vs. pending (handlers/service still open).
- Sync the ADR index row for ADR 046 to match the ADR’s status and boundary statement (to satisfy the index↔body drift gate).
- Update docs-site copy to reflect that
zitadel claimand the OpenAPI endpoints exist, but the server-side claim flow cannot complete yet.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| docs/adrs/README.md | Updates ADR 046’s index status/summary to “Accepted” and clarifies partial implementation vs. pending handlers. |
| docs/adrs/046-claim-lifecycle-v2.md | Changes status to “Accepted” and adds an amendment explicitly stating 501 behavior until #611/#612 land. |
| apps/docs/content/docs/index.mdx | Corrects “claim isn’t shipped” messaging to reflect shipped CLI/contract but missing server handlers. |
| apps/docs/content/docs/concepts/project-team-user.mdx | Updates the preview note to match the same shipped boundary (CLI/contract shipped; handlers pending). |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
fforootd
approved these changes
Aug 14, 2026
IAM-marco
added a commit
that referenced
this pull request
Aug 20, 2026
) ## Summary - ADR 046's status and amendment (last set by #902) still said the server-side claim handlers answer 501 with #611 and #612 open. Both closed: #909 added the claim service and #912 wired the handlers with integration tests. Reword the status to `Implemented` and rewrite the amendment to the full shipped list (#739, #628, #740, #751, #754, #776, #909, #912), including one clause on claim state being the unique active owning-team grant in `authz_assignments` (anticipating proposed ADR 054 §2). - Update the `docs/adrs/README.md` index row to match. - Reword the two docs-site pages (`index.mdx`, `concepts/project-team-user.mdx`) to the same boundary. - The nuance that survives everywhere: the console claim page is not shipped yet (#615), so the browser leg of the flow has no guided UI and currently requires driving the API directly. The docs do not claim a working browser flow. ## Validation - `node scripts/check-adrs-index.mjs` (adr index: ok, 54 records) - `node scripts/check-pr-title.mjs --title "docs: mark the claim flow implemented in ADR 046 and the docs site"` - `rg -n "501|not implemented|cannot complete|handlers land"` and `rg -n "#611|#612"` over `docs/` and `apps/docs/` return no hits - No em or en dashes introduced in the edited text ## Release notes / changeset No changeset required: documentation only, no shipped behavior changed. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/projects/{project_id}/claim/{init,status,complete}. The routes exist in the OpenAPI contract and are mounted, but the handlers fall back toapi.UnimplementedHandlerand answer 501: there is no claim service yet, andverifyClaimSession(the C2 precondition) has no production caller. The claim service and handlers are still open as Claim E1: claim service (init/status/complete) #611 and Claim E2: claim handlers and integration tests #612.Acceptedwith an amendment naming the actual boundary: contract (feat(api): add claim lifecycle endpoints to the OpenAPI contract #739),claim_challengesstorage (feat(migration): add claim_challenges table (#607) #628, refactor(database): add claim challenge statements and the personal-team lookup #740), platform-session precondition (feat(api): verify platform session for claim/complete #751), CLIzitadel claim(feat: add the zitadel claim command #754), and team-attachment reporting (feat: report team attachment in setup, status, and doctor #776) shipped; server handlers pending (Claim E1: claim service (init/status/complete) #611, Claim E2: claim handlers and integration tests #612).docs/adrs/README.mdindex row to match (the docs: reconcile ADR statuses with reality and gate index-status drift #866 drift gate requires it).index.mdxandconcepts/project-team-user.mdxstill saidzitadel claimand the claim endpoints do not exist. Reword both to the same boundary.Validation
node scripts/check-adrs-index.mjs(adr index: ok, 51 records)node scripts/check-pr-title.mjs --title "docs: reconcile claim implementation status with reality"Release notes / changeset
No changeset required: documentation only, no shipped behavior changed.
🤖 Generated with Claude Code