Maintaining the Standards - LiteSpec 2.0.0

Intent#

This page is the maintainer's manual for the LiteSpec repository itself. It states how a provision moves through its lifecycle. It states how an identifier rename is handled. It states how citations are written. It states how a LiteSpec release is published.

The page exists because litespec/core/authoring#publish-each-release-as-a-complete-contract requires each LiteSpec release to state its complete contract. A maintainer who follows those rules needs the procedures this page states.

Concepts#

The provision lifecycle#

A provision passes through three states.

State	Meaning
draft	The provision text is being written.
active	The provision is cited from a validator case or a Verification row.
retired	The provision has been replaced or removed.

A provision never goes from active back to draft. A retirement is permanent.

The identifier#

Every provision ID is litespec/<page>#<slug>, defined by litespec/core/authoring#use-the-declared-identifier-grammar. A rename replaces the identifier outright. The repository keeps no alias and no mapping from an old identifier.

Citations#

A citation from one page to another names the cited provision by its current identifier. A citation on the same page uses the same form.

The LiteSpec release#

A LiteSpec release is a tagged snapshot of the repository. Between releases, litespec.manifest.json, the topmost changelog entry, and the consumer template's reviewedLiteSpecVersion name the release being prepared. The new tag carries that version number and makes the release current. Each schema $id names that release under https://litespec.dev/<version>/schemas/, so a pinned consumer keeps resolving the shapes it reviewed.

Standards#

State the provision lifecycle#

ruleguidance

Requirement A maintainer MUST keep each provision in exactly one of three states: draft, active, or retired.

Rationale The three states tell a maintainer what a provision's identifier means. An active identifier is stable. A retired identifier is gone.

Example A provision is added in draft. When cited from a Verification row it becomes active. When its assertion is folded into a richer rule, the provision is retired.

litespec/core/maintaining#state-the-provision-lifecycle

Replace every citation on a rename#

rulecheckable

Requirement A provision rename MUST replace every citation of the old identifier in one change.

Rationale A citation names the provision it resolves to. An old identifier left behind names nothing, and the repository keeps no alias to resolve it. Citations always use current identifiers.

Example Renaming a provision changes its heading, its ID, its Verification row, and every citation together.

litespec/core/maintaining#replace-every-citation-on-a-rename

Publish a LiteSpec release from a tag#

ruleguidance

Requirement A LiteSpec release MUST carry the highest git tag in the manifest version, the changelog entry, and the consumer template version.

Rationale A git tag is the only durable artifact that names a release. The highest tag is the current release. The manifest version, the changelog entry, and the template version name that release.

litespec/core/maintaining#publish-a-litespec-release-from-a-tag

Conventions#

None.

Reference example#

This informative example demonstrates litespec/core/maintaining#state-the-provision-lifecycle, litespec/core/maintaining#replace-every-citation-on-a-rename, and litespec/core/maintaining#publish-a-litespec-release-from-a-tag.

Step one, adding a provision#

A maintainer writes a new provision on a page. The provision is in draft until a validator case or a Verification row cites it.

Text

### State the rule
**Requirement:** A consumer MUST do the thing.
**Rationale:** The thing matters.

The validator finds the new provision uncited. The maintainer adds a Verification row that names the rule. The provision moves to active.

Step two, renaming#

A rule changes. The maintainer updates the heading, the identifier, and every citation in one change.

Step three, releasing#

The maintainer runs git describe --tags --abbrev=0 to find the tag with the highest version number. The tag is the current release. The manifest version names the release being prepared, the changelog entry is added, and the commit is tagged.

Verification#

ID	Mark	Evidence
litespec/core/maintaining#state-the-provision-lifecycle	guidance	Is every provision in exactly one lifecycle state, with retired identifiers cited nowhere?
litespec/core/maintaining#replace-every-citation-on-a-rename	checkable	`litespec validate` emits no `ID_UNKNOWN_REFERENCE` diagnostic.
litespec/core/maintaining#publish-a-litespec-release-from-a-tag	guidance	Does one new tag carry the current version across the manifest, the changelog, and the template?