deploy-kit

Everything needed to get an application deployed: the model an application author writes, the decision record that justifies every rule in it, and, as it lands, the compiler that turns that model into deployable artifacts.

Status: pre-implementation. The model and its decision surface are here and enforced by CI. The compiler is being brought over from deploy-config-schema, which stays alive and authoritative until this repository can render the estate. Nothing here deploys anything yet.

What is in here

Path	What it holds
CONTEXT.md	The vocabulary. One term, one meaning; also the naming authority for code.
docs/architecture.md	Normative for code structure, the way spec/v1 is normative for the model.
docs/adr/	The decision surface, one directory per decision domain. Machine-checked.
docs/adr/model/	The v1 model: premises carrying falsifiable claims, decisions resting on them. The register counts both.
docs/adr/architecture/	The compiler's own structure. Pointers resolve against docs/architecture.md, not spec/v1.
docs/adr/deferred/	Delivery and co-testing decisions, defined separately from the model. Direction work, not v1.
spec/v1/	The normative specification. Chapters 00–60, including the two authored documents: Project Intent (10) and Platform Intent (14).
spec/v1/diagrams/	One drawn diagram per chapter, as an SVG with the editable draw.io diagram embedded. One palette; colour carries the layer.
spec/v1/examples/minimal/	The smallest complete Application: one project, one Application, one Process, 26 authored lines reaching 10 objects.
spec/v1/examples/	Worked examples: real Applications from this estate, written in the model.
emf/	The model-driven implementation: a Java build on Ecore, Xtext, OCL, QVT-Operational and Acceleo, held to parity with the production implementation and deleted after the course.
scripts/	The gates: the ADR contract, links, manifests and layer boundaries. TypeScript that Node runs directly (tooling).

The shape of the model

The three-model pipeline: three models, each joined to the next by a transformation, with the middle one as a contract (0003). They are stages of a pipeline, not metalevels, which is why "metamodel" here means a language definition and nothing else (CONTEXT.md):

1. Project Intent: hand-authored, requirements only. What an application owner knows and nobody else does: its cold-start budget, what its data is worth, which paths answer readiness.
2. Resolved Deployment: derived. Every platform decision, assigned from pinned, digested inputs (0006) and reviewable as a diff.
3. Deliverable Set: serialization only. No decisions.

Two rules do most of the work. Contention decides authority (0004): a value is platform-assigned exactly when it must be unique estate-wide or draws on a shared finite resource; everything else belongs to the Application. And derivation is total (0005): every hand-tuned value in the live estate must be reachable from something only the Application could have declared.

Reading it

Start at spec/v1/00-overview.md for the model, or docs/adr/README.md for why each rule is what it is.

ADRs justify; the spec is normative. Where an ADR and its normative: pointer disagree, the spec wins and the ADR is what gets fixed: CI resolves every pointer against a real heading, so the two cannot drift silently.

A premise carrying claim: open is decided in direction but not yet tested. It names its owner and the exact command or measurement that would settle it. Three of the eight are currently false as built, and say so.

What is deliberately not here

How the estate deploys, and how one unit's tests gate another's deploy, are defined separately from the model. The model makes exactly three demands on whatever delivery mechanism is eventually chosen:

Demand	Decided in
Release Unit atomicity: no member switches until every member is healthy	0060, superseded by 0062
Destructive operations gated by Durability Class	0015
Rendering only from pinned, digested inputs	0006, 0034

Everything else (push or pull, who applies, what prunes) is that definition's business. The parked direction work is in docs/adr/deferred/.

Local checks

nvm use             # Node 24.21.0, pinned in .nvmrc
npm ci
npm run verify      # lint, format, typecheck, ADR contract, tests + coverage

npm run lint:adrs alone runs the decision-record contract, and npm test runs the suite without enforcing coverage. npm run test:coverage (part of npm run verify) enforces the ratchet in vitest.config.ts: statements 99.15%, branches 96.49%, functions 100%, lines 99.08%.

Conventions

• CONTRIBUTING.md: Conventional Commits, PR flow
• VERSIONING.md: the versioning contract
• SECURITY.md: reporting
• AGENTS.md: the one agent contract every tool reads; CLAUDE.md imports it and adds Claude-specific notes only