Authoring Standard

Requirement Authored prose MUST follow the Google developer documentation style guide, except where this page states a different rule.

Rationale One established guide gives every writer, person or agent, the same answers on voice, word choice, and formatting. It reads as ordinary technical writing, and nobody maintains a second guide.

Requirement Authored prose MUST contain only ASCII unless code, data, or mathematical content requires another character.

Rationale ASCII prose stays stable in terminals, diffs, generated context, and plain-text tools.

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

Requirement An ASCII check MUST exclude only the natural-language content paths that the project record declares.

Rationale A product whose subject is another language carries that language in its content files, where a diacritic is part of a word. Every document about that content stays in scope.

Requirement A Standards provision MUST use exactly one approved capitalized modal and no other capitalized normative term.

Rationale The provision contract defines the approved modals and their RFC meaning, so a reader never has to interpret strength.

Requirement Authored prose MUST name each concept with its one glossary term.

Rationale A second name for the same concept makes a reader wonder whether it is a second concept. A term defined once is checked once.

Requirement A consumer MUST record each term, its rejected synonyms, the scope of each rejection, and its mannered terms in a language record satisfying schemas/language.schema.json.

Rationale A glossary column headed "Avoid" states the rule to a reader and to nothing else. A rule held as data reaches the reader and the validator alike.

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

{ "term": "customer", "rejected": ["client"], "scope": "^domain/modules/orders/",
  "reason": "client names the API consumer" }

Requirement Authored prose MUST NOT use a synonym that the project language record rejects for the scope the page sits in.

Rationale Drift in terms is invisible one page at a time and plain across a module. The expensive case is a synonym that is a defined term elsewhere, because one word then names two things.

Requirement A consumer MUST name every non-Markdown surface its vocabulary reaches in paths.languageScan, including source, interface copy, the API contract, and acceptance tests.

Rationale Documentation is often the smallest surface a reader meets. A rejection also has to reach names, so ClientOrderId breaches a rejection of client the way a sentence does.

Example A pattern that matches no file is an error, so a surface cannot go unread unnoticed.

{ "paths": { "languageScan": ["apps/*/lib/i18n/dictionaries/*.json", "apps/api/tests/**/*.feature"] } }

Requirement A language record MUST list, in except, every compound in which a rejected word names a concept other than the one the rejection is about.

Rationale A rejection matches a word, and a word can belong to more than one term. A library can reject reservation in favor of hold while its reading room still books a reading-room reservation.

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

{ "term": "hold", "rejected": ["reservation"], "scope": "^docs/domain/modules/circulation/",
  "except": ["reading-room reservation"], "reason": "one word for a book hold and a seat booking" }

Requirement An authoring check MUST skip every generated region.

Rationale A generated region holds tool output, so a check would fail a page for words no author wrote.

Requirement A page MUST use Title Case for its title and sentence case for every other heading.

Rationale Titles read as names in an index, and sentence-case headings read as statements. Code names, product names and layer names keep their own capitalization.

Requirement An authored page MUST use the sections, in order, of its page style.

Rationale A fixed shape lets a reader and a tool find the authority, the context, the defaults, and the evidence in the same place on every page.

Requirement A documentation root index MUST state which page style answers which reader question before its first navigation group.

Rationale A reader who cannot tell a tutorial from a reference opens both and trusts neither.

Example A Which page do you want section names each style in the reader's terms, one sentence each.

Requirement A tutorial step or how-to step MUST name the repository command that performs it, where one exists.

Rationale A procedure that lists what a command already does becomes a second copy of that command, and the copy drifts.

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

Requirement A page MUST NOT describe both a command and the mechanism that command runs, outside an Underneath section.

Rationale A reader who wanted the command reads the mechanism as noise, and a reader who wanted the mechanism reads the command as an obstacle.

Requirement A command page MUST state under Underneath what the command runs, or that nothing beneath it is separately runnable.

Rationale A wrapper nobody can see through cannot be debugged when it fails.

Example A command with nothing separately runnable writes None. under Underneath.

Requirement A configuration setting a reader can change MUST appear on a configuration page with its default, its scope, and what overrides it.

Rationale A setting introduced inside a procedure is found only by the reader who already knows which procedure mentioned it.

Requirement A Standards provision MUST follow the Standard contract this page defines.

