Repository navigation
LiteSpec 3.0.0
LiteSpec 3.0.0 is a top-down specification standard for one bounded-context business application, written by agents and judged by machines, so people review only what is theirs to decide. A consumer installs this release as the LiteSpec.Cli local .NET tool at the release version and records it in reviewedLiteSpecVersion. The release takes effect as the v3.0.0 tag.
Layers
- Four layers: Intent (why and what we promise; product people review it), Behavior (how the system behaves; developers review it), Implementation (code) and Proof (tests, checks, computed statuses and the book).
- Each layer is written from the one above. Nothing above Implementation is computed from code; code and tests point up. Facts from the world enter Intent as research or constraints, and what a lower layer needs travels up as a question with a decider.
- The translation rules Specify, Implement and Verify state what each boundary receives, must add, may not decide, and checks.
- Consumer docs sit in one folder per layer:
docs/intent,docs/behavior,docs/implementation,docs/proofanddocs/governance.
Records
- Each record page is a YAML record file holding one mapping with its entries in
records; an optional explanation file beside it holds Markdown under H2 sections. - A module page is
module.yamlin its module folder and an aggregate page isaggregate.yamlin its aggregate folder; the glossary isdocs/glossary.yaml. - Anything a check reads or a reviewer approves is a record field; the explanation file only helps a reader understand. Product, constraint, rule set, actor, role and external system hold
summary; goal holdswhyItMatters; problem holdssituation; feature holdsoffering; decision holdsconsequences; topic holdssummary,positionandrefusals; journey holdsbetweenSteps. - Use cases hold
purpose,whatHappensandexposure; reactions, jobs, notifications and setting sets holdpurposeandwhatHappens; screens holdsummary; integration events holdsummaryanddelivery; runbooks holdimpact,prerequisites,procedure,verification,recoveryandescalation; exceptions holdexitandconsequences; research sources carry akey. - Prose cites a record by its identifier, such as
[the refund rule](rule/refund.within-window); research cites a source as[text][key]. - A Markdown page that holds no record is a document with an optional frontmatter block holding only its page style and common fields.
- Journeys are product sentences with step ids,
finishedWhenand a per-stepfailure; use cases point up withserves. - Requirements state exceptions with
exceptand afallback, and carryriskandsetBy. - Use cases are commands or queries with
access(grantandtenant;authsits on the entry point),changes,reads,consistency,effects(runs,sends,emits,calls),idempotency,audit, typed query output inincludegroups, freshness and paging. Generic refusals are derived. - Record types include reaction, job, notification, setting and integration event. Aggregates have
entity,sagaandstorekinds, and data classes with erasure positions. A retention schedule page holds retention rows. - Reactions and jobs declare edges in
effectswith the same verb grammar as use cases; a reaction may omittiming, which reads asasync, and a top-level verb besideeffectsis refused. - An idempotency
keytemplates{field}placeholders over the record'sinputfields, andscopeistenant,account,loginorglobal; reaction and job placeholders name triggering event or run window fields and are not checked. - Reaction and job
onFailureis a structured policy:modeisretry,skip-and-logordiscard; aretrypolicy holdsmaxAttempts,initialDelay,maxDelayandbackoff;thenisdead-letter, withdeadLetter,surfacesInandrunbook, with ISO 8601 durations. - Approval is data:
approvedBy,approvedOnand a semanticapprovedHash, written bylitespec model approve.
Review and checks
- Product people read journey chapters and ballots; developers review Behavior diffs; a named security reviewer sees tier 1 access and data changes. Tier 3 questions auto-approve after a veto window.
- Every check has a level: G (record graph, blocking), S (stack reader, blocking where qualified) and A (advisory).
- Every edge between use cases, reactions, jobs, notifications, integration events and external systems is declared and checked. A calls edge counts only through a port anchored to an external-system record.
- A refusal proof confirms from the asserted code, a client code
refusals.aliasestranslates, or the HTTP statusrefusals.statusesmaps to the code. - An integration fact that drives a use case or rule confirms its scenario or rule claim from inside the host.
- An
effect-undeclaredfinding names a one-hop helper asvia 'Type.Method'. - A term's
labelssit outside the approval hash, so adding a language reopens no approval. - A project declares its use-case verb vocabulary in
vocabulary:verbs,phrasalverbs counted as one, andretiredsynonyms with their replacement, checked byuse-case-verb-unknown. effect-timing-invalid(level S) reports a command whosesendsorcallseffect runs inline; consequences run from an event handler or a job after the commit.event-tense-invalidaccepts a past tense followed by a prepositional complement and a mark method naming its state, andterm-clashskips a hyphenated pair opening with a function word.state-unreached(level G) reports every state no transition enters. An aggregate writes its creation as a transition from-in itstransitionsfield, so its first state is reached too.- The approval hash covers every written record field except the identity, workflow and approval fields the guide lists, and compares numbers by value, so
50.00and50hash alike. For research, decision and topic pages it also covers the explanation file. prose-missingreports a significant use case with nopurposefield and a significant command with nowhatHappensfield.explanation-orphaned,explanation-missing,format-drift,source-link-bare,source-key-unknownandsource-unused(level A) report an orphaned explanation, a missing article explanation, a record outside canonical form, and a research source linked directly, cited by an unknown key, or never cited.record-invalidreports a record file that does not parse, with the parser message and line.reader-missing(level S) also reports a .NET file that cannot be read or parsed, a declared stack root that resolves to no folder, aserverproject with no backend reader, and a configured bill of materials that cannot be read, is not SPDX or CycloneDX, or yields no packages.- A test proves a scenario across machines: the proof ledger hashes each test file by its path relative to the project root and its text with normalized line endings.
Application Layer
- A command handler loads or creates one aggregate, calls one domain method, stages it and returns; validation, authorization, idempotency, audit, the timestamp, holds, the commit and fault classification are pipeline stages, and a change to another aggregate is a consequence. A record declaring
consistency: atomicis the one exception. - Each command implements one use case with one success path; a find-or-create flow is two use cases the owning boundary chooses between, and a lost race ends with the use case's conflict refusal at commit.
- Uniqueness is enforced by the store: a unique index, an identity derived from the owner, aggregate state for a once-only rule, or a key the aggregate declares and persistence claims at commit. Each constraint maps by name to its conflict refusal, and no handler reserves or checks a key.
- A refusal code built at run time from a key, such as the conflict for a lost uniqueness key, declares its template in the project file
refusals.composed, andrefusal-unimplementedreads the code as raised where its key is a literal in the code. - Every aggregate carries a version the store compares at commit.
- A message whose target must be the caller carries no target or declares a self grant the guard enforces.
- Audit targets and reasons the message carries are declared beside it; the handler adds only values it learns while running.
- Messages, provider calls and changes to other aggregates run in event handlers after the commit; the outbox delivers each event to each handler separately.
- Query handlers take no repository and never write. Work over many records is a job issuing one command per record, each in its own unit of work.
- Result parts are named
{UseCase}QueryResult{Part}or{UseCase}CommandResult{Part}, event handlers are{Action}On{Fact}Handlerin anOn{Fact}folder of the subscriber's aggregate, and repository variables are named after their interface.
Mobile
- An
androidstack builds a native Android app with .NET for Android and plain Android views: no MAUI, no WebView screens. It sits atdocs/frontend/mobile/android/under shared mobile pages for structure, screens and navigation, data and state, device capabilities, and testing, so a later mobile stack reuses them. - The mobile solution lives at
apps/mobile/with platform-free core projects beside one app project per platform; aclient-onlyapp holds Domain, Application and Infrastructure, aserverapp holds the generated API client. - The
android-clientpreset starts a client-only Android consumer, and the manifest pins the Android API level instack.android.
Tools
litespec model diffhas--intentand--behaviorviews with a security queue, andlitespec bookrenders journey chapters and a ballots page.litespec newscaffolds a record file with its explanation file for an article type,litespec renamerewrites an id in record files, explanation files and documents, andlitespec model approverecords approval in the record file.litespec new resultandlitespec new scenarioappend one entry to a use-case record file in house order: successes, refusals, then scenarios.litespec model formatrewrites every record file and the glossary file into canonical form;--checkwrites nothing, lists each file that would change, and exits 1 when any would. It exits 2 when a file does not parse.litespec appendadds an entry to a record file;litespec initwritesdocs/glossary.yaml.- Consumer templates ship as
<type>.yamlrecord files, with<type>.mdexplanation files for article types and<type>.mddocuments for document styles. litespec model check --stagedreports only staged records, their direct links, and the records staged code implements.litespec model approve --dry-runprints which records would be stamped and which would be reopened, without writing.- The
litespec-maintaintool checks the standard's own pages, schemas, manifest, and provision index fromapps/maintain/withvalidateandprovisions; thelitespectool serves consumers only. - Extensions added: privacy, devices, automation, workflow-engine, pipeline, queues and ai. LS2002 is retired.
litespec model checkprints each finding once, the blocking ones first, then a count per finding code and level, and ends with the number of findings, blocking findings and known findings.--levellimits the findings and counts to the named levels, such as--level G,S.litespec model check --sinceand--stagedleave out files under.model/, which the tool writes itself.litespec model approve --all --dry-runlists exactly the recordslitespec model approve --allstamps.- Every command reports an unexpected failure as one line and exit code 1; with
--format jsonthe line is a JSON object with anerrorfield. A repeated option, an empty value, and an unknown option given with--helpare usage errors. - The book links only
http,https,mailto, in-page fragments, relative paths, record identifiers and the configured editor scheme, and renders any other link target as text.litespec bookexits with code 2 when the carried release is missing. - A project that opts out of the analyzers with
LiteSpecLayer=Nonegets no diagnostics and no generated code from the analyzer package. - The navigation and page-frame patterns draw their wireframes on the Claimwick cast. Their option ids follow the option names:
cost-centre-sections-as-tabs-on-the-cost-centre-page,no-switcher-back-to-the-cost-centre-list,the-count-the-cost-centres-the-exceptions,per-cost-centre-cards-with-a-rate,payouts-as-a-timeline,split-payouts-left-incidents-right,month-grid-with-trips-marked,week-lanes-per-cost-centreandreceipt-scanner-is-offline. - Provisions cover file uploads and the
429status on the API, and offline commands, saved navigation state, app links and touch and text accessibility on Android. The shared frontend data rules live on the frontend data page for every stack, and thejobsextension runs scheduled jobs in a Worker. FsCheck is pinned for property-based Domain tests. - Record files use a strict YAML subset in canonical key order with two-space indentation;
litespec model formatowns the layout. - The YAML block at the top of a document is called frontmatter throughout the standard.
Record Hierarchy
- Every record has exactly one parent: by identifier containment, by one required written up-link, or, for a type with no record above it, its layer list under the product. A record whose required parent is missing is an error at level G, reported even when the record is a draft. Every inverse link is computed, never written.
- A feature names at least one problem in
solves; its parent is the first entry. Every non-refused feature names at least one goal inadvances. A refused feature namesrefusedBecauseand the problem it declines insolves, and carries noadvances. - Every journey names its goal record in a required single link
serves, which is its parent. A use case, reaction, job or screen serves journey steps; a journey serves one goal, and a use case never serves a goal directly. - Every requirement names its parent: a carrying feature, a constraint or research in
basedOn, or a decision naming it indecides, in that precedence. - Written result and scenario identifiers use the
result/<use-case>.<name>andscenario/<use-case>.<name>form, and derived generic results take the same form. A written result no scenario shows is reported: level G for a success result, level A for a refusal, on large projects. - Structural parents are level G for all records; other required links are level A for tier 3 records and level G for tier 1 records.
- Field names follow one grammar: a classifier is
kind; a link is a present-tense verb, plural when it holds a list; a deadline is<verb>By, a recorded date<verb>On; a reason isreasonor<verb>Because. Featurelifecycle, goal and requirementdueBy, featureplannedFor, decisionapprovedOn, and constraintauthorityandkindfollow it, checked bylitespec-maintain validate. Glossary terms carrylayerandaliases. - Use cases list the settings they read in
reads; a setting's readers are computed, never written. The Links table carries a "reads as" phrase in both directions for every link, and the book takes its connection labels from it. A follows edge marks export beside implements in the built model. - Research states its
conclusion, and LiteSpec keeps its own research and decision records underdocs/intent/. litespec bookis one offline shell with sharded data, generated from the model, with the outline from the parent table and the labels from the Links table and the glossary.- Approval batches a journey with the goal it serves, keeps each entry a page stamp did not hold at the page's former status, refuses a decision naming no chosen option, and keeps a transcribed record serving a draft journey in draft. Screens are Behavior, and reaction and job scenarios carry their own stamp.