Materialise the render directive-expansion seam when code-include lands #3

New Issue

2026-06-28T16:56:36+02:00

Brummel commented

2026-06-28 16:56:36 +02:00

Context

CLAUDE.md invariant 4 (closed directive vocabulary, open at one handler-registry
seam) and the walking-skeleton spec call for a directive-expansion seam in the
render pipeline. In the walking skeleton it is conceptual: src/render/mod.rs
documents the seam in a comment, but there is no AST-walk step — code and
table are native Markdown, so a no-op seam needs no code.

When this matters

The first non-native directive (code-include) needs a real AST walk over the
parsed Markdown to expand directives before/within rendering. At that point the
render pipeline should grow an explicit, testable expansion step (the handler
registry) rather than render_doc being reshaped ad hoc.

Note

Not actionable until code-include is specced; this records the deferred seam
so the next render cycle factors it deliberately. Surfaced by the cycle-0001
close audit (architect flagged it high; downgraded to carry-on — a no-op seam
is correct YAGNI for code + table this cycle).

## Context CLAUDE.md invariant 4 (closed directive vocabulary, open at one handler-registry seam) and the walking-skeleton spec call for a directive-expansion seam in the render pipeline. In the walking skeleton it is conceptual: `src/render/mod.rs` documents the seam in a comment, but there is no AST-walk step — `code` and `table` are native Markdown, so a no-op seam needs no code. ## When this matters The first non-native directive (`code-include`) needs a real AST walk over the parsed Markdown to expand directives before/within rendering. At that point the render pipeline should grow an explicit, testable expansion step (the handler registry) rather than `render_doc` being reshaped ad hoc. ## Note Not actionable until `code-include` is specced; this records the deferred seam so the next render cycle factors it deliberately. Surfaced by the cycle-0001 close audit (architect flagged it high; downgraded to carry-on — a no-op seam is correct YAGNI for code + table this cycle).

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Brummel/DocSite#3