docs(planning): draft document-scaffolding — C-0011 capability + D-0017 generation gaps

[sksizer]

Summary

Two draft planning docs exploring contract-driven document generation — turning a contract into an empty-but-valid starting markdown file. This is the architecture/product exploration behind the docs-site reframing in the companion PR (#200); it can land on its own timeline.

It mirrors the existing config-scaffolding pairing (C-0008 capability / D-0009 decision) with the transform reversed:

	Config scaffolding (shipped)	Document scaffolding (this)
Direction	docs → contract (init)	contract → document (new)
Capability	C-0008	C-0011
Decision	D-0009	D-0017

docs/planning/capabilities/C-0011-document-scaffolding.md — product perspective

A markdown-contract new <contract> verb that emits a conforming starting document: required frontmatter keys with starter values, required sections in order, and leaf stubs (table header row, checkbox list, fenced code). Framed as the create door beside validate/read, and the primitive a template engine or a CMS "new document" button would build on — without markdown-contract becoming either.

docs/planning/decisions/D-0017-contract-to-document-generation.md — engineering gap analysis

What it would take to meet the gaps:

• Deterministic from the section grammar: sections, order, nesting/heading depth, anchors, per-leaf block stubs — a straight walk of the same IR the validator traverses.
• Frontmatter splits by authoring path: the declarative (YAML) vocabulary inverts into starter values; arbitrary combinator Zod is best-effort (via z.toJSONSchema()), and .refine()/.transform() are non-invertible.
• The one hard gap — inverting pattern regexes and typed table/list cells — with a proposed optional example:/placeholder: annotation to close it, plus a --fill policy fallback.
• Round-trip-to-valid property (validate(new(contract)) → zero structural findings), mirroring init's accept-by-construction self-check.

Both are status: open/proposed, need_human_review: true, and each ends with an open-questions section. Drafts for review — not a commitment to build the new verb.

Testing

• Built packages/core and ran the dogfood validator over docs/planning: No findings.
• Validated each new doc against contracts/decision.contract.yaml / contracts/capability.contract.yaml directly: 0 findings each (required sections, frontmatter patterns, and the References-cites-a-wikilink rule all pass).

[sksizer]

I also had an idea that we could emit a typed function over the contract, or via the templates wrapper library that provides a typed data structure of the values to fill in ie:

contract defines frontmatter fields like:

let contract = Contract(
front:matter: {
status: <active|closed|pending>
})

then the template.create(contract).( {frontmatter: {status: "closed"}})

And it automatically puts those values in the right place.

[sksizer]

Great idea — captured it in d7afe85. It's the write-dual of typed consumption ([[C-0002-typed-consumption]]): the contract that types doc.frontmatter.status for reading types the values argument for writing.

• C-0011 — new "Typed builder — the write-dual of read" section with your sketch: template.create(contract)({ frontmatter: { status: "closed" } }), where the input type is derived from the contract and create({}) degenerates to the blank skeleton.
• D-0017 — decision step 5: the input type comes from z.input<> / the declarative fields (frontmatter) and the grammar + leaves (body — a table reuses the typed-row shape core/model.ts already derives), the factory places values, and — the nice payoff — a bad enum member or missing required field becomes a compile-time type error instead of a post-hoc "fill me in" finding.

One contract, typed both ways, so a builder can't place a value the validator would reject. Both docs still validate clean.

---

Generated by Claude Code

[cloudflare-workers-and-pages]

Deploying markdown-contract-docs with    Cloudflare Pages

Latest commit:	f3b8e14
Status:	✅  Deploy successful!
Preview URL:	https://82138dd5.markdown-contract-docs.pages.dev
Branch Preview URL:	https://claude-planning-document-sca.markdown-contract-docs.pages.dev

View logs

[sksizer]

if never emits prose, but given that contracts cn test prose content - doesn't this make it impossible to satisfy the poor statement that new rads a contract and writes a document that satisfies it?