Repository navigation
feat(spec): draft lifecycle with retractable pre-promotion identity (ADR-0003) - #23
Merged
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
Adopts ADR-0003 by introducing a retractable draft lifecycle tier (persistence guarantee attaches at draft → candidate promotion) and aligns the schema/tooling/docs to the updated identifier and status semantics, including the ADR-0002 shift to a 3-field deterministic reference seed.
Changes:
- Add
draftto the sharedStatusenum and propagate it through OpenAPI and governance/spec/versioning documentation. - Remove
normalization_version(andexamples) from the data model and validation/compile pipeline; introduce requiredCitationSystem.description. - Update JSON-LD context and record pages/docs to reflect the revised shapes and deterministic identifier seed.
Reviewed changes
Copilot reviewed 25 out of 25 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| standard/schema/common.ts | Adds draft to the Zod Status enum and removes SemVer helper. |
| standard/schema/citation-system.ts | Removes normalization_version/examples, adds required description, simplifies regex validation. |
| standard/schema/canonical-reference.ts | Removes normalization_version from CanonicalReference schema. |
| src/pages/id/system/[key]/index.astro | Updates system landing page to show description; removes normalization/examples rendering. |
| src/pages/id/ref/[uuid]/index.astro | Removes display of normalization_version on reference pages. |
| src/lib/registry.fixture.ts | Updates fixture registry objects to match new schema (adds description, drops normalization_version). |
| src/content/docs/standard/versioning.md | Documents draft lifecycle, retraction rules, and promoted/non-draft constraints. |
| src/content/docs/standard/system-profiles.md | Reworks profile requirements around canonical locator form and description (no examples/version). |
| src/content/docs/standard/specification.md | Updates normative model: adds description, removes normalization_version, adds draft persistence semantics. |
| src/content/docs/standard/json-ld.md | Updates JSON-LD context documentation (adds description, removes old fields). |
| src/content/docs/standard/identifier-syntax.md | Updates deterministic seed definition (3-field) and scopes immutability to candidate+. |
| src/content/docs/get-started/url-layout.md | Updates example reference UUID/URLs to new deterministic seed output. |
| src/content/docs/get-started/mappings-and-resolver-targets.md | Updates example payloads to remove normalization_version. |
| src/content/docs/get-started/how-it-works.md | Updates explanation/examples to the 3-field deterministic ID seed. |
| src/content/docs/get-started/authoring.md | Updates authoring guidance/example system YAML to use description instead of version/examples. |
| src/content/docs/de/association/governance.md | Mirrors governance lifecycle/status and persistence-guarantee changes in legally binding DE text. |
| src/content/docs/association/governance.md | Mirrors governance lifecycle/status and persistence-guarantee changes in EN text. |
| scripts/validate-data.ts | Updates deterministic UUID validation seed to 3 fields. |
| scripts/compile.ts | Removes normalization version usage and updates reference UUID seed and system shape. |
| public/contexts/v1.jsonld | Updates the published JSON-LD context (adds description, removes normalization_version/examples). |
| decisions/ADR-0003-draft-lifecycle-ephemeral-identity.md | Adds ADR-0003 documenting the draft lifecycle and persistence attachment at promotion. |
| decisions/ADR-0002-uuid-seed-semantic-identity.md | Adds ADR-0002 documenting 3-field deterministic reference UUID seeding. |
| CONTRIBUTING.md | Updates review tracks and flowchart to reflect draft entry and promotion semantics. |
| api/openapi.yaml | Adds draft to Status enum; updates schemas to add description and remove old fields. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| The compiler enforces: an active `CanonicalReference` MUST NOT reference a tombstoned `Work` or `CitationSystem` through `work_key` or `citation_system_key`. `MappingAssertion`s are exempt — successor links from a withdrawn subject to an active target are exactly the documented pattern. | ||
|
|
||
| Analogously, a promoted (`candidate` or higher) record MUST NOT reference a `draft` `Work` or `CitationSystem` through its keys: systems and works are promoted before or together with the records that depend on them. |
Adopt ADR-0003 (fixes textrefs#22): new draft status is an ephemeral tier below candidate. The identifier-persistence promise attaches at the promotion event (draft -> candidate, expert review), not at publication. Draft records may be corrected (identity change mints a different id) or retracted (deleted, no tombstone); a re-proposed tuple regains the same UUID by construction. All records keep deterministic v5 ids at every stage - governance §6.3/6.4 no longer prescribes generated ids for provisional objects. - specification §11/§12: promotion semantics + draft status definition - identifier-syntax: immutability scoped to candidate-or-higher - versioning: ladder, draft-retraction section, promoted-must-not-cite- draft invariant (enforcement is an ADR follow-up) - governance EN/DE §4-§6: entry via technical review, promotion via expert review, tombstones scoped to promoted records - CONTRIBUTING: review tracks + flowchart - Status enum: draft added (Zod + OpenAPI) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
All records enter the ADR-0003 ladder at draft; see textrefs/registry#7. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
maehr
force-pushed
the
feat/22-draft-lifecycle
branch
from
July 5, 2026 19:23
05cf591 to
4fa6919
Compare
maehr
added a commit
to textrefs/registry
that referenced
this pull request
Jul 5, 2026
* feat(data)!: demote all records to draft status One-time bootstrap demotion, companion to textrefs/textrefs.org#23 (ADR-0003): the draft lifecycle attaches the identifier-persistence promise at promotion (draft -> candidate, expert review). No record has had expert review yet and the registry is unreleased, so no persistence promise was ever publicly made; every work, mapping, and system record re-enters the ladder at draft. ADR-0003's promotion path is one-way from here on. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * chore: retrigger validate after textrefs.org#23 landed on staging --------- Co-authored-by: Moritz Mähr <14755525+maehr@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This was referenced Jul 5, 2026
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.
Fixes #22. Stacked on #21 — contains its commits; merge #21 first, then this diff reduces to ADR-0003 + the lifecycle amendments.
What
Adopts ADR-0003 (included): a new
draftstatus forms an ephemeral tier belowcandidate, and the identifier-persistence promise attaches at the promotion event (draft → candidate, expert review) instead of at publication.draftafter technical review; rendered flagged + noindexed (follow-up), included in dumps withstatusas the signal — same convention as tombstones.statusonly, MUST NOT change identity fields — the IRI survives promotion. From there the record is permanent and tombstone rules apply unchanged.Work/CitationSystem.Changes
decisions/ADR-0003-draft-lifecycle-ephemeral-identity.md(Status: Proposed)specification.md§11 (promotion semantics) + §12 (draftdefinition)identifier-syntax.md— immutability scoped tocandidate-or-higher, draft exemptionversioning.md— status ladder, new Draft records and retraction section, promoted-must-not-cite-draft invariant (normative; compiler enforcement is an ADR follow-up)draftbullets, §5.3 tombstones scoped to promoted records, §6.3/6.4 reworkedCONTRIBUTING.mdreview tracks + flowchartdraftadded instandard/schema/common.tsandapi/openapi.yaml(additive, no data uses it yet)Follow-ups (tracked in the ADR)
Compiler invariant enforcement, draft banner/noindex rendering, downgrading current seed data to
draft, optional CI persistence diff.Verification
npm run verify: format, astro check, full build with internal-link validation — green.npm run validate:data: 39,250/39,250 records valid (enum addition breaks nothing).🤖 Generated with Claude Code