Spec gap: fields requiring Phase A template protection are not exhaustively listed #9

New issue

Open

opened 2026-05-27 05:25:09 +00:00 by hurui200320 · 0 comments

hurui200320 commented

2026-05-27 05:25:09 +00:00

Member

Problem

§8.4 describes the template protection mechanism for Phase A rendering, where certain fields must have their template expressions preserved through Phase A so they can be rendered at runtime (Phase C). The spec lists two protected fields:

Template expressions that appear inside system_prompt fields (and any other field that is documented as supporting runtime templating, such as content under prompts).

However, the phrase "any other field that is documented as supporting runtime templating" does not link to any such exhaustive list. No section of the spec enumerates all runtime-templatable fields. An implementor must hunt through the entire spec and make guesses.

Fields that appear to support runtime templating but are not explicitly stated include:

system_prompt ✅ (mentioned)
prompts[*].content ✅ (mentioned)
template_vars values — unclear
Agent config.context values — unclear
LLM template field values — unclear
template_config.params values — unclear

If a protected field is missed, the library will render Phase C expressions at load time and fail (or silently produce wrong values) every time a runtime variable like {{ context.topic }} appears.

Impact on Library Implementation

The template protection scanner is a core part of the loading pipeline. An incomplete or incorrect set of protected fields causes subtle bugs where some system prompts render correctly and others don't, depending on what context variables are available at load time.

Fix Needed

Add a table or explicit list enumerating all fields that support Phase C (runtime) template rendering and must therefore be protected during Phase A. This list should be exhaustive and normative, not described by reference to scattered documentation.

References

§8.2 — Document-Level Rendering Lifecycle (step 2)
§8.4 — Deferred Rendering and Field Protection
§8.11 — Runtime Template Rendering (Phase C)
§10.4 — The prompts Section

## Problem §8.4 describes the template protection mechanism for Phase A rendering, where certain fields must have their template expressions preserved through Phase A so they can be rendered at runtime (Phase C). The spec lists two protected fields: > Template expressions that appear inside `system_prompt` fields (and any other field that is documented as supporting runtime templating, such as `content` under `prompts`). However, the phrase "any other field that is documented as supporting runtime templating" does not link to any such exhaustive list. No section of the spec enumerates all runtime-templatable fields. An implementor must hunt through the entire spec and make guesses. Fields that appear to support runtime templating but are not explicitly stated include: - `system_prompt` ✅ (mentioned) - `prompts[*].content` ✅ (mentioned) - `template_vars` values — unclear - Agent `config.context` values — unclear - LLM `template` field values — unclear - `template_config.params` values — unclear If a protected field is missed, the library will render Phase C expressions at load time and fail (or silently produce wrong values) every time a runtime variable like `{{ context.topic }}` appears. ## Impact on Library Implementation The template protection scanner is a core part of the loading pipeline. An incomplete or incorrect set of protected fields causes subtle bugs where some system prompts render correctly and others don't, depending on what context variables are available at load time. ## Fix Needed Add a table or explicit list enumerating **all fields** that support Phase C (runtime) template rendering and must therefore be protected during Phase A. This list should be exhaustive and normative, not described by reference to scattered documentation. ## References - §8.2 — Document-Level Rendering Lifecycle (step 2) - §8.4 — Deferred Rendering and Field Protection - §8.11 — Runtime Template Rendering (Phase C) - §10.4 — The `prompts` Section

Rows
Columns