Browse pages
Product Release
A product release is the verified behavior a team ships as one immutable artifact. Teams apply this page at every release to run the checks their boundaries select, to read completion computed from proof, and to write the release record and the verification report. A project that selects the Delivery extension adds its deployment and rollback rules on top.
Stack: any
Layer: operations
Concepts#
Git Is the Decision Record#
A record present in git is decided, and the pull request that changes it is its review. A record the product drops is deleted; git keeps its history. A project that names who answers for an area names them in CODEOWNERS.
Completion Is Computed#
Completion is computed from proof: has code, has tests, scenarios pass. The builder computes it on every run, and the book leads with it. Nobody types it.
The Release Gate#
The gate admits a release when its G checks are green, its scenarios are verified, its S checks are green where the reader is qualified, and every exception it relies on is live. An exception is live while it is present and unexpired. G checks read records only and always block; every missing required link is G. S checks read code through a stack reader: they block where that reader is qualified and report otherwise. A checks report without blocking. litespec model check --release makes the release-readiness findings block, so the gate is a command. A project that selects the Delivery extension adds its formal readiness gate, deployment and rollback rules on top of this gate.
The Verification Report#
Each change ships with a verification report beside it: the exact commands run, their outcomes, the evidence scope, skipped checks with reasons, generated differences, scope limits, and covered use cases. The report tells a reader precisely what the evidence covers and what it does not.
Checker Qualification#
A stack reader is qualified by fixtures: a known good tree it passes and a known bad tree where it reports each planted defect. Only a qualified reader gates its scope with S checks; elsewhere the same checks report without blocking.
Verified Behavior and Journey Evidence#
A use case is implemented when its handler exists, and verified when every one of its scenarios has a passing proof through the public boundary, as the model page states. A journey test proves that connected use cases produce one observable product outcome through the deployed public boundary, catching the wiring, permission, and data defects that narrower suites miss.
The Release Record#
Each release creates one release record for its immutable artifact. The record names the source commit and the immutable artifact reference, and lists the included journeys, use cases, and extensions. It stays non-authoritative: specifications own behavior and scenarios, so the record links outward instead of restating them. Release records live under .litespec/releases/ unless the project records another location. A project that selects the Delivery extension adds the evidence and operating readiness lists that extension states.
Boundaries Select Checks#
Each changed boundary adds the checks written for it. A change that touches several boundaries runs every check each one selects.
| Changed boundary | Checks the change runs |
|---|---|
| Backend | The release build and the backend test suites |
| Frontend | Frozen installation, lint, type checking, tests, and the production build |
| Journey | Its journey tests through the deployed boundary |
| Intent or Behavior | G checks with the book |
| Extension | The verification its extension states |
Debt, Gaps, and the First Release#
Accepted debt never sits as an untracked compromise: it lives as an exception of kind gap with an expiry date, whose findings report until the date and whose exception-expired reports after it. The model page states the exception shape. Governance is a group of records beside the four record layers, not a fifth layer.
A release record binds evidence to one artifact, so a product with no artifact yet has nothing to record in one. Before its first production release, the consumer keeps a readiness record instead, with dated rehearsals, green gates, and a backup and restore rehearsal.
The Adopted LiteSpec Release#
A consumer adopts one LiteSpec release by installing the LiteSpec.Cli tool package at that release version and recording the same version in reviewedLiteSpecVersion. Each LiteSpec release publishes the tool package and the site at the release version together. A consumer upgrades by changing the tool version and reviewedLiteSpecVersion together, after reading the contract the new release states.
Standards#
Verify Connected Journeys#
ruleruleguidancelitespec/core/release#verify-connected-journeysA completed journey MUST connect verified use cases to one observable outcome through a deployed public boundary.
Applies toartifact: record:journey
Why
Use cases that pass in isolation can still fail together: wiring, permissions, and data cross boundaries the isolated tests never touch. A journey test that runs verified use cases to one observable outcome through the deployed public boundary proves the connected path customers actually take.
Checka reviewer answers
Reviewed forWhich completed journeys lack a passing test through the deployed boundary? Look at the journey tests beside each included journey.
Marked guidance: a reviewer answers this question.
Run Boundary-Selected Checks#
ruleruleguidancelitespec/core/release#run-boundary-selected-checksA release change MUST run every check selected by its changed backend, frontend, journey, Intent, Behavior, and extension boundaries.
Applies toartifact: any
Why
Each boundary carries failures the others cannot see: frontend checks say nothing about migrations, and backend suites say nothing about rendered screens. Running every check the changed boundaries select keeps each change evidenced where its failure lives. A narrow category that passes alone certifies only part of the change.
Checka reviewer answers
Reviewed forWhich changes lack a passing result for a check their boundaries select? Look at the change report beside the boundary table.
Marked guidance: a reviewer answers this question.
Run Backend Release Checks#
ruleruleguidancelitespec/core/release#run-backend-release-checksA backend change MUST pass the release build and the backend test suites.
Applies toartifact: any; conformance: full
Why
The release build compiles the solution in release mode, catching the conditional and optimization-gated breaks a debug build hides. The architecture, integration, and acceptance suites the size requires prove architecture layering, wiring, and behavior in turn. Skipping any of them ships backend code the project's own suites do not fully prove.
Checka reviewer answers
Reviewed forWhich backend changes lack a passing release build or suite result? Look at the build and suite reports beside the change.
Marked guidance: a reviewer answers this question.
Run Frontend Release Checks#
ruleruleguidancelitespec/core/release#run-frontend-release-checksA frontend change MUST run frozen installation, lint, type checking, tests, and production build checks.
Applies toartifact: any; conformance: full
Why
Each step guards a different failure: frozen installation pins dependencies, lint and type checking catch static defects, tests prove behavior, and the production build proves the shipped bundle compiles. A frontend that skips one arrives at release with that whole class of defect unchecked.
Checka reviewer answers
Reviewed forWhich frontend changes lack a passing install, lint, type, test, or build result? Look at the frontend reports beside the change.
Marked guidance: a reviewer answers this question.
Run Journey Checks#
ruleruleguidancelitespec/core/release#run-journey-checksA journey change MUST run its journey tests.
Applies toartifact: record:journey
Why
A journey change alters the connected path, so only a journey test through the deployed public boundary can prove it still reaches its outcome. Narrower suites keep passing while the journey itself breaks.
Checka reviewer answers
Reviewed forWhich journey changes lack passing journey tests? Look at the journey reports against the deployed boundary.
Marked guidance: a reviewer answers this question.
Run Consistency Checks#
rulerulecheckablelitespec/core/release#run-consistency-checksAn Intent or Behavior change MUST pass the G checks with the book.
Applies toartifact: any
Why
G checks read records only: shape, references, links, reachability, coverage, and the Behavior rules the check list names. Without them, a renamed record or a moved file silently breaks the references other pages rely on, and the book renders a graph that no longer holds. litespec model check --since <ref> blocks only on findings about records and code changed since <ref> and reports the rest, so an adopting project clears new findings first.
Checkchecked by a tool
Checked bylitespec model check exits zero with no G finding.
Marked checkable: the tool named here checks it.
Run Extension Checks#
ruleruleguidancelitespec/core/release#run-extension-checksA selected project or applicable local extension MUST run its stated verification when affected.
Applies toartifact: any
Why
An extension adds behavior, tests, and operating surface beyond the baseline. Its stated verification is the only evidence written for that surface, so skipping it releases extended behavior the baseline checks never examine.
Checka reviewer answers
Reviewed forWhich affected extensions lack their stated verification evidence? Look at the extension evidence beside the change.
Marked guidance: a reviewer answers this question.
Regenerate Application Contracts#
ruleruleguidancelitespec/core/release#regenerate-application-contractsA source change MUST regenerate OpenAPI and frontend API types when it changes their source contract.
Applies toartifact: any; conformance: full
Why
OpenAPI and frontend API types derive from a source contract. A source change that leaves the committed copies stale ships clients built against a contract the server no longer honors.
Checka reviewer answers
Reviewed forWhich committed contracts differ from a fresh generation? Look at the contract diff beside the source change.
Marked guidance: a reviewer answers this question.
Keep Generated Contracts Stable#
ruleruleguidancelitespec/core/release#keep-generated-contracts-stableA generated application contract MUST be stable and exclude timestamps, machine paths, and nondeterministic ordering.
Applies toartifact: any; conformance: full
Why
Timestamps, machine paths, and unstable ordering make every regeneration look like a behavior change. Deterministic output keeps contract diffs reviewable, so a reviewer sees only the changes that matter.
Checka reviewer answers
Reviewed forWhich contract diffs hold timestamps, machine paths, or unstable order? Look at the generated diff beside each contract.
Marked guidance: a reviewer answers this question.
Qualify the Checker with Known Good and Known Bad Fixtures#
ruleruleguidancelitespec/core/release#qualify-the-checker-with-known-good-and-known-bad-fixturesA stack reader MUST pass its known good and known bad fixtures before it gates with S checks.
Applies toartifact: any; conformance: full
Why
An unqualified reader blocks on noise or passes on silence, and each mistake trains the team to ignore its findings. Passing a known good tree and reporting each planted defect in a known bad tree proves the reader sees what it claims before it blocks any change.
Example
The .NET reader passes the clean tree and reports the planted undeclared write before its S findings block.
Checka reviewer answers
Reviewed forWhich gating S readers lack passing fixture runs? Look at the fixture results beside the stack reader.
Marked guidance: a reviewer answers this question.
Apply Release Access Controls#
ruleruleguidancelitespec/core/release#apply-release-access-controlsA release with restricted access MUST provide authentication and authorization.
Applies toartifact: any; conformance: full
Why
Restricted behavior without authentication accepts callers nobody identified, and without authorization it accepts actions nobody permitted. Both decisions call for a trusted identity and a declared permission before the behavior ships.
Checka reviewer answers
Reviewed forWhich restricted release paths lack authentication or authorization? Look at the guards on each restricted path.
Marked guidance: a reviewer answers this question.
Record the Release Artifact#
ruleruleguidancelitespec/core/release#record-the-release-artifactA release MUST create one release record for its immutable artifact.
Applies toartifact: any
Why
Evidence scattered across builds and reports answers no single question. One release record per immutable artifact binds every result to the exact output it proves.
Checka reviewer answers
Reviewed forWhich releases lack one record naming the immutable artifact? Look at the release records beside each artifact.
Marked guidance: a reviewer answers this question.
Resolve Release Blockers#
ruleruleguidancelitespec/core/release#resolve-release-blockersA release MUST settle every expired exception and every external claim it depends on, or exclude the affected behavior from every owning record.
Applies toartifact: any
Why
An expired exception is a promise past its date, and an unverified external claim behind released behavior is a promise with unsettled terms: a provider fact, a law text, or a term nobody rechecked. Settling each one, or excluding the affected behavior from every owning record, keeps the Intent and release records agreeing on what shipped. exception-expired reports every expired exception.
Checka reviewer answers
Reviewed forWhich releases depend on an expired exception or an external claim without excluding the behavior? Look at the exceptions and claims beside the owning records.
Marked guidance: a reviewer answers this question.
Report Verification Exactly#
ruleruleguidancelitespec/core/release#report-verification-exactlyA completion report MUST name exact commands, outcomes, evidence scope, skipped checks, generated differences, scope limits, and covered use cases.
Applies toartifact: any
Why
A vague report lets unrun checks hide among completed ones. Naming exact commands, outcomes, scope, omissions, and limits tells a reviewer precisely what the evidence covers and what it does not.
Checka reviewer answers
Reviewed forWhich completion reports lack commands, outcomes, scope, omissions, differences, limits, or covered use cases? Look at the report beside the change.
Marked guidance: a reviewer answers this question.
Identify Immutable Release Artifacts#
ruleruleguidancelitespec/core/release#identify-immutable-release-artifactsA release record MUST name source commit and immutable artifact reference.
Applies toartifact: any
Why
The source commit names the verified input and the artifact reference names the deployed output. Together they bind the record to one build, so evidence from another build cannot stand in for it.
Checka reviewer answers
Reviewed forWhich release records lack a source commit or artifact reference? Look at the record header beside each artifact.
Marked guidance: a reviewer answers this question.
List Included Release Behavior#
ruleruleguidancelitespec/core/release#list-included-release-behaviorA release record MUST list included journeys, use cases, and selected applicable extensions.
Applies toartifact: any
Why
The behavior boundary of an artifact is exactly its journeys, use cases, and extensions. Listing them tells operators and reviewers what the artifact contains and, by omission, what it does not.
Checka reviewer answers
Reviewed forWhich records omit an included journey, use case, or extension? Look at the behavior list on each release record.
Marked guidance: a reviewer answers this question.
Keep Release Records Non-Authoritative#
ruleruleguidancelitespec/core/release#keep-release-records-non-authoritativeA release record MUST NOT restate a specification or copy a scenario.
Applies toartifact: any
Why
Specifications own behavior and scenarios. A release record that restates them becomes a second copy, and the copies drift until nobody knows which one holds. The record links outward instead.
Checka reviewer answers
Reviewed forWhich release records restate a specification or copy a scenario? Look at the record beside the linked specifications.
Marked guidance: a reviewer answers this question.
Record Accepted Debt as an Exception#
ruleruleguidancelitespec/core/release#record-accepted-debt-as-an-exceptionAccepted debt MUST live as an exception of kind gap with an expiry date.
Applies toartifact: record:exception
Why
Accepted debt with no expiry date is forgotten work. An exception of kind gap with one turns it into a dated promise whose findings report until the date and whose exception-expired reports after it. The model page states the exception shape.
Example
Claimwick ships month-end export without its archive proof, so the debt lives as an exception of kind gap with an expiresOn of 2027-03-01; exception-expired reports it after that date.
Checka reviewer answers
Reviewed forWhich accepted debts lack an exception of kind gap with an expiry date? Look at the exceptions beside each debt.
Marked guidance: a reviewer answers this question.
State Each Release as a Complete Record#
ruleruleguidancelitespec/core/release#state-each-release-as-a-complete-recordA release record MUST state its complete behavior and evidence without depending on an earlier release record.
Applies toartifact: any
Why
A release judged from fragments is judged by archaeology: the reader digs through other records to fill the gaps. A complete record lets one reader judge one release from one page, with no upgrade guide filling in.
Checka reviewer answers
Reviewed forWhich release records depend on an earlier record to be judged? Look at the record alone beside its links.
Marked guidance: a reviewer answers this question.
Conventions#
Store Release Records Together#
conventiondefaultguidancelitespec/core/release#store-release-records-togetherKeep release records under .litespec/releases/.
ReplacementA consumer records a release-path convention naming where its release records live.
Applies toartifact: any
Why
One folder for release records tells a maintainer where to find the evidence for any artifact. A record filed elsewhere looks missing while readers open the folder and find nothing there.
Example
.litespec/releases/2026-08-21.md records one immutable artifact and its evidence.
Checka reviewer answers
Reviewed forWhich release records sit outside .litespec/releases/ without a recorded release path convention? Look at the release paths beside the convention.
Marked guidance: a reviewer answers this question.
Reference Example#
This informative example demonstrates litespec/core/release#verify-connected-journeys and litespec/core/release#identify-immutable-release-artifacts.
A reimbursement release includes verified submit, approve, and reimburse use cases. The submit-and-reimburse journey passes against the deployed API and database, and the record names the source commit and the image digest as the immutable artifact reference.