Principles

A record layer written from the record layer above inherits decided promises instead of inventing its own: Behavior fulfills Intent, Implementation builds Behavior, and Proof checks Implementation. A record layer written from below restates guesses as rules, and the next upper record-layer change leaves two versions of one promise.

A use case names the requirement it fulfills before its handler exists.

Checked bylitespec model check reports no record-link-missing finding on the changed records.

Marked checkable: the tool named here checks it.

A name is a claim about what happens. The right name comes from asking what the act really does, including how it can end, and the record that states the act decides it; the use case, the aggregate method, the event, the permission, the route and the screen label then repeat it. A check that reports two names for one act reports drift, not the answer: the fix brings every layer to the name the intent states, and the intent changes first when its own word is wrong. A rename made only to quiet a check, or a name kept in one layer while the others move, leaves one act with two names.

In the Claimwick product, finance staff send an approved expense's payout to the bank, and the bank can refuse it when the company account cannot cover it. The act is a submission, not a payment: the use case is submit-payout, the method SubmitPayout, the event PayoutSubmitted, the permission submit-payout, and the screen's button reads "Submit payout". A later command records whether the bank paid or refused.

Reviewed forWhich act carries a different name in its use case, method, event, permission, route or screen label than the record above it states? Compare the names of one act across its record, its handler, its endpoint and its screen.

Marked guidance: a reviewer answers this question.

A record computed from code turns what exists into what is promised, so drift becomes the plan and the record restates what the code already does. Records above Implementation state decided promises, and code points up to the record it serves through a mark naming that record.

Reviewed forWhich records above Implementation restate code instead of a decided promise? Compare each new record with the code beside it.

Marked guidance: a reviewer answers this question.

Derivation between records keeps one authored source behind every value: the source changes once and each derived view follows. Generic refusals derive from access and input, and each view derives from the records it lists, so readers trace every derived value to the record that states it.

Reviewed forWhich derived values lack an authored source record? Trace each derived value to the record it cites.

Marked guidance: a reviewer answers this question.

A provider behavior, a regulation, or an incident is evidence from outside the project, and entering it as research or a constraint keeps the citation and the date beside the fact. A fact typed straight into Behavior or code loses its source, and later readers treat an observation as a decision.

An agent records a slower payout settlement as research, then writes the constraint that cites it.

Reviewed forWhich outside facts lack a cited and dated source? Look at the research and constraint records beside the change.

Marked guidance: a reviewer answers this question.

A need that goes to the owner reaches the person who decides it, and a need placed on the backlog board stays visible outside the repository. A need filled in quietly at the lower record layer becomes an undecided promise that later readers trust.

A use case that needs a price its requirements do not state raises an owner question naming the missing price.

Reviewed forWhich needs from a lower record layer lack an owner question or a backlog item? Look at the owner questions and the backlog board beside the records that need them.

Marked guidance: a reviewer answers this question.

Intent holds the decided promises, so Behavior that fulfills them and code that builds them keep one chain from promise to product. Where Intent states the promise, code that disagrees is the defect, and the fix changes the code.

Reviewed forWhich code disagrees with a stated promise? Compare the changed code with the Intent records it serves.

Marked guidance: a reviewer answers this question.

Silent Intent plus working code means a decision nobody recorded: deleting the code destroys behavior users rely on, and copying it quietly into Intent turns code into a promise nobody stated. A question carries the behavior to the owner with the code as evidence, and the answer lands in Intent first.

A positivity guard in code that no rule states becomes an owner question citing the guard, and the code stays until the answer lands in Intent.

Reviewed forWhich working code outside Intent lacks an owner question carrying it? Look at the owner questions beside the uncovered code.

Marked guidance: a reviewer answers this question.

An edge declared on its record is checked: the builder verifies its target, its timing, and its failure handling. An undeclared edge is the defect, because it runs behavior no record names and no review saw.

A use case that reminds a manager declares a sends edge to the notification with its timing and failure handling.

Reviewed forWhich edges lack a declaration on their record? Look at the effects entries with runs, sends, emits, or calls beside the changed records.

Marked guidance: a reviewer answers this question.

A cycle without an end condition runs until something outside the records stops it, so no reader can state when the work finishes. Routing each cycle through a domain event with a stated end condition names the loop and its exit in the records the graph checks.

Checked bylitespec model check reports no effect-loop-invalid finding on the changed records.

Marked checkable: the tool named here checks it.

Two inline edges that look alike run in one transaction or two, and the difference decides what a failure leaves behind. Stating the sharing on the edge keeps transaction honesty where the edge is declared.

An inline runs edge states sharesTransaction: true, so a failure in the use case it runs rolls back the caller.

Checked bylitespec model check reports no record-invalid finding on the changed inline edges.

Marked checkable: the tool named here checks it.

An async edge crosses a commit boundary, so work past it can fail after the caller succeeded. Atomic consistency promises one shared outcome, which holds only while every edge stays synchronous.

Reviewed forWhich atomic use cases span an async edge? Look at the consistency and effects fields beside the changed use cases.

Marked guidance: a reviewer answers this question.

The engine carries the saga while the records state it: one use case per step keeps the promise, the refusal codes, and the undo in the records the checks read. An engine step without its use case runs behavior no record names, and a step without its compensation leaves a failure with no stated undo.

An engine step that reimburses an expense maps to the reimburse-expense use case, whose compensation voids the payout.

Checked bylitespec model check reports no behavior-unrecorded finding on engine steps without a use case.

Marked checkable: the tool named here checks it.

LiteSpec checks declared edges and leaves stricter taste to each project. A stricter rule recorded as a cited convention stays visible and checkable beside the records it constrains, instead of living as habit in a few heads.

