Authoring Standard

Non-ASCII characters break in terminals, diffs, generated context, and plain-text tools: a curly quote becomes unreadable in one reader and a silent mismatch in another. ASCII prose renders the same everywhere the standard is read or checked.

Write a hyphen or a comma where a typographic dash would go.

Checked bylitespec-maintain validate emits no PROSE_NON_ASCII diagnostic.

Marked checkable: the tool named here checks it.

A product whose subject is another language carries that language in its content files, where a diacritic is part of a word rather than a styling choice. Excluding only the declared content paths keeps the check strict everywhere else: documents about that content stay in scope, so styled prose filed beside content still meets the check.

Reviewed forWhich non-ASCII prose sits outside the paths the project record declares? Look at the content files beside the declaration.

Marked guidance: a reviewer answers this question.

Strength words work only when each one means exactly one thing. The provision contract defines the listed modals with their RFC meaning, so a reader knows whether a word obliges or suggests, and no second capitalized term sneaks in a different shade of obligation.

Checked bylitespec-maintain validate emits no STANDARD_MODAL_COUNT or STANDARD_MODAL_VOCABULARY diagnostic.

Marked checkable: the tool named here checks it.

Obligation hides when it sits in Concepts, Rationale, or an example: a project replaces a default it saw nowhere in the labeled assertions. One location for every modal lets readers and tools find each obligation in the same place. A prohibition written as cannot and a rule written as never belong in the same labels.

Checked bylitespec-maintain validate emits no PROSE_NORMATIVE_LOCATION or STANDARD_INFORMATIVE_NORMATIVE diagnostic.

Marked checkable: the tool named here checks it.

A second name for one concept reads as a second concept: the reader hunts for a distinction the writer did not mean. One term per concept means each term is defined once and checked once. Settled by decision/0018-one-record-language on the evidence in research/naming-grammar-evidence.

Reviewed forWhich concepts appear under more than one name? Look at the terms the change adds, beside the glossary.

Marked guidance: a reviewer answers this question.

A glossary column headed "Avoid" speaks to a reader and to nothing else: no tool can check it. A rule held as data reaches the reader and the validator alike, so the same rejection appears in prose guidance and in diagnostics.

A rejection carries the scope that binds it, because a word that is right in one module is wrong in another.

{ "id": "term/customer", "term": "customer", "meaning": "A person or company that buys.",
  "rejected": [{ "word": "client", "scope": "^domain/modules/orders/",
    "reason": "client names the API consumer" }] }

Checked bylitespec model check validates the project glossary against the glossary schema.

Marked checkable: the tool named here checks it.

Term drift is invisible one page at a time and plain across a module: each page looks fine while the project slowly speaks two languages. The expensive case is a synonym that is a defined term elsewhere, because one word then names two things and every reader guesses which one.

Reviewed forWhich words on the page are synonyms the project glossary rejects for the scope the page sits in?

Marked guidance: a reviewer answers this question.

A metaphor or stock phrase reads smoothly while hiding what the project means: each reader pictures a different act behind the same flourish. The glossary lists each mannered term with the literal phrase that carries its meaning, so the check points at the flourish and names the plain words to reach for.

The glossary lists { "term": "leverage", "instead": "use" }, so prose reads "use the retry queue" rather than "leverage the retry queue".

Reviewed forWhich mannered terms on the page stand where the glossary asks for the literal word?

Marked guidance: a reviewer answers this question.

A rejection matches a word, and a word can belong to more than one term: Claimwick rejects docket in favor of receipt for payment proof while a docket still names the shipping list. Without the except list, the check would force the project to rename an unrelated concept or drop a sound rejection.

The exemption covers the compound only, so the bare word stays rejected.

{ "word": "docket", "reason": "one word for a payment receipt and a shipping list",
  "scope": "^.litespec/domain/modules/spending/", "except": ["shipping docket"] }

Reviewed forWhich compounds use a rejected word to name another concept without being listed in the rejection's except?

Marked guidance: a reviewer answers this question.

A generated region holds tool output that no author wrote and no author can fix by editing the page. Checking it would fail pages for words outside author control and train writers to ignore diagnostics.

