Frontmatter fields

Every artifact Groundwork writes is a Markdown file whose YAML frontmatter is validated against a JSON Schema. These tables are generated from those two schemas, so a field that exists in the schema appears here and a field that does not, does not.

The structural validators — validate_requirements.py and validate_design.py — check each artifact’s frontmatter against these schemas. They enforce more besides: rules that hold across a whole set rather than within one file — global ID uniqueness, agreement between an ID’s prefix and its type, traces_from references that resolve, the required headings in assumptions.md, glossary.md and drivers.md, and MADR 4.0 headings in an ADR body — none of which a per-field table can show. And they enforce less than this when jsonschema is not installed: the stdlib fallback checks a hand-listed subset of required fields and enums, not the schema. See Gates for the set-level checks and for what happens when one fails, and Reading an artifact for what the fields mean in practice rather than in schema terms.

Requirement fields

Required by validate_requirements.py over .sdlc/requirements.

Field	Type	Required	Values	Meaning
`id`	string	always	—	Categorical, zero-padded, stable ID. Prefix encodes type: FR->functional, NFR->non_functional, CON->constraint, BR->business_rule, UC->use_case. An optional uppercase category infix is allowed (e.g. FR-ORDER-014).
`type`	string	always	`functional` `non_functional` `constraint` `business_rule` `use_case`	Requirement category.
`tier`	string	always	`business` `stakeholder` `solution` `transition`	BABOK v3 four-tier hierarchy level.
`title`	string	always	—	Short human-readable title (matches the kebab-case used in the filename).
`description`	string	always	—	For functional requirements: an EARS-phrased statement. For NFRs/constraints/etc.: a clear single statement of the requirement.
`rationale`	string	always	—	Volere mandatory rationale: the WHY behind this requirement.
`fit_criterion`	string	always	—	Volere mandatory fit criterion: a measurable test oracle for the requirement.
`priority`	string	always	`must` `should` `could` `wont`	MoSCoW priority.
`confidence`	string	always	`high` `medium` `low`	Confidence level for human-in-the-loop triage.
`verification_method`	string	always	`test` `inspection` `analysis` `demonstration`	How the requirement is verified.
`ears_pattern`	string	functional	`ubiquitous` `event` `state` `unwanted` `optional` `complex`	EARS sentence pattern. Required for functional requirements only; omitted for other types.
`status`	string	always	`draft` `reviewed` `approved` `implemented` `verified` `obsolete`	Lifecycle status. IDs are never re-used; set status to obsolete instead of deleting.
`created_at`	string	always	—	Creation date in YYYY-MM-DD format.
`traces_from`	array	always	—	Upstream traceability: IDs of higher-tier requirements this one derives from. May be empty for top-tier (business) requirements.
`traces_to`	object	always	—	Downstream traceability mapping to design, tests, and code artifacts. Any of the three keys may be omitted or empty.
`scope`	string	optional	`project` `epic` `story`	RESERVED (STO-98/agile). Agile planning scope. Present-but-optional.
`parent_scope`	string \| null	optional	—	RESERVED. Parent scope ID, or null. Present-but-optional.

Design fields

Required by validate_design.py over .sdlc/design.

Field	Type	Required	Values	Meaning
`id`	string	always	—	Categorical, zero-padded, stable ID. Prefix encodes type: CMP->component, IF->interface, ADR->adr, DIA->diagram. An optional uppercase category infix is allowed (e.g. CMP-AUTH-004).
`type`	string	always	`component` `interface` `adr` `diagram`	Design-artifact category.
`title`	string	always	—	Short human-readable title (matches the kebab-case used in the filename).
`description`	string	always	—	One clear statement of what this element is.
`traces_from`	array	always	—	Upstream traceability: requirement IDs (FR-/NFR-/CON-/BR-/UC-) this element satisfies. May be empty. Existence is resolved by the cross-artifact validator (STO-102), not this schema.
`traces_to`	object	always	—	Downstream traceability to ADRs, diagrams, code, and tests. Any key may be omitted or empty.
`status`	string	always	`draft` `reviewed` `approved` `implemented` `verified` `obsolete`	Lifecycle status. IDs are never re-used; set status to obsolete instead of deleting.
`confidence`	string	always	`high` `medium` `low`	Confidence level for human-in-the-loop triage (STO-138).
`created_at`	string	always	—	Creation date in YYYY-MM-DD format.
`scope`	string	optional	`project` `epic` `story`	RESERVED (agile planning scope). Present-but-optional; mirrors the requirement schema.
`parent_scope`	string \| null	optional	—	RESERVED. Parent scope ID, or null. Present-but-optional.
`responsibility`	string	component	—	The single clear purpose of the unit.
`boundary`	string	component	`internal` `external`	Whether the unit is inside the system boundary or an external system modelled as a component (C4).
`depends_on`	array	component	—	The interface contracts this component consumes. IF- IDs only; may be empty. Existence is resolved by the design validator.
`provider`	string	interface	—	The single component that provides this contract. Exactly one CMP- ID.
`operations`	array	interface	—	The operations this contract exposes, at architecture altitude (name + summary + interaction; no payload schemas).
`error_modes`	array	interface	—	How this contract can fail. An interface that does not say how it fails is a gap; at least one mode is required.
`decision_status`	string	adr	`proposed` `rejected` `accepted` `deprecated` `superseded`	MADR decision status. Distinct from `status`, which is the artifact lifecycle.
`considered_options`	array	optional	—	The options weighed. Never fabricated: when a second option cannot be recovered from the recorded decision, no ADR is emitted at all.
`chosen_option`	string	optional	—	The option taken. Absent while the decision is still proposed.
`level`	string	diagram	`context` `container` `component`	C4 level. Determines the Mermaid header directive: context->C4Context, container->C4Container, component->C4Component.
`container`	string	optional	—	The container key whose internals this view depicts. Present only on level: component.

Reading the Required column

always means every artifact of that stage carries the field. A list of type names means the field is required only for those types — ears_pattern is required for functional requirements and meaningless for the rest. optional means the schema permits it and never demands it.