E18 — kiln extraction
| State | Closed |
| Start Date | 2026-10-25 |
| Closed Date | 2026-11-13 |
| Feature | State | Iteration | Stories |
|---|---|---|---|
| F18.1 — Templates, generation and state move to commons | Closed | release-6 | 3 Closed |
| F18.2 — Templated artifacts and plan diffs | Closed | release-6 | 2 Closed |
| F18.3 — Fast, complete document reads and writes | Closed | release-6 | 4 Closed |
| F18.4 — Markdown structure | Closed | release-6 | 1 Closed |
| F18.5 — One pin set on the new tags | Removed | — | 1 Removed |
| F18.6 — Cache Markdown structure by text | Closed | release-8 | 1 Closed |
| F18.7 — A managed block's end marker can sit at a different indent | Closed | release-8 | 2 Closed |
kiln, the rn-forge repository generator, grew plumbing that any application
reading configuration, rendering text or checking Markdown would write again. It
reads TOML through tomllib because DocumentUtils is seven times slower. It
reads YAML through PyYAML's C loader because YamlUtils is fourteen times
slower. It caches a TemplateEngine per module and wraps every render in an
Artifact by hand. It also parses Markdown headings, links and tables with
regular expressions. This epic makes the kit's own paths fast and complete
enough that kiln deletes those copies. It also moves template rendering and the
generation engine to commons. A web application that writes files from templates
can then plan, preview, apply and detect drift, without the CLI and installer
layers.
kiln adopts this after the release and the pin bump it requires; until then it keeps its own code.
Context
Reopened on 2026-11-10 for F18.6 and F18.7. The original extraction shipped in Release 6; Markdown parse caching and the managed block's end indent are planned for Release 8.
Placed as its own epic, as E17 was for Apollo: the features come from one consumer's review, span several packages and are not deferred.
Placement follows ADR-0002, rule 1, as amended on 2026-10-24. Rule 3 now keeps only the command-line and installation layers in tooling. The template engine, the generation engine, the state store and the Markdown helpers name nothing about either, so they go to commons:
- the template engine and the Markdown helpers behind extras (ADR-0003);
- the generation engine outside the facade, since it needs no third-party package.
jinja2, Python-Markdown and markdown-it-py are light, and the generation engine
has no dependency set of its own. None of them passes
ADR-0011's first test for a package of its own.
rn-forge-tooling keeps the lifecycle verbs and install mechanics.
Considered and rejected
- Keep the generation engine in tooling. It made an application that writes files from templates install the CLI and installer layers to get plan, diff, atomic apply and drift detection. Rule 1 places code by signature, not by today's callers.
- A new ADR for the move. ADR-0002's rule 1 already decides it; what changed is rule 3's wording, which is amended in place.
- A
rn-forge-textorrn-forge-generationpackage. Each fails ADR-0011's first test: light dependencies, or none. - A docs-site link checker (nav targets, orphans,
exclude_docs). Its rules are MkDocs policy, and kiln is its only consumer. - A Markdown work-item reader for epic, feature and release pages. It is kiln's spec model, not Markdown.
- A
delimiterspreset onTemplateEnginefor YAML whose own{{ }}syntax clashes with Jinja's. The environment keywordsvariable_start_stringandvariable_end_stringalready do it, and a preset would only rename them (ADR-0001, rule 2).