Reviewed forWhich findings point inside generated-region fences? Look at the findings the checks report.

Marked guidance: a reviewer answers this question.

Titles and headings read as names in indexes, tabs, and search results. Title Case capitalizes every word except articles (a, an, the), coordinating conjunctions (and, but, for, nor, or, so, yet), and prepositions of four letters or fewer (as, at, by, for, from, in, into, of, off, on, onto, over, per, to, up, upon, via, with); the first and last words stay capitalized, and code, identifiers, and file names keep their own case.

Checked bylitespec-maintain validate emits no PAGE_TITLE_CASE or PAGE_HEADING_CASE diagnostic.

Marked checkable: the tool named here checks it.

A fixed shape puts the authority, the context, the defaults, and the evidence in the same place on every page. Readers learn the shape once, and tools find each section without guessing. A page that invents its own order sends both searching. A record file carries its type's fields in canonical key order instead of sections.

Checked bylitespec-maintain validate emits no PAGE_MISSING_SECTION, PAGE_SECTION_ORDER or PAGE_UNKNOWN_SECTION diagnostic.

Marked checkable: the tool named here checks it.

The first sentence states the scope and boundary. The second states who applies the page and when. An optional third sentence relates the page to its neighbors.

Reviewed forWhich Intent sections run past three sentences? Look at the Intent section of each page the change touches.

Marked guidance: a reviewer answers this question.

One fixed marker reads the same on every page and gives the validator one shape to accept.

Checked bylitespec-maintain validate emits no PAGE_EMPTY_SECTION or PAGE_EMPTY_SECTION_TEXT diagnostic.

Marked checkable: the tool named here checks it.

A reader without a map from question to page opens both and trusts neither. Naming each style in the reader's terms before the first navigation group sends each question to the page that answers it.

A Which Page Do You Want section names each style in the reader's terms, one sentence each.

Checked bylitespec-maintain validate emits no INDEX_MISSING_ROUTING diagnostic.

Marked checkable: the tool named here checks it.

A procedure that lists what a command already does becomes a second copy of that command's behavior. The copy drifts from the tool, and readers follow stale steps. Naming the repository command delegates the steps to the tool that performs them.

A step reads Run `./shop up` rather than listing the compose start, the readiness wait, and each process launch.

Reviewed forWhich procedure steps lack a repository command? Look at the steps the change adds.

Marked guidance: a reviewer answers this question.

A reader who wanted the command reads mechanism detail as noise, and a reader who wanted the mechanism reads the command wrapper as an obstacle. One documentation layer per page serves each reader, and the Underneath section holds the mechanism for the reader who asks for it.

Reviewed forWhich command pages mix mechanism into other sections? Look outside the Underneath section of each command page the change touches.

Marked guidance: a reviewer answers this question.

A wrapper nobody can see through leaves a failure with no command to run by hand and no documentation layer to inspect. Stating what the command runs, or that nothing beneath it is separately runnable, gives every failure a next step.

A command with nothing separately runnable writes Nothing beneath this command is separately runnable. under Underneath.

Checked bylitespec-maintain validate emits no PAGE_MISSING_SECTION diagnostic for a command page.

Marked checkable: the tool named here checks it.

A setting introduced inside a procedure is found only by the reader who already knows which procedure mentioned it. A configuration page with the default, scope, and overrides puts every setting where a reader looks it up.

Reviewed forWhich procedure-named settings lack a configuration page row? Look at the settings the change adds, beside the configuration pages.

Marked guidance: a reviewer answers this question.

A copy drifts from its source with the next unrelated edit, and readers follow the stale one. One home for each fact keeps every reader on the current text. A link to a record names its identifier, not its file.

Reviewed forWhich passages restate content another page owns? Compare repeated passages with the owning page.

Marked guidance: a reviewer answers this question.

Technology lives in stack pages, so a principle holds for every stack. A framework name in a principle binds every stack to one choice.

Reviewed forWhich principle pages name stack detail? Look for framework, package, and language names in principle pages.

Marked guidance: a reviewer answers this question.

Shared pages stay neutral across stacks. Each stack page carries its own bindings, so a reader finds one stack's detail in one place.

