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
.mustachefiles 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>.mustacheblock preceded by prose (role, model inputs, output artefact, profiles). Groups (cmake,cpp,sql,doc,assets) get<slug>_group.orgnamespace docs;overview.orgtops 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.elbehind thetangle_codegen_templatesCMake 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/templatesfor org↔mustache drift;regenerate_facet_inventories.py --checkfor 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) andcompass add facet_groupscaffold 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 withproj:(GitHub blob URLs), notfile:— 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.