Gravity Standard

02 · Specifications

Business rules are the stable part. Implementation is allowed to change.

People describe an application in plain language. An AI makes it formal and builds it. Tests that cite each numbered rule decide whether the build is acceptable, no matter which model wrote the code or when.

A specification with rules LR-001 to LR-003 compiles to a definition, which builds an implementation. The implementation is regenerated as version two with a different shape, and the same three rule tests run again and pass. SPECIFICATION Loan Request LR-001LR-002LR-003 markdown · source of truth DEFINITION kind: processname: loan-requeststages: [ … ]rules: [ … ] JSON · reviewed IMPLEMENTATION Build v1 Build v2 · regenerated code · schema · forms · tests RULE TESTS · CITE THE IDS · DECIDE ACCEPTANCE LR-001LR-002LR-003 v1 accepted: every rule passes v2 accepted: a different build, the same rules
The build changes shape. The rules and their tests don't.

A specification states what must be true. How it's made true, whether by a database constraint, a form check or a type in code, is the implementer's choice, and a later AI model may choose better. That's expected and welcome.

What must not drift is the rule itself. Every rule has a stable ID, every rule is testable, and a rule without a test is a gap.

When a spec and its definition disagree, the spec wins and the definition is regenerated. A definition is never edited by hand to make them agree.

Three layers

Specification, definition, implementation.

LayerWritten byFormFate
SpecificationPeople, with AI helpMarkdown a business person can read and correctThe source of truth
DefinitionThe AI, from the specJSON with a published JSON SchemaReviewed, validated and published; regenerated when the spec changes
ImplementationThe AI, from the spec and definitionCode, schema, forms, state machines and testsRebuildable; accepted when the rule tests pass

Compiling a definition

Mechanical parts are copied. Judgment parts are owed.

The compile step writes a skeleton, deterministically: the same specifications give the same bytes. It fills in what a program can parse, such as names, types, fields, stages and timeouts. Everything that needs judgment is left owed.

An owed part fails the schema on purpose. The checker's report becomes the AI's to-do list, and a half-compiled definition can never be published.

A definition skeleton has mechanical parts filled in and four owed parts. The AI fills each owed part, the checker count falls from four to zero, and the definition becomes valid for review. support-ticket.json enforcement: owed enforcement: required-when reader access: owed reader access: view (id, name) flow condition: owed flow condition: outcome = resolved CHECKER 3 2 1 0 parts owed VALID · TO REVIEW AI proposes. Validation and a person approve.

A record type, as written

A short document a business person can correct.

No tables, Lambdas or state machines. Just the data, its statuses, its classification and the rules, each with an ID that tests will cite.

Security, tenant isolation and logging come from the foundation and are never restated in a spec.

domains/servicing/person.md
# Person

Code: PER
Domain: servicing
Retention: seven years after the person's last loan closes

## Fields
| Field      | Type | Required | Class        | Meaning           |
|------------|------|----------|--------------|-------------------|
| name       | text | yes      | confidential | Legal name        |
| birth date | date | yes      | confidential | Date of birth     |
| ssn        | text | no       | restricted   | Government ID     |

## Rules
- PER-001: Age must be between 0 and 150 years.
- PER-002: A person's SSN, when present, is unique
  within the tenant.

How an AI assistant works

The spec is read first, and every change starts there.

  1. Read the spec and the foundation documents it relies on.
  2. Propose any spec change, such as a new rule, stage or field, before changing anything else, and show it for review.
  3. Compile the spec into its definition and validate it against the published schema.
  4. Realize the definition: schema, forms, state machine, queries, automation and tests.
  5. Cite rule IDs in tests and enforcement, and report rule coverage.

The AI may strengthen an implementation at any time, as long as the rule tests pass. It must not weaken, drop or reinterpret a rule without a spec change a person reviews.

Rule enforcement

A fixed set of kinds, and no expression language.

A condition is a comparison on one field, or an all or any of comparisons. Anything more complex is hand-written Go, where it's testable and observable.

KindMeaning
required-whenA field must have a value when a condition holds
uniqueFields are unique together within the tenant or the company
compareCompares a field with a value, another field or a tenant parameter
range · age · pattern · lengthBounds on numbers, ages, text patterns and text length
key-existsA business key in another domain names something that exists
status-moves · initial-statusStatus starts where declared and moves only along declared paths
flowThe process flow itself makes the rule true
codeHand-written code makes it true, and names its handler
retiredThe rule is retired; its ID is never reused