Reviewed forWhich shared pages carry stack-specific sections? Look for stack sections outside stack pages.

Marked guidance: a reviewer answers this question.

Fixed labels separate package needs from related extensions and guides. A line with nothing to name holds None..

Reviewed forWhich Dependencies sections lack a labeled line? Look in each page under an ext/ folder.

Marked guidance: a reviewer answers this question.

The heading anchor already carries the term identifier, so a Term line repeats it. Lines after the definition name the record layer, established aliases, the source, and rejected synonyms where they exist.

Reviewed forWhich glossary entries open with something other than the definition, or carry a Term line? Look in docs/reference/glossary.md.

Marked guidance: a reviewer answers this question.

Groups in a fixed order with one opening sentence tell a reader where a term lives before any term is read. An unordered group hides its terms from a reader who guesses the wrong place, and a group without its sentence opens on terms with no shared context.

The code, product, and standard term groups open the glossary in that order, each with one sentence saying what its terms name.

Checked bylitespec-maintain validate emits no GLOSSARY_ORDER or GLOSSARY_DEFINITION diagnostic.

Marked checkable: the tool named here checks it.

One provision with one obligation has one authority, one identifier, and one verification line. A provision that bundles two obligations leaves a project half-compliant with no identifier for the half it missed.

### Keep Business Invariants in Domain owns one obligation about where invariants are enforced.

Checked bylitespec-maintain validate emits no STANDARD_LABEL_INVALID, STANDARD_LABEL_ORDER, STANDARD_LABEL_DUPLICATE, STANDARD_SENTENCE_COUNT, STANDARD_MODAL_COUNT, STANDARD_MODAL_VOCABULARY, STANDARD_MISSING_DEVIATION, STANDARD_UNEXPECTED_DEVIATION, STANDARD_DEVIATION_NORMATIVE, STANDARD_DEVIATION_SENTENCE, STANDARD_MISSING_REQUIREMENT, STANDARD_REQUIREMENT_COUNT, STANDARD_UNLABELED_CONTENT, or PROVISION_RESTATES_HEADING diagnostic.

Marked checkable: the tool named here checks it.

A Convention heading under ## Conventions makes each replaceable default traceable: a project cites exactly the default it replaces. Without the contract, defaults hide in prose and replacements cite paragraphs instead of identifiers.

Checked bylitespec-maintain validate emits no CONVENTION_MISSING_DEFAULT, CONVENTION_MISSING_REPLACEMENT, CONVENTION_DEFAULT_SENTENCE, CONVENTION_REPLACEMENT_SENTENCE, CONVENTION_REPLACEMENT_DEVIATION, or PROVISION_RESTATES_HEADING diagnostic.

Marked checkable: the tool named here checks it.

An example floating free of its provision reads as a second rule: readers obey the illustration instead of the obligation. Belonging to its provision, or to a Reference Example that names every provision it demonstrates, marks it as illustration.

Checked bylitespec-maintain validate emits no STANDARD_EXAMPLE_LABEL, PAGE_UNKNOWN_SECTION, or REFERENCE_EXAMPLE_DECLARATION diagnostic.

Marked checkable: the tool named here checks it.

The page names the file and the ID line states the slug, so a citation resolves with no lookup table. One grammar for every identifier keeps citations writable by hand and checkable by tool. The ID line is the identity: a heading reword leaves it unchanged, and no two provisions share one.

litespec/frontend/components#compose-composites-in-page-code is the ID line under its heading on the frontend components page.

Checked bylitespec-maintain validate emits no ID_UNKNOWN_REFERENCE or ID_DUPLICATE diagnostic.

Marked checkable: the tool named here checks it.

The page segment is the file a reader opens and the address the provision carries on the published site. Deriving it from the path keeps the identifier and the file from disagreeing.

litespec/frontend/structure#mirror-the-backend-use-case-path-in-kebab-case and litespec/frontend/mobile/structure#organize-screens-by-module are on two different pages.

Checked bylitespec-maintain validate emits no ID_PAGE_FILENAME or ID_DUPLICATE diagnostic.

Marked checkable: the tool named here checks it.

