Type to search pages and rules.

Browse pages

Provision Scopes

Provisions are filed by concern: each page states the rules for one concern, while an agent changing one file needs every rule for that situation. This page states the shared situation vocabulary each provision carries: its stack, its layer, its artifact, its conformance level, and its strength. Authors write these values when they write or grade a provision, and the provision index carries them so the CLI lists the provisions that apply to one path and the part of the contract each provision belongs to.

Markdown7 rules

Stack: any Layer: workspace

Concepts#

The Five Fields#

Each provision carries five scope fields. The page declares the first two once; a provision narrows them or adds the third; the fourth names the conformance level the provision belongs to; the fifth grades how binding the provision is.

FieldAnswersValues
stackWhich technologydotnet, react, svelte, blazor, android, any
layerWhich part of the systemdomain, application, infrastructure, web-api, frontend-ui, frontend-data, tests, records, workspace, operations
artifactWhich kind of thing is madeany, one code kind, several code kinds separated by a comma, or record:<type> for one record of that type
conformanceWhich part of the contractrecords, traced, full
strengthHow binding it isrule, default, advice

Stack Values#

ValueMeaning
dotnetThe .NET backend stack
reactThe React web stack
svelteThe Svelte web stack
blazorThe Blazor stack
androidThe Android mobile stack
anyNo technology; the provision applies to every stack

Layer Values#

ValueMeaning
domainBusiness state, rules, and language
applicationUse-case coordination and the pipeline
infrastructureStorage, messaging, and outside calls
web-apiHTTP endpoints and their contracts
frontend-uiComponents, routes, and rendering
frontend-dataClient state, the cache, and generated clients
testsThe suites that prove behavior
recordsSpecification records and standards pages
workspaceRepository shape, packages, and configuration
operationsReleases, deployment, and support

Artifact Values#

ValueMeaning
aggregateThe aggregate root with the entities it guards
state-recordOne named state of an aggregate and its data
value-objectOne immutable type defined by its values
domain-eventOne fact completed inside the bounded context
use-caseThe message and result types of one use case
command-handlerThe execution path of one command use case
query-handlerThe execution path of one query use case
validatorThe input validation of one command or query use case
reactionThe handler class of one reaction
portOne declared port interface
repositoryOne aggregate repository, its interface or its store implementation
endpointOne route operation and the class serving it
migrationOne storage schema change
jobScheduled or manual background work in code
componentOne UI component
routeOne frontend address and its page file
formOne data-entry form
testOne test
anyEvery file of the provision layer
record:<type>One record of that type, such as record:use-case. The types are the Type column of the placement table on the model page

record:aggregate names the aggregate record while aggregate names its code, and record:job names the job record while job names its code. A provision names several code kinds separated by a comma when one rule governs several kinds, for example artifact: command-handler, query-handler; a file matches when its kind is one of the named kinds. The value any stands alone: it names no kind, and a file matches when its layer is the provision layer, so artifact: any states the layer-wide scope on a page where another provision names a kind. Each code kind names files the CLI classifies from the path, so a kind with no classifiable files earns no value here.

Conformance Values#

ValueMeaning
recordsThe record model: Intent, Behavior, governance, and glossary records, and the standards that govern them
tracedThe records part, and marks in code and tests, proof from test runs, and the model builder that computes statuses from them, in a code layout of the project's own
fullThe traced part, and the selected stacks, LiteSpec's code layout, the analyzers, and the operations provisions

The levels nest: traced includes every provision at records, and full includes every provision at traced. A project claims one conformance level, and litespec rules reads the conformance level of each provision from the provision index to show the provisions at or below the claimed level.

Page Conformance Level#

A page gives every provision on it one conformance level by default, from the folder the page sits in. The default table lives in the provision index builder and on this page, so the generated index and the standard state the same table.

Page folderConformance level
docs/core/records
docs/backend/, docs/frontend/, docs/workspace/, docs/quality/, and docs/ext/full

The stack folders sit under docs/backend/ and docs/frontend/, so a stack page takes full from its folder. No folder gives traced as a page default: a provision about marks, proof, or the model builder on a page that mixes levels, such as the model page, states its own level with a conformance field on its Applies to line. A provision states its own level only when that level differs from its page level.

Strength Values#

ValueMeaning
ruleFollow it; depart from it only through a recorded exception of kind departure whose covers names the provision, with a reason.
defaultFollow it unless the project chooses otherwise, and record the choice.
adviceExperience; apply it with judgement and record nothing.

Assigning Strength#

