Skip to content

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.

Back to the work index

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-text or rn-forge-generation package. 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 delimiters preset on TemplateEngine for YAML whose own {{ }} syntax clashes with Jinja's. The environment keywords variable_start_string and variable_end_string already do it, and a preset would only rename them (ADR-0001, rule 2).