Story: Document MASD and code generation principles

Table of Contents

This page documents a story in Sprint 19. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

Goal

Produce a permanent technical knowledge document that establishes code generation as a first-class engineering principle of ORE Studio. The document weaves the theoretical foundations of Model-Driven Engineering (MDE) and the MASD method with the concrete choices made in ORE Studio's ores.codegen implementation, so that both new contributors and LLM agents understand not just what the generator does but why it exists and what it is working towards.

The document also articulates the long-term objective: backing out code generation from a reference implementation. Rather than designing abstract models first, ORE Studio commissions entities by hand, extracts the recurring pattern into a generator, and then uses that generator to produce all subsequent entities. The currency entity is the current reference implementation; it is the yardstick against which codegen coverage is measured.

Once written, the document is linked from ores.compass (the site entry point) so that it is reachable from the top of the documentation tree.

Status

Field Value
State DONE
Parent sprint Sprint 19
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-06-01

Acceptance

  • A knowledge document exists in doc/knowledge/ titled "MASD and code generation principles" covering:
    • The theoretical underpinnings of MDE and MASD as they apply to ORE Studio.
    • How ores.codegen realises these principles in practice (inputs, templates, outputs, profiles).
    • The reference-implementation backout strategy: hand-write one entity fully (currency), extract the pattern, generate all others.
    • A clear statement of what code generation covers today vs. what remains manual, keyed to the entity evaluation checklist.
  • The document is linked from ores.codegen (component overview) and from compass.org (the top-level site entry point).
  • The document links back to ores.codegen, ores.codegen architecture, and the entity evaluation checklist.
  • The document passes validate_docs.sh and the site builds cleanly.

Tasks

Task State Start End Description
T1: Write the MASD and code generation principles doc DONE 2026-06-01 2026-06-01 Author the knowledge document; wire into site nav

Decisions

  • Document type: knowledge (cross-cutting reference, not a recipe or task). Lives in doc/knowledge/ with a #+level: cross tag so it appears in the knowledge index.
  • Entry point linkage: add a bullet in compass.org under a new ** Engineering principles subsection rather than burying it inside a component page; this makes it discoverable from the top of the tree.
  • MASD scope: focus on ORE Studio's own usage of MASD concepts (meta-models, templates, profiles, the backout strategy). Do not attempt a comprehensive survey of the academic literature — one citation to the foundational Brambilla et al. or Selic work is sufficient.

Out of scope

  • Changes to ores.codegen itself (new templates, new outputs).
  • Generation of new entity artefacts from the expanded generator.
  • Documentation of non-codegen architectural decisions.

Emacs 29.1 (Org mode 9.6.6)