charter-format

name	charter-format
description	The normative Charter `.charter.md` block catalog and `:::question` open/resolved schema — the single format source of truth cited by the charter authoring skill (to WRITE blocks) and by Guardrails plan-breakdown (to INTERPRET them). Use whenever you must read, write, or interpret Charter `:::` directive blocks.
format-version	1
format-min	1

charter-format — the normative Charter block catalog

A Charter deliverable is a .charter.md file: CommonMark prose plus ::: directive containers (Markdig custom containers), each validated against a C# record in Charter.Core. This skill is the single source of truth for that format — the block catalog, each block's semantics, and the :::question open/resolved rule. It is bound to the renderer by a drift test (Charter.Core.Tests), so this catalog and the real BlockKind set / QuestionSpec fields can never silently diverge.

Do not invent, fork, or vendor this catalog. Cite this skill.

Format version

This skill declares the format range it understands in its frontmatter:

• format-version: 1 — the newest catalog version this skill defines (skillMax).
• format-min: 1 — the oldest file format it still understands (skillMin).

A .charter.md stamps the format it was authored against in a plain-YAML frontmatter marker (charter-format-version: F, readable without this skill). It is consumable iff format-min ≤ F ≤ format-version. Any change to the catalog below bumps format-version — the drift test binds the version to the code, so a semantic change with no bump fails the build.

The block catalog (the only blocks that exist)

Primitives are plain CommonMark. The ::: directives are the rich, validated blocks.

Block	Syntax	Semantics
prose / heading / list / table / code	plain CommonMark	Narrative and data. Annotatable (a whole block, or a text range inside it; a code block per line).
note callout	:::note	An aside. Rendered as a callout; annotatable as a whole element.
warn callout	:::warn	A risk the reviewer must not miss. A callout; annotatable as a whole element.
comparison	:::comparison	Options weighed side by side — a pipe table or list body. Annotatable per row.
diagram	:::diagram	A Mermaid diagram (Mermaid source as the body). Rendered theme-aware; annotatable per node.
diff	:::diff	A unified diff. Annotatable per line (add / remove / context).
custom HTML	:::custom-html	The sanctioned raw-HTML escape hatch — its body is passed through live (every other surface escapes raw HTML). Reach for it last.
question	:::question	The elicitation block — asks the human (or downstream agent) to decide something inside the plan. Validated JSON body; see below.

There is no :::file-tree and no :::annotated-code. They have no renderer — do not author them, and treat any other unknown :::foo as an unknown directive, never as a known block.

The :::question block — open vs. resolved

The body is a JSON object (JSON is a subset of YAML, so the parser stays dependency-agnostic) validated to QuestionSpec in Charter.Core. Its fields:

Field	Type	Required	Meaning
id	string	yes	Stable, document-unique question id. (Two questions sharing an id is a review-time error — an answer would resolve into both.)
title	string	yes	The question shown to the reviewer.
mode	string	yes	One of single / multi / free-text / bool / number.
options	array of strings	for single/multi	The choices. Required and non-empty for the select modes; unused otherwise.
target	string	yes	human or agent — who the resolved answer routes to.
answer	array of strings	no	The open/resolved marker. Absent or empty ⇒ the question is open. Non-empty ⇒ resolved, carrying the chosen value(s).

The answer shape mirrors a submitted answer's values: a single/bool/number answer is one element, a multi answer is the selected values, and free-text is the text as one element.

Open (as authored):

:::question
{ "id": "db-choice", "title": "Which datastore for the read path?",
  "mode": "single", "options": ["Postgres", "DynamoDB"], "target": "human" }
:::

Resolved (the answer key is added on drain — every other key is preserved):

:::question
{ "id": "db-choice", "title": "Which datastore for the read path?",
  "mode": "single", "options": ["Postgres", "DynamoDB"], "target": "human", "answer": ["Postgres"] }
:::

Interpreting a question: a resolved question is a settled decision — fold its answer in, keeping the options as rationale. An open question must be surfaced, never silently defaulted.