The first pass over the pages is mechanical: a provision with Checked by, or a rule on a checked boundary, takes rule; a convention or a pattern takes default; general knowledge and a provision whose Statement uses SHOULD take advice. Each area pass then settles its pages honestly: most provisions earn rule or default, and generic restatements earn advice.

A provision that restates an outside standard is replaced by a link to its source, and a provision that a stack page restates from a base page merges into the base one, so one rule has one home.

Where Scope Is Written#

Each page that owns provisions declares stack and layer once, in a **Stack:** line and a **Layer:** line directly under its title. The two lines are the Scope block. A page without provisions, such as a tutorial, a how-to, an explanation, a reference, a command, or an index page, carries no Scope block. Each line names one or more comma-separated values:

Markdown
# Domain Layer

**Stack:** dotnet
**Layer:** domain

A provision adds **Applies to:** only when it is narrower than its page, or when its conformance level differs from its page level, naming stack, layer, artifact, or conformance in that order, separated by ; , for example artifact: aggregate or artifact: aggregate; conformance: traced. An artifact field names one kind, several kinds separated by a comma, any, or one or more record:<type> values separated by a comma. Narrower means each named field holds a subset of the page values; artifact always narrows because the page names none. The value any holds the page layer scope in the field, so a provision that governs every file of its layer states artifact: any on a page where another provision names a kind, and carries no line on a page where no provision names a kind. A provision states conformance only when its level differs from its page level, and names exactly one level. Every provision carries its **Strength:** line directly after its ID line, before Applies to. The authoring standard states the full provision layout.

litespec-maintain provisions writes the scope, conformance level, and strength of every provision into the provision index and its data file, with the conformance level right after the artifact, and states the checked share of rules for each page in the index, so the CLI reads one file instead of parsing every page.

Scope Diagnostics#

These checks report scope defects that no single provision owns, so they are listed here instead of beside a provision.

CodeMeaning
SCOPE_ARTIFACTA provision names no artifact on a page where another provision names one.
SCOPE_BLOCKA page that owns provisions carries no Scope block, or the block names no stack or no layer.
SCOPE_VALUEA Scope block or an Applies to line names a value outside this page's tables, an Applies to line names a conformance value outside records, traced, and full or more than one level, or a provision carries no conformance level.
SCOPE_NARROWAn Applies to line is as wide as its page, widens it, repeats it, or states the conformance level of its page.
STRENGTH_LINEA provision carries no Strength line, or the line names a value outside rule, default, and advice.

Standards#

Declare the Page Scope#

rulerulecheckable
litespec/core/scopes#declare-the-page-scope
Statement

Each page that owns provisions MUST declare its stack and layer in a **Stack:** line and a **Layer:** line directly under its title.

Why

One block under the title tells every reader and tool which situation the page governs without reading further. A page without it leaves its provisions unfiled: retrieval cannot tell which change they govern, so it shows them everywhere or nowhere. Declaring both fields once keeps the page, not each provision, as the home of the common scope.

Checkchecked by a tool

Checked bylitespec-maintain validate emits no SCOPE_BLOCK diagnostic.

Marked checkable: the tool named here checks it.

Use Only Declared Scope Values#

rulerulecheckable
litespec/core/scopes#use-only-declared-scope-values
Statement

A Scope block and an Applies to line MUST use only the stack, layer, artifact, and conformance values this page lists.

Why

Retrieval matches situations to values: a value invented on one page matches nothing, so its provisions never surface for the change they govern. One closed vocabulary keeps every value comparable across pages. A new situation earns a value here first, then uses it on its page.

Example

A provision about the expense aggregate narrows with artifact: aggregate rather than inventing artifact: receipt. A provision about marks on a record-model page states conformance: traced rather than inventing a level name.

Checkchecked by a tool

Checked bylitespec-maintain validate emits no SCOPE_VALUE diagnostic.

Marked checkable: the tool named here checks it.

State Applies to Only When Narrower#

rulerulecheckable
litespec/core/scopes#state-applies-to-only-when-narrower
Statement

A provision MUST carry an Applies to line only when its scope is narrower than its page scope, its conformance level differs from its page level, or it marks its layer-wide scope with artifact: any on a page where another provision names a kind.

Why

The page scope already governs every provision on it: repeating it on each provision doubles the homes for one fact, and the copies disagree at the next edit. An Applies to line that widens the page scope misfiles the provision under situations the page never governed. One line, only when narrower, at a different level, or marking the layer-wide scope beside a named kind, keeps retrieval exact.

Example

