The AI-Native Code Discipline — Manifesto

0. What this is, in one paragraph

08Code generation by frontier models is already good.

09The unsolved problem is the rest of the lifecycle: a model — often a different, weaker model than the author — must later read, understand, and safely change that code.

10The Discipline optimizes for that.

11Its single design target is to lower the minimum model capability required to maintain code safely, so that a swarm of small agents can maintain code that a frontier model authored.

1. The target function: author/reader asymmetry

12The economics that justify everything below: a strong author runs once; weak readers run thousands of times.

13So the discipline moves cost from maintenance-time to authoring-time.

14The strong author materializes expensive cognition into infrastructure — meta-layer, contracts, executable scaffolds, recorded rationale — and the weak swarm lives off that capital.

15The Discipline is a capability-gap compensator.

16A clever construct with no materialized rationale is theft from the reader pool.

17This is why "make the code simpler" is the wrong frame.

18We are not lowering the ceiling of what the code does; we are lowering the floor of who can safely touch it.

2. The six axioms, projected to the language level

19The axioms are unchanged from the Charter; here is what each means for how code and its metadata are written.

• 20A1 — Explainability. Every artifact carries a machine-resolvable chain from code to requirement to rationale (spec:// URIs, in-source #[spec(...)] edges). Unexplainable code is unmergeable. Language-level: identifiers, errors, and items are anchored to requirements, not free-floating.
• A2 — Never pay twice. Derived cognition is materialized content-addressed and dependency-tracked. Language-level: anything mechanically derivable (boilerplate, indexes, glue) is generated, not hand-maintained; the strong author's analysis is stored, not re-run.
• A3 — Algorithmic floor. Where a deterministic procedure exists, the LLM is forbidden; its outputs sink below the floor. Language-level: push as much intent as possible into machine-checkable form — types, exhaustiveness, contracts — so a checker, not a model, enforces it. This is the engine of the central law (§3).
• A4 — Human accountability. AI checks and proposes; the human is the accountable author; diffs stay human-reviewable. Language-level: no change is so clever a human cannot review it; determinism keeps diffs semantic.
• A5 — Rule = code. Every rule ships a checker or is explicitly a WISH. Language-level: a style rule with no linter is not a rule; it is documentation that decays (see §6). Rulebook health is the wish-ratio, not the page count.
• A6 — Reality before aspiration. Gates measure deltas against inventoried reality; debt, unimplemented intent, and contradiction are first-class tracked objects. Language-level: the code's actual state — not its intended state — is what tooling reasons over.

3. The central law: idiomatic inside the file, engineered around the file

21The strongest empirical result we found, dated and controlled: models collapse on out-of-distribution surface syntax (EsoLang-Bench, Mar 2026: frontier models 0–11% on esoteric languages they could solve trivially in Python) — and current agents largely recover that collapse through tools and in-session strategy (the Jun 2026 follow-up: the same tasks, 87–100% with file-editing + interpreter loops).

22In-context learning could not teach the unfamiliar surface (few-shot gave ~0 benefit); the recovery came from the verification loop and from building executable helpers, not from prose.

23The law that follows:

24

Keep the code surface inside the training distribution. Put all the strictness into the meta-layer, the type system, and the verification loop — which sit AROUND the code, not in its syntax.

25Concretely: AI-Native Rust looks like ordinary idiomatic Rust at the token level (no invented notation, no exotic dialect — that would inherit the OOD penalty).

26What is unusual is everything around it:

• 27dense machine-checkable metadata,
• contract-bearing types,
• executable scaffolds,
• and a fast per-unit verification loop.

28We do not make the language stranger; we make its envelope stricter.

4. Stricter, not simpler — and where the strictness lives

29"AI-native" is more discipline, not less — but the added strictness lives exclusively in machine-checkable form.

30More types, more contracts, more verification, more metadata — never more exotic syntax.

31Every constraint we add must be either enforced by a checker (A5) or it does not exist.

32A rule a model must remember is a rule that decays; a rule a compiler enforces is a rule that holds.

33The discipline's strictness is the compiler's strictness, extended.

34Bans carry escape hatches.

35Forbidden-by-default constructs (raw unwrap in domain logic, inline asm, proc-macro magic, stringly-typed protocols) remain legal with machinery and a recorded reason — the unsafe / #[spec(deviates, reason)] pattern.

36A ban with no escape hatch is a bug in the discipline; a deviation with no reason is a bug in the code.

37The strictness is equal across projections. No language projection enforces the discipline more weakly than another; a rule the pilot enforces is either enforced in every projection or its absence carries a recorded reason.

38This is the projection-level twin of ##BAN-WITHOUT-HATCH-IS-A-BUG: an unexplained asymmetry between projections is a bug in the discipline exactly as a reasonless deviation is a bug in the code. A projection is weaker with machinery and a recorded reason — a language genuinely lacking an idiom's analogue (the compiler already enforces it; the idiom does not exist in that language) records that, and the recorded reason is the escape hatch.

39The pilot language is the current reference bar because it is furthest along, not because it is privileged; as a projection matures past the pilot on some axis, the bar rises to it. A new language inherits the law on arrival — it is a projection of the one discipline, held to the same floor.

40A projection weaker on some rule with no recorded reason is not a smaller stack; it is the discipline silently decaying — the failure mode A5 and A6 exist to make impossible. Weakening a rule for a projection because building its checker is harder there is the same category of error as dropping the rule for being unused (§4): the checker is built or the reason is recorded, never the rule quietly relaxed.

5. Runnable capital: explanation must be executable

41The second decisive result: weak agents given a written distillation of a strong agent's strategy barely improved; given an executable helper library carrying the same strategy, they leapt (Sonnet 4.6 on Brainfuck: 12→12 with text, 12→64 with runnable helpers).

42The mechanism: mid-tier models do not lack the idea; they cannot build the reusable code to carry it out.

43Therefore: explanation capital must be runnable capital.

44The meta-layer ships executable scaffolds — generators, typed builders, runnable contracts, differential oracles, compiled examples, local simulators (the nine classes; see 02-EXECUTABLE-SCAFFOLDS.xml).

45Prose that could be a checker, a doctest, or a typed API is a WISH until it becomes one.

46A spec that says "use the registry pattern" is weaker than one that ships the registry macro plus a working example.

47The honest boundary on this: that result is about generation against an unfamiliar target.

48Transfer to comprehension and modification of in-distribution Rust is [E-mid] — plausible, not yet measured on our codebase.

49It is the primary thing the pilot must validate.

6. Delivery: the discipline is not "know N rules"

50The owner's central worry is correct: a weak model cannot apply forty rules at once, in the right order.

51The resolution is that rules are never all active at once.

52Each rule/pattern is a card (01-PATTERN-CARD-FORMAT.xml) carrying a Trigger (when to switch on), a short Routine (≤7 steps), a Checker (machine verification), and a Budget (attention cost).

53The harness delivers only the cards whose triggers fire, as a small activation-matched set (lazy-push). Specified, not built at card grain: no harness reads a card. Lazy-push itself is real one level up — vibe implements DeliveryMode::LazyPush for subskills, matching an agent's task description against a subskill description, with vibe check enforcing that a lazy-push unit carries one and warning on activation overlap between siblings. Nothing applies that machinery to cards: no reader of card-ops, of a card trigger, or of cards/INDEX.md exists in any language anywhere in the repository. Card delivery today is a boot instruction a session follows by hand, not an activation match the harness computes.

54Triggers escalate by cost:

1. 55Inline (edit-time) — lint-detectable, fires in the per-cell loop; the cheapest mode and the one that fires most often. Each stack's cards/INDEX.md is the roster: of the nine scaffold cards, 2 sit here (C, F) against 5 at gate.
2. Gate (merge-time) — heavier checks (oracles, proofs) that need not run per keystroke.
3. Raid (scheduled) — swept periodically across a layer when per-edit triggers cannot keep up (03-RAID-PLAYBOOK.xml).
4. Review (human/strong-agent) — needs judgment a weak reader lacks.

56This is grounded in the AGENTbench result (Feb 2026): bloated context hurts weak agents; minimal, sufficient context helps.

57The discipline therefore proselytizes minimal sufficiency — and obeys it: this package is a full authoring/review artifact, but runtime delivery to a weak reader is an extract (the card's ops block), never the whole corpus.

7. The honest boundary (what we do not yet know)

58This is a beta.

59Stated plainly so the pilot can falsify it:

• 60Transfer is unproven. The executable-scaffold result is generation, not modification. [E-mid].
• There is a floor. Even with executable scaffolds, the weakest models (Haiku-4.5-class, and our target Qwen-32B may sit lower on some axes) did not recover — scaffolds amplify capability, they do not create it. The discipline lowers the floor; it does not remove it.
• Surface-distribution is current. The "stay in-distribution" law is tied to today's model generation; it carries a sunset (R-050) and must be re-checked as models change. The obligation stands; the sunset it names has no carrier. R-050 is authored in no document that ships — every occurrence across this package, the language stacks, the engine crates and the host is a citation, and the ATLAS roster it would live in holds only BLD- / DR1- / DR2- / R2C- / R3- ids. Nothing schedules the re-check, expires the law, or records when it was last examined. The sunset mechanism does exist one grain over — every one of the 22 entries in the host's debt registry carries a sunset field, and cards carry a Sunset: clause in their Risks band — so the pattern is proven and simply not applied to this law.
• Measurement is deferred by design. We build the core on internal logic plus others' published evidence, and instrument later, at a buyer's expense. Every card therefore carries a falsifiable prediction in place of a present measurement.

61A discipline that names its own failure modes is more trustworthy than one that hides them.

62This one names them.

8. The package map

63Guiding layer (T1, language-independent):

• 6400-MANIFESTO.xml — this document.
• 01-PATTERN-CARD-FORMAT.xml — the format every pattern is written in (GoF × JEP × operational layer).
• 02-EXECUTABLE-SCAFFOLDS.xml — the nine scaffold classes; the runnable-capital catalog.
• 03-RAID-PLAYBOOK.xml — layered, scheduled refactoring campaigns (raids).
• 04-SWEEP-PLAYBOOK.xml — the standing sweep that holds a tree inside the Discipline between campaigns.
• 05-CAMPAIGN-FORM.xml — the campaign paper trail: cold-executable plans, baselines, predictions, logs, reports.
• 06-WAL-CONVENTION.xml — session-durable project state (optional but preferred).

65Mechanisms (T1, language-independent; implemented per-stack):

• 66mechanisms/ENGINE-CONFORM-v0.1.xml — the conformance engine: fact store, rules-as-queries, SARIF, ratchet baseline.
• mechanisms/PROP-014-specmap-bidirectional-traceability.xml — spec↔code traceability: anchors, revisions, tags, the index.
• mechanisms/BROWNFIELD-PROTOCOL-v0.1.xml — terraforming unfinished projects: inventory-not-gate, the registries, xfail-strict, characterization.
• mechanisms/LEDGER-INTENT-v0.1.xml — the intent ledger: facts vs interpretations, epoch-keyed cache.

67Spec-unit URIs for this package read spec://org.vibevm.ai-native/core-ai-native/<docpath>#<anchor> (e.g. spec://org.vibevm.ai-native/core-ai-native/mechanisms/ENGINE-CONFORM-v0.1#rules); the Rust implementations ship in stack:org.vibevm.ai-native/rust-ai-native-lang (rust-ai-native-conform, rust-ai-native-specmap, rust-ai-native).

68Language projections (T2):

• 69spec/rust/GUIDE-AI-NATIVE-RUST.md in stack:org.vibevm.ai-native/rust-ai-native-lang — the law and scaffolds projected onto Rust; supersedes GUIDE-RUST-v0.1. (Pilot language.)
• rust/tools/rust-ai-native-tcg.md — token-level type-aware constrained generation for Rust (very-far-future; carries the family prefix per PROP-028 §2.4).
• The AGENTIC delivery shipped first: rust/tools/vibe-agentic-tcg-rust.md — the consultation oracle over rust-analyzer.
• typescript/GUIDE-AI-NATIVE-TYPESCRIPT.md — projected onto TypeScript (typed language only; JS guide separate). The language where the generation-time type oracle already exists and codemods are mature.
• typescript/tools/typescript-ai-native-tcg.md — type-aware constrained generation for TypeScript (a wrap-and-extend of existing PLDI'25 work, not from scratch). @status:unknown
• Other languages (Python, C++, Go, Java, Kotlin) projected after Rust + TypeScript are validated.

70Cards (the patterns) — shipped per-language by each stack:

• 71cards/INDEX.md — registry, axes, trigger modes (one per language stack).
• cards/scaffold-{a..i}-*.md — the nine scaffold patterns in their per-language card shape. The core (T1) defines the card FORMAT (01-PATTERN-CARD-FORMAT.xml) and the scaffold CATALOG (02-EXECUTABLE-SCAFFOLDS.xml), both language-neutral; each language stack ships the concrete cards/ (Rust cards in stack-rust-ai-native, TypeScript cards in stack-typescript-ai-native), so the weak-reader runtime surface for an edit is a language-matched Band-3 block.

72Appendix (synthesis provenance):

• 73appendix/CONTRADICTION-MAP.xml — where sources and hypotheses conflict, and the resolutions.
• appendix/ATLAS.xml — the findings ledger rendered for humans (generated from findings.jsonl). Correction: the ledger is real and is the appendix itself — 87 `#FINDING- records, whose ids the cards cite and resolve against. The generator is not: no findings.jsonl` is tracked anywhere in this repository, in any package, or in any consumer, so ATLAS is authored directly rather than rendered from a source. Read the parenthetical as the intended pipeline, not as the current one (F-088).*

74The vibevm-specific adoption plan lives OUTSIDE this package, in the host's terraform/, because the Discipline is the product and vibevm is its pilot.