Story: Convert codegen mustache templates to literate org-mode documents

Table of Contents

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

Goal

Every codegen mustache template is owned by a literate org-mode document. Today projects/ores.codegen/library/templates/ holds 116 raw .mustache files with no narrative: nothing explains what model fields a template consumes, what artefact it produces, or why its structure is the way it is. The project already has a working literate pattern — doc/knowledge/architecture/clang_format_config.org tangles to .clang-format, doc/llm/claude_code_settings.org tangles to .claude/settings.json — and this story extends it to the codegen template library.

After this story, the org document is the single source of truth for each template: it documents the template's role, its model inputs and its output artefact, and tangles to the .mustache file consumed by codegen. The library is organised as a three-level literate hierarchy — template ← facet doc ← group doc ← groups overview: each facet group gets a "namespace" org file documenting the group, and a top-level file describes all the groups. The tangled files carry a generated-file header naming their source document, and a zero-diff tangle check makes drift between org and mustache detectable.

Promoted from inbox capture 76178191-E20D-4479-BC01-79B877247D03, which lives on as the rollout task below.

Status

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

Acceptance

  • All templates under projects/ores.codegen/library/templates/ have a corresponding literate org document that tangles to them.
  • Tangled .mustache files carry a generated-file header naming the source org document.
  • Tangling is reproducible via the project tangle tooling — no manual steps.
  • Codegen output is byte-identical before and after the migration (zero-diff regeneration).
  • A drift check (zero-diff on tangle) exists so CI or compass can detect divergence between org sources and tangled templates.

Tasks

Task State Start End Description
Design the literate template layout and tangle workflow DONE 2026-06-06 2026-06-06 Decide file layout, grouping, tangle tooling and drift check; prove with a pilot batch.
Tangle all mustache templates from facet-documenting org files DONE 2026-06-06 2026-06-06 Every mustache template should be tangled from an org-mode file that documents its facet (literate style, as with the gnuplot charts). Each facet group gets a 'namespace' org file documenting the group, and a top-level file describes all the groups — a three-level literate hierarchy: template <- facet doc <- group doc <- groups overview.
Add facet and facet-group doc types to compass and codegen DONE 2026-06-06 2026-06-06 The literate template hierarchy introduces two new document types — the facet doc (one per template family, tangling to its .mustache files) and the facet grouping doc (namespace page per group). Teach ores.codegen generate_doc and compass add to scaffold both, so facet docs are never hand-rolled from the generic knowledge type.
Replace file: links with proj: links across the documentation DONE 2026-06-06 2026-06-07 Audit every org document for file: links pointing at repo files (sources, JSON, scripts, images) and convert them to proj: links, which export to GitHub blob URLs on the published site. file: links to non-org files 404 because the site build only publishes org->html; found via the profiles.json links in the template-library docs.
Refine the cpp facet grouping DONE 2026-06-06 2026-06-06 The cpp group's 58 templates landed in five facets, but the split is coarse: cpp_domain_type holds 22 templates and cpp_service mixes two distinct families (component-service scaffolding vs the per-entity service pair). Analyse the set against the profiles and the MASD facet definitions and re-cut into finer, more cohesive facets.

Decisions

  • Granularity: one org file per facet, with each template a #+begin_src mustache :tangle <name>.mustache block preceded by prose (role, model inputs, output artefact, profiles). Groups (cmake, cpp, sql, doc, assets) get <slug>_group.org namespace docs; overview.org tops the hierarchy.
  • Facet cut: facets are cohesive MASD facets — entity-lifecycle layer × profile membership — not filename-prefix buckets, and stay at roughly a dozen templates or fewer without rationale. The cpp re-cut (PR #1136) set the pattern: cpp_domain, cpp_table, cpp_repository, cpp_qt, cpp_messaging, cpp_service_app, cpp_component, cpp_model_types. IDs stay stable when a facet merely renames; moved blocks get their GENERATED FILE header repointed (render-neutral, header-only artefact diffs).
  • Location: org sources co-located with their artefacts in projects/ores.codegen/library/templates/.
  • Tangle tooling: ores-build-codegen-templates.el behind the tangle_codegen_templates CMake target; tangles every org doc in the templates directory (group docs/overview are no-ops).
  • Header: every tangled file starts with {{! GENERATED FILE — tangled from <facet>.org. Edit the org source. }} — standalone mustache comments are spec-stripped, so pystache output is byte-identical (proven on all eight cmake templates).
  • Drift checks: tangle then git diff --exit-code -- projects/ores.codegen/library/templates for org↔mustache drift; regenerate_facet_inventories.py --check for group-inventory drift. CI wiring lands with the rollout task.
  • Doc types: compass add facet (requires --facet-group, lands #+facet_group: for the inventory generator) and compass add facet_group scaffold the hierarchy; facet inventories in group docs are generated, never hand-edited.
  • Link rule: repo files not published as HTML (e.g. profiles.json) are linked with proj: (GitHub blob URLs), not file: — repo-wide cleanup tracked by the replace-file-links task.

Out of scope

  • Changing template content or codegen behaviour — this is a format/documentation migration; generated output must not change.
  • Migrating the entity models to org — that is the in-flight Codegen unified model — org-mode migration story.

Emacs 29.1 (Org mode 9.6.6)