Rationale One identified obligation has one authority and one verification row.

Example ### Keep business invariants in Domain owns one obligation about where invariants are enforced.

Requirement A Convention provision MUST follow the Convention contract this page defines.

Rationale A heading under ## Conventions makes each replaceable default traceable without turning it into a rule.

Requirement An informative example MUST belong to its provision or to a Reference example that names every provision it demonstrates.

Rationale A reader can then tell an illustration from an independent obligation.

Requirement A provision ID MUST be litespec/<page>#<slug>, computed from its page path and its heading.

Rationale The page names the file and the slug names the heading, so a citation resolves with no lookup.

Example litespec/frontend/components#compose-composites-in-page-code is a heading on the frontend components page.

Requirement A provision ID's page segment MUST be its page's path under docs/ without the .md extension.

Rationale The page segment is the file a reader opens and its address on the published site.

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

Requirement A provision heading MUST carry no identifier text.

Rationale The page path and the heading already state the ID, so a written ID can only repeat it or contradict it.

Requirement A provision ID MUST NOT contain a sequence number.

Rationale A counter orders a provision among its siblings and says nothing about what it requires, which is the slug's job.

Requirement A page that owns provisions MUST give every provision one row in its Verification table.

Rationale Exact evidence makes each provision reviewable by a person or a tool.

Requirement A Verification row MUST mark its provision checkable or guidance.

Rationale The mark tells a reader whether a tool or a person judges the provision.

Requirement A standards change MUST leave docs/reference/provisions.md equal to the output of litespec provisions.

Rationale One generated page resolves every ID to its heading and page, so a reader follows a citation in one step.

Requirement A consumer page MUST open with a specification metadata block satisfying the record schema for its declared type.

Rationale The schema owns the field list of every record type and page style. The block is one JSON object between two lines that hold only ---. The model page states the record types and their homes.

Example A use-case page opens with this block.

---
{
  "type": "use-case",
  "id": "use-case/orders.cancel-order",
  "title": "Cancel order",
  "owner": "__OWNER__",
  "status": "approved"
}
---

Requirement A consumer page MUST use its opening specification metadata block as its only metadata carrier.

Rationale Source links, implementation paths, and verification evidence belong in the body sections they describe.

Requirement Every Markdown file under the consumer documentation root MUST declare a record type or page style, or sit under a declared unstructured path.

Rationale A file the validator cannot classify is skipped, and a skipped file looks sound. A directory index that owns no record uses the index style.

Requirement A specification MUST name the source or the command that produces any count, census, or membership list computed from code.

Rationale A restated number is right until the next unrelated commit, and nothing reports when it goes stale.

Example A page states the rule and the command rather than the total.

Every command declares an audit position. To count the declarations:

    grep -rl "Audited(" src/Application --include=*.cs | wc -l

Requirement A standards change MUST pass the repository validator, the test suite, and git diff --check.

Rationale The change report lists every skipped check with its reason. The command index names each check and its command.

Requirement The standards validator MUST evaluate only current standards material.

Rationale Each pinned release is a complete snapshot. Git history and the changelog give release context outside validation.

Requirement Current standards material MUST NOT contain history-specific paths, IDs, terms, aliases, replacement maps, release migration material, compatibility rules, or transition checks.

Rationale The published snapshot states its own contract without carrying earlier releases forward. An extension's Baseline relationship section names a provision it replaces inside this release, which is not history.

Requirement A LiteSpec release MUST state every active provision without depending on an earlier release.

Rationale A consumer reads one pinned snapshot and needs no other release to know its obligations.

Requirement The LiteSpec repository MUST NOT publish a compatibility guarantee, migration path, deprecation period, or identifier alias between its own releases.

Rationale LiteSpec is a pinned contract rather than a running service. A consumer product keeps its own API compatibility, migration, deprecation, and rollback provisions.

Requirement A consumer MAY keep any published LiteSpec release for as long as it chooses.

Rationale Adoption is the consumer's decision, and no repository change obliges a consumer to move.

Requirement A consumer MUST record the LiteSpec release it adopts in reviewedLiteSpecVersion within litespec.project.json.

Rationale A provision can gain force while keeping its ID, so an Exception written against an earlier release could otherwise apply to a rule nobody reread. Recording the release makes adoption an explicit act.