Reviewed forWhich stricter edge rules lack a cited convention? Look at the project conventions beside the changed records.

Marked guidance: a reviewer answers this question.

LiteSpec favors one set of mechanisms and states that choice openly instead of claiming neutrality. An extension states how its mechanism composes with the core fields, so a project that needs it selects one place that holds the whole contract.

Reviewed forWhich mechanisms outside the favored set lack an extension? Look at the selected extensions beside the changed records.

Marked guidance: a reviewer answers this question.

Two homes for one fact become two facts with the next edit: each copy changes on its own schedule while readers guess which one rules. Deriving every other appearance from the model keeps the authored record as the single place a change lands. Completion computed from the model stays true without anyone typing it by hand.

Reviewed forEach fact on the changed pages traces to one authored record, with every other appearance derived from the model.

Marked guidance: a reviewer answers this question.

The manifest is the version authority for the stack the standards select, so every consumer resolves the same tested combination. A version pinned in prose or remembered by an agent drifts from that authority with the next manifest change. Consumer dependencies still live in package manifests and lockfiles; only the standards-selected stack versions resolve from litespec.manifest.json.

Checked bylitespec model check fails a project whose stack versions do not resolve from the manifest.

Marked checkable: the tool named here checks it.

A passing test that skips the use case proves nothing about the behavior it claims. Calling the use case and asserting its result ties the proof to the shipped path. A scenario without such a test carries a gap exception with an expiry date, not silent coverage. The model page defines the proves link.

Reviewed forEach scenario in the model links a passing test that calls its use case and asserts its result.

Marked guidance: a reviewer answers this question.

A record in git is the decision, and the pull request that changes it is its review. A record nobody wants is deleted, and git keeps who changed what and when. Records carry no history of their own.

A feature nobody wants is deleted from the repository; its history stays in git.

Reviewed forWhich changed records bypass their pull request? Look at the pull request behind the change.

Marked guidance: a reviewer answers this question.

The specification is closed: something that seems missing becomes a question to the owner or a backlog item, never code. Code without a record behind it is a promise nobody stated.

An agent that finds no payout rule asks the owner instead of coding a guessed guard.

Reviewed forWhich code has no specification record behind it? Compare the changed code with the records it serves.

Marked guidance: a reviewer answers this question.

Goals, problems, features, research, and constraints all qualify when they translate into code, results, tests, or infrastructure. Running the company stays out; it enters only as a constraint or as dated research.

A goal that translates into payout code and tests qualifies; a sales target does not.

Reviewed forWhich records state company business instead of the software? Compare each new record with the code, results, tests, or infrastructure it translates into.

Marked guidance: a reviewer answers this question.

What a reader asks first is how much of a thing exists and is proven. Completion typed by hand turns the plan into a completion report that the next commit falsifies. The model page defines what the model computes.

The book shows a use case complete when its handler exists and its scenarios pass, with the model deriving that from the runs.

Reviewed forWhich records state their own completion? Compare the record fields with the completion the model computes.

Marked guidance: a reviewer answers this question.

Strength words work only when each one means exactly one thing: an agent tells binding from advisory without a check existing. A check is an aid where one is cheap and sure, never the condition for a provision to exist.

Reviewed forWhich provisions leave their strength or scope unstated? Look at the provisions the change adds.

Marked guidance: a reviewer answers this question.

Each command, check, generated file, or package adds maintenance, failure modes, and concepts every later reader learns. A tool nothing uses is removed instead of kept beside its replacement.

A check nobody runs is removed with its command.

Reviewed forWhich commands, checks, generated files, or packages lack an owner approval or a user? Look at the tooling the change adds beside its users.

Marked guidance: a reviewer answers this question.

A branch may be incomplete; what merges is complete. A record that must stay unreached past a merge carries an exception with expiresOn, which parks reachability for that record until it expires.

A use case with no endpoint stays on its branch until the endpoint lands or an exception with expiresOn parks it.

Checked bylitespec model check reports unreached records locally and blocks on them in the pull-request check.

Marked checkable: the tool named here checks it.

A boundary stated only in prose holds until the first commit that ignores it. Mechanical proof, such as a reference, a visibility rule, an architecture test, a behavior test, or a lint rule, fails the build or the check the day the boundary breaks. Specifications then explain the decisions that need judgment, while tools guard the constraints that do not. Enforceable boundaries include project and package references, compiler visibility, permission guards, store constraints, and lint rules.

A project-reference test proves Domain has no Infrastructure reference.

Reviewed forEach changed enforceable boundary names a reference, test, or lint rule that proves it.

Marked guidance: a reviewer answers this question.

Each package, project, wrapper, background process, cache, queue, or distributed pattern adds maintenance, failure modes, and concepts every later reader must learn. A current use case, decision, or requirement names the activation criterion that justifies that cost. Preference and possible future need justify nothing, so speculative machinery stays out.

Reviewed forEach added package, project, wrapper, process, cache, queue, or pattern cites a current use case, decision, or requirement.

Marked guidance: a reviewer answers this question.

Boundaries are where components meet and where future readers orient themselves. Business operation names, specific command and query mediators, and business-action external ports state the purpose at that meeting point. A precise name lets a newcomer place the interaction without opening either side.

Reviewed forEach changed boundary name states its business action.

Marked guidance: a reviewer answers this question.

Names such as bus, manager, helper, processor, and service say nothing about the business action, so unrelated responsibility collects behind them with every change. The narrower name keeps each boundary to the action it names.

A notifier named for post publication names its action; one named only service does not.

Reviewed forEach changed boundary name carries the narrowest accurate business name, with no bare bus, manager, helper, processor, or service.

Marked guidance: a reviewer answers this question.