The page path and the heading already state the identifier. An identifier written into the heading repeats it at best and contradicts it at worst, after a rename touches one and misses the other.

Checked bylitespec-maintain validate emits no ID_IN_HEADING diagnostic.

Marked checkable: the tool named here checks it.

A counter orders a provision among its siblings and says nothing about what it requires. Words name the obligation; numbers would renumber every sibling on each insertion and break citations for no gain.

Reviewed forWhich identifiers carry a sequence number? Look at the provision IDs the change adds.

Marked guidance: a reviewer answers this question.

The type names the record kind and home.name names the owning module or set, so an identifier resolves with no lookup table. One grammar for every record kind keeps identifiers writable by hand and checkable by tool. The model page states the form each type uses, and the identifier page states the name rules and checks.

reaction/spending.send-receipt-reminder-on-expense-submitted is a reaction owned by the spending module, and journey/submit-and-reimburse#s2 is the second step of a journey.

Checked bylitespec model check fails a record identifier outside the declared grammar.

Marked checkable: the tool named here checks it.

A reader who cites a provision copies its ID from where the provision stands, instead of deriving a slug by hand or looking it up elsewhere. The ID line is the identity: a heading may change without changing it, so an ID line that reads differently from its heading still holds.

### Keep Shared UI in One Package on docs/frontend/components.md is followed by the ID line litespec/frontend/components#keep-shared-ui-in-one-package.

Checked bylitespec-maintain validate emits no ID_LINE_MISSING or ID_LINE_MISMATCH diagnostic.

Marked checkable: the tool named here checks it.

A provision with no verification line is a rule nobody checks: people assume a tool covers it while no tool was told. One line per provision, beside the rule it checks, makes each rule reviewable by a person or a tool.

Checked bylitespec-maintain validate emits no VERIFY_MISSING_ID, VERIFY_DUPLICATE_ID, VERIFY_ORDER, or VERIFY_HEADER diagnostic.

Marked checkable: the tool named here checks it.

The label tells a reader who judges the provision: a tool (checkable) or a person (guidance). Without it, a team automates a judgment call or hand-reviews what a command already proves.

Checked bylitespec-maintain validate reports VERIFY_MISSING_ID for a provision whose verification line opens with any other label.

Marked checkable: the tool named here checks it.

A line that restates its Statement sends the reviewer in a circle: the evidence confirms that the rule says what it says. Naming the artifact and its location turns the line into an instruction the reviewer follows.

Checked bylitespec-maintain validate emits no VERIFY_GENERIC_EVIDENCE, VERIFY_TEMPLATED_EVIDENCE, VERIFY_DUPLICATE_EVIDENCE, VERIFY_COMMAND, or CHECKED_BY_UNKNOWN diagnostic.

Marked checkable: the tool named here checks it.

A fact checked by a tool on one page and judged by a person on another leaves each reviewer unsure which judgment holds.

Reviewed forWhich shared facts carry different labels? Compare the verification lines that name one check, using the provision index.

Marked guidance: a reviewer answers this question.

One generated page resolves every identifier to its heading and page, so a reader follows a citation in one step. It carries each provision's scope and strength, so the CLI reads one file instead of parsing every page. Regenerating it with litespec-maintain provisions on every standards change keeps the index and the pages from disagreeing.

Checked bylitespec-maintain provisions --check exits zero.

Marked checkable: the tool named here checks it.

The record schema owns the field list of every record type and page style. A record file is one YAML mapping with its entries in records, holding no Markdown and no frontmatter fences. A document frontmatter block is YAML between two lines that hold only ---, holding only the page style and its common fields. The model page states the record types and their homes.

A use-case record file opens with its identity fields.

type: use-case
id: use-case/spending.submit-expense
title: Submit Expense

Checked bylitespec model check validates each record file and each document frontmatter block against the record schema.

Marked checkable: the tool named here checks it.

Two metadata carriers on one page disagree sooner or later: source links, paths, and evidence drift between the record file and the explanation file. One record file keeps every field a check reads in one place, while the explanation file beside it explains without stating a field value.