On a page scoped to layer: domain, a provision for aggregates carries **Applies to:** artifact: aggregate, while a provision for the whole domain layer carries no line. On an application page where a provision names artifact: validator, a provision for the whole application layer carries **Applies to:** artifact: any. On a record-model page, a provision about marks carries **Applies to:** conformance: traced.

Checkchecked by a tool

Checked bylitespec-maintain validate emits no SCOPE_NARROW diagnostic.

Marked checkable: the tool named here checks it.

Name the Artifact of Every Provision on a Page That Names One#

rulerulecheckable
litespec/core/scopes#name-the-artifact-of-every-provision-on-a-page-that-names-one
Statement

On a page where one provision names an artifact, every provision MUST name the kinds of file it governs, or artifact: any when it governs every file of its layer.

Why

litespec rules matches a provision to a file by the kind of file it names. A provision that names none on a page of named kinds matches every file of the layer, so a handler receives the validator and port provisions beside its own and an agent reads provisions that do not govern the file in front of it.

Example

On the application page, the provision for validators names artifact: validator and the provision for the whole application layer names artifact: any, so litespec rules on a command handler returns the second and leaves out the first.

Checkchecked by a tool

Checked bylitespec-maintain validate emits no SCOPE_ARTIFACT diagnostic.

Marked checkable: the tool named here checks it.

Give Every Provision a Conformance Level#

rulerulecheckable
litespec/core/scopes#give-every-provision-a-conformance-level
Statement

Every provision MUST carry the conformance level of its page, or state its own level as a conformance field on its Applies to line when that level differs from its page level.

Why

A tool that reports only the part of the contract a project claims reads the level of each provision from the provision index: a provision with no level, or with a level copied from its page, gives the tool no exact part to report. The page folder gives the default, one override states the exception, and the index carries the result beside the artifact, so no reader composes the level by hand.

Example

A provision about expense records on a page under docs/core/ carries records from its page and states no field. A provision about test marks on the same page states **Applies to:** conformance: traced, and its index row carries traced.

Checkchecked by a tool

Checked bylitespec-maintain validate emits no SCOPE_VALUE diagnostic for a provision with no conformance level.

Marked checkable: the tool named here checks it.

Depart from a Rule Only Through a Recorded Exception#

ruleruleguidance
litespec/core/scopes#depart-from-a-rule-only-through-a-recorded-exception
Statement

A project that departs from a provision of Strength rule MUST record an exception of kind departure whose covers names the provision, with a reason.

Why

A rule binds every project it reaches: a silent departure claims conformance the project does not hold. The exception record names the provision, the reason, and the expiry date, so the departure stays visible, dated, and ends instead of lingering. The model page states how a live exception outranks its provision.

Example

Claimwick ships its weekend export without the review step, so it records an exception of kind departure whose covers names the authorization provision, with the reason and an expiry date.

Checka reviewer answers

Reviewed forEach departure from a provision of Strength rule resolves to an exception record under .litespec/governance/exceptions/ with the provision, a reason, and an expiry date.

Marked guidance: a reviewer answers this question.

Record Each Replaced Default#

ruleruleguidance
litespec/core/scopes#record-each-replaced-default
Statement

A project that chooses otherwise than a provision of Strength default MUST record its choice where the provision names.

Why

A default holds until the project says otherwise in writing: without the record, a reader cannot tell a deliberate choice from a provision nobody read. The provision names the recording place in its Replacement, so each choice sits where its provision points. Advice asks for no record, which is what sets the two strengths apart.

Example

A project that keeps its pattern catalog outside the default path records the path in paths.uiPatterns, as the provision's Replacement names.

Checka reviewer answers

Reviewed forEach choice against a provision of Strength default is recorded in the place its Replacement names.

Marked guidance: a reviewer answers this question.

Conventions#

None.

Reference Example#

This informative example demonstrates litespec/core/scopes#declare-the-page-scope, litespec/core/scopes#use-only-declared-scope-values, and litespec/core/scopes#state-applies-to-only-when-narrower.

A domain page for the .NET stack opens with its Scope block, and its aggregate provision narrows to the aggregate artifact:

Markdown
# Domain Layer

**Stack:** dotnet
**Layer:** domain

### Guard Each Aggregate Boundary

**ID:** `litespec/backend/domain#guard-each-aggregate-boundary`

**Strength:** rule

**Applies to:** artifact: aggregate

**Statement:** An aggregate MUST guard every change through its root.

**Rationale:** Changes that pass outside the root skip the checks the aggregate holds.

**Reviewed for:** Which aggregate changes pass outside the root? Look at the callers of each aggregate.