Guring

one continuous procedure: make a real request's contract visible in MDX, implement the smallest coherent change, leave evidence the result still matches the contract. operating shape first; detailed evidence in the same document for people and agents.

ruling

outcome

one readable contract, one accountable implementation, proportionate verification
no private source, guessed fallback, or undocumented behavior is treated as done

why

intent living only in code → every consumer (reviewer, concurrent agent, later maintainer) reverse-engineers the target state from a moving implementation; completion becomes an author's claim, not an observed result
contract first → one accountable path: the contract states what must be true, the implementation is the smallest coherent step toward it, verification proves the boundary that changed
without that order: concurrent work collides on hidden assumptions and evidence never accumulates

start with the visible contract

write or update the owning MDX before changing code.

name: user outcome, domain words, non-goals, invariants, source of truth, evidence that proves completion
high-level design readable without expansion; implementation mechanics, diagnostics, file manifests inside accordions

choose domain words

a domain word is the shortest, easiest word in the project scope immediately related to one thing. use workflow and step only when each is unique in that scope. record chosen words in the domain glossary, then use them consistently in symbols, tables, routes, and slices.

create or refresh the slice

a slice is one MDX file covering a full vertical flow: user outcome, high-level design, detailed boundaries, implementation manifest, hashes, verification. a stale manifest blocks a completion claim until the slice is reviewed and its evidence refreshed.

build one coherent path

implement from the contract downward: boundary validation → domain behavior → persistence or providers → interface.

prefer generated API clients and schemas, deterministic values, direct symbols, one owner per concept
high-level files easy to scan; lower-level foundations divided by independent responsibilities

MDX is the interface

treat generated or authored MDX as untrusted until it parses. validate frontmatter, allowed components, component props, links, owning schema. a failed response gets one bounded repair pass with structured diagnostics; if it still fails, return the typed failure — never persist a silent fallback.

keep code deterministic

choose schemas, parsers, builders, typed identifiers, and explicit mapping tables over casing transforms, replace, raw slicing, or inferred aliases. one stable name and one accountable owner per value, from input to display.

keep the tree navigable

keep high-level feature files few and direct. split lower foundations when routes, schemas, mappings, or integrations have independently understandable responsibilities. an index file exists only as an intentional barrel; de-nest a folder that contains just one file.

verify the whole flow

read the slice and changed-file change ledgers before editing
update the MDX contract first, then change code
run the narrowest checks that prove the changed boundary: parsing and content inventory for MDX; generation, types, lint, build, route smoke check for the public surface
record failures with a stable diagnostic and exact remediation boundary

completion evidence

completion means the rendered procedure, implementation manifest, and verification results agree. hash the declared implementation inputs after review. if a hash, invariant, or route check disagrees, create the smallest repair task and keep the slice stale.

agent handoff

every agent reads the top JSDoc change ledger before modifying a code file; every MDX document starts with frontmatter. a handoff names the updated contract, exact files and boundaries, verification evidence, and any unresolved diagnostic — never asks a later agent to infer missing intent.

where this procedure comes from

Guring is the public face of a private corpus; each phase is owned by a deeper standard:

Guring phase	owning standard
start with the visible contract	specification-first
verify the whole flow	verification evidence
MDX as the durable knowledge interface	MDX knowledge loop

good and bad

bad

—agent A refactors files while agent B is reviewing the same slice.
—agent A finishes refactoring, then writes the intended architecture in the slice.
—agent B's concurrent review hits conflicts: files were renamed, imports moved, intent was not visible.
—agent B does not know which changes are intentional design vs. cleanup, cannot safely rebase work, throws error.
—slice remains stale; intended architecture is written only after conflicts block others.

another concrete failure:

—agent A refactors Domain A without documenting the target state first.
—agent B, working on Domain B, relies on old contracts from Domain A.
—agent A's change breaks Agent B's assumptions mid-work, caught only during integration.
—slice remains unclear about which contracts changed, which are still valid, and why.

the broken change record shape:

slice: incomplete refactor (stale)

implementation steps (wrong order):
1. renamed files: userService.ts → user.service.ts
2. moved imports: ../utils → ~/lib/utils
3. changed function signature: createUser(data) → createUser({ name, email })

documentation (written after):
the refactor aimed to:
- use conventional file naming
- consolidate import paths
- add typed parameters

—no slice existed when work started. conflicts arose. contract was written after implementation.

why this fails — code changed before contract, so concurrent agents cannot:

discover the intended target while implementation is moving
validate whether concurrent work is compatible
rebase or merge safely — intentional refactors are indistinguishable from byproducts
update the record of what changed and why — the slice stays stale and unreviewable

good

—agent A writes the slice: user outcome, high-level design, exact files touched, implementation hash.
—agent B, working on Domain B, reads the slice and validates contract compatibility. finds a conflict, raises it before coding.
—agent A acknowledges conflict, updates slice, confirms the narrowed boundary.
—agent B proceeds with known, frozen contract.
—agent A refactors, updates implementation hash, marks slice complete.
—next reviewer sees contract, evidence, and hash — no ambiguity about what changed or why.

the correct change record shape:

slice: adopt typed parameters for multi-input functions (complete)

user outcome:
function calls are explicit about what each argument is, optional parameters are visible, and adding new parameters doesn't break callers.

rule:
use typed parameter objects when a function has 3+ parameters or is extensible.

verification:
grep for functions with 3+ positional args; confirm they use typed objects.

// contract → implementation (visible, frozen)
type CreateUserParams = {
  name: string;
  email: string;
  role?: "admin" | "user";
};

function createUser({ name, email, role = "user" }: CreateUserParams) {
  // ...
}

// evidence: change record shows contract-first path
// 1. slice written with user outcome, rule, verification
// 2. implementation follows contract exactly
// 3. verification evidence recorded in slice

why this works — contract-first makes each change:

discoverable: target state, boundary, non-goals visible before implementation starts
mergeable: concurrent agents validate against a frozen contract, not moving code
auditable: slice records intent, what changed, and the evidence it matches
handoff-safe: next agent reads contract first, then evidence, never guesses intent from code alone