Reviewed forWhich pages carry field values outside the record file? Look at the explanation files beside the changed record files.

Marked guidance: a reviewer answers this question.

A file the validator leaves unclassified is skipped, and a skipped file looks sound: its errors stay hidden. Requiring every file to be a record file, an explanation, or a document, or to sit under a declared unstructured path, leaves no page unchecked. A directory index that owns no record uses the index style, and a README.md with no frontmatter is a document.

Checked bylitespec model check reports no explanation-orphaned finding, and fails a .yaml file with no record type outside a declared unstructured path.

Marked checkable: the tool named here checks it.

One shape puts the title and each section in the same place on every explanation. The H1 carries the record title, and each H2 carries one section from the table on this page or a free section; Notes take free ### headings under their H2.

Reviewed forWhich explanation files miss their H1 title or section content outside H2? Look at the explanation files beside the changed record files.

Marked guidance: a reviewer answers this question.

A restated number is right until the next unrelated edit changes the records it counts, and nothing reports when it goes stale. Naming the source or the command gives every reader the current figure instead of the figure from commit day. Derivation between records is allowed: generic refusals derive from access and input, and computed completion appears in the book and the model output only.

A chapter states where its numbers come from rather than copying them.

The figures below render from the retention schedule at build time.

Reviewed forWhich counts, censuses, or membership lists lack a source or command? Look at the numbers the change adds.

Marked guidance: a reviewer answers this question.

Code implements Behavior, so a field filled from an implementation restates what already ships instead of stating the promise under review. A fact learned from the world enters Intent as research or a constraint, cited and dated, and a need the upper record layer does not state becomes a backlog item outside the repository. Derivation between records stays allowed.

A positivity guard found in a handler becomes a backlog item for a rule, while the code stays untouched until the rule lands.

Reviewed forWhich Intent or Behavior fields copy values from code? Look at the fields the change fills, beside the implementation.

Marked guidance: a reviewer answers this question.

Two agents working in parallel mint the same identifier when each writes a file by hand, and the collision surfaces only at merge time. Scaffolding reserves the identifier before any prose exists, so the second author learns the clash at creation and picks another name. For an article type the command also writes the explanation file, and for a document style it writes the document.

litespec new reaction spending.send-receipt-reminder-on-expense-submitted creates the reaction record file with its reserved identifier.

Reviewed forWhich new pages lack a reserved identifier? Look for pages created without litespec new.

Marked guidance: a reviewer answers this question.

An identifier rename touches the record file, its explanation file, and every record that points at it. Rewriting every link in the same command leaves no citation pointing at the old name, so the repository stays resolvable at every commit. When the file name follows the identifier, both files move together.

litespec rename use-case/spending.close-run use-case/spending.complete-run updates the page and every citation together.

Checked bylitespec rename leaves no citation of the old identifier, and litespec-maintain validate emits no ID_UNKNOWN_REFERENCE diagnostic.

Marked checkable: the tool named here checks it.

Full validation walks the whole repository, which grows slow exactly when many authors commit often. A single-page check reports shape and link errors for the page at hand in seconds, so each commit arrives already sound.

The author validates the touched page, fixes the reported diagnostics, and commits only when the page passes.

Reviewed forThe change report shows each touched page passing single-page validation before commit.

Marked guidance: a reviewer answers this question.

The repository validator, the test suite, and git diff --check each catch what the others miss: structure, behavior, and whitespace. Passing all three on every standards change keeps the standard checkable by anyone who runs the same commands. The change report lists every skipped check with its reason. The command index and the maintainer index name each check and its command.

Checked bylitespec-maintain validate, dotnet test --solution LiteSpec.slnx and git diff --check exit zero.

Marked checkable: the tool named here checks it.

Each pinned release is a complete snapshot, so the validator judges the working tree alone. Reading history would let a provision pass on the strength of a release nobody pinned. Git history and the changelog give release context to readers outside validation.

Reviewed forWhich validator inputs come from outside the working tree? Look at the paths the validator reads.

Marked guidance: a reviewer answers this question.

A snapshot that carries aliases, maps, migration notes, or transition checks for other releases forces every reader to learn releases they did not pin. The published snapshot states its own contract and nothing else. An extension's Baseline Relationship section names a provision it replaces inside this release, which is a current replacement rather than history. The changelog's generated list of added, removed and renamed provision identifiers states a fact about the release it ships in; it offers no alias, mapping or migration path, so it stands as the one exception this provision allows.

Reviewed forWhich active files carry history-specific paths, aliases, or migration material? Look at the files the change adds.

Marked guidance: a reviewer answers this question.

A consumer pins one snapshot and reads it as the whole obligation. Depending on another release would force the consumer to pin and read two contracts to know either. Stating every active provision in each release keeps one snapshot sufficient.

Checked bylitespec-maintain validate checks every page of the release in one run, and the manifest names one version for the whole contract.

Marked checkable: the tool named here checks it.

LiteSpec is a pinned contract, not a running service: consumers adopt a release whole, on their own schedule. Compatibility guarantees, migration paths, deprecation periods, and identifier aliases between LiteSpec releases would promise a continuity the model does not offer. A consumer product keeps its own API compatibility, migration, deprecation, and rollback provisions for its own users.

Reviewed forWhich pages promise migration, mapping, or alias between releases? Look at the release material the change adds.

Marked guidance: a reviewer answers this question.

A consumer cites provision identifiers in code marks, records, and exceptions, so a release that removes or renames an identifier without naming it leaves every citation pointing at nothing with no way to find what changed. The generated list states a fact about the release it ships in and nothing more: it carries no alias, no replacement map, and no migration path, and no provision depends on an earlier release to state its own contract. Because the list derives from the two provision indexes, a tool generates it; a list typed by hand goes stale with the next provision edit. This provision is the exception to litespec/core/authoring#exclude-historical-transition-material, and it extends to no other history material.

litespec-maintain changelog --from v3.0.0 writes the list into the changelog entry for a release, with litespec/core/scope#declare-the-conformance-level under Added when that provision first ships, and a major release lists each identifier it removes or renames under Removed and Renamed in the same entry.

Reviewed forWhich changelog identifiers were typed by hand, or name an identifier that a comparison of the provision index at the previous tag with the provision index of the release does not produce? Look at the changelog entry beside the two provision indexes.

Marked guidance: a reviewer answers this question.

Adoption is the consumer's decision. If a repository change could oblige a move, every LiteSpec edit would become a deadline for every consumer. Keeping any published release for as long as it serves decouples the consumer's schedule from the standard's.

Reviewed forWhich provisions oblige a move to a later release? Look at the Statements the change adds.

Marked guidance: a reviewer answers this question.

A provision can gain force while keeping its ID, so an exception of kind departure written against one release could otherwise apply to a rule nobody reread. Recording the adopted release in reviewedLiteSpecVersion makes adoption an explicit act and tells every reader which contract the project reviewed.

Checked bylitespec model check fails when reviewedLiteSpecVersion differs from the pinned release.

Marked checkable: the tool named here checks it.

Two spellings of one concept split every search and every listing, and a reader cannot tell whether they name one concept or two. One spelling per concept keeps each term defined once and checked once. A hyphenated pair whose first part is a function word is two words side by side, not one compound split in two, so the check skips it: a, an, as, at, by, in, of, on, or, to, and with.

The notification send-receiptreminder-confirmation and the reaction send-receipt-reminder-on-expense-submitted name one concept with two spellings; the project picks one and renames the other. send-on-line-notice beside send-online-notice is not reported, since on opens no compound.

Reviewed forWhich terms differ from another term only in hyphenation, spelling, plurality, or a compound split? Look at the terms the change adds, beside the glossary.

Marked guidance: a reviewer answers this question.

The vague words are handle, handles, handled, process, processes, manage, manages, various, etc., appropriate, appropriately, properly, as needed, and so on: each says that something happens without saying what. A reader cannot check a statement that hides its behavior, so each statement names the act in words a test could assert.

A scenario step reads "The member borrows the copy" rather than "The member handles the copy".

Reviewed forWhich rule statements, scenario steps, or result meanings hide their behavior behind a vague word? Look at the statements the change adds.

Marked guidance: a reviewer answers this question.