Get Started
In this section
Back to reference

7. Frontmatter System

aDNA Specification v2.5 Section 7 of 20 Full text

Scan: Required base fields (type, status, created, updated, last_edited_by, tags), tag conventions, priority field, type-specific extensions.

Decisions: C4, D18, D20

7.1 Scope

YAML frontmatter MUST be present on all aDNA content files — files inside the triad (what/, how/, who/ or .agentic/what/, etc.) and root governance files.

Project content files (source code, external documentation) outside the triad are exempt from frontmatter requirements.

7.2 Required Base Fields

Every aDNA content file MUST include these frontmatter fields:

---
type: <entity_type>
status: <lifecycle_status>
created: YYYY-MM-DD
updated: YYYY-MM-DD
last_edited_by: agent_<username> | <username>
tags: []
---
FieldPurpose
typeEntity classification (e.g., session, mission, customer, context_research)
statusLifecycle state (e.g., active, completed, draft, abandoned) — entity-specific values
createdDate of file creation
updatedDate of last modification — critical for collision prevention
last_edited_byAttribution — who or what last modified this file
tagsCategorization array for filtering and discovery

Per-class profile (v2.5, ADR-044): the six base fields are required for content and session entities. status is optional for type: directory_index and type: coordination — an index or correspondence record has no lifecycle state, and their canonical templates omit it. The other five base fields remain required for all classes.

7.3 Tag Conventions

Tags MUST use lowercase with underscores (e.g., mission, context_research).

Every aDNA content file MUST have at least one tag (the type tag is sufficient).

No formal tag registry is prescribed. Projects SHOULD document their tag conventions in AGENTS.md files when the tag set exceeds a dozen unique tags.

7.4 Priority Field

Content items that need prioritization (tasks, backlog ideas, customers) MAY include a priority field using a simple numeric scale: 0 (highest) through N (lowest).

Rule/guardrail conflict resolution is a separate concern. Projects that need rule precedence SHOULD define their own mechanism in CLAUDE.md or governance files.

7.5 Type-Specific Fields

Templates (§12) define additional frontmatter fields per content type. For example, a session template adds session_id, plan_id (legacy field name), tier; a customer template adds segment, deal_stage, contacts.

Frontmatter is the integration layer between human tools (Dataview queries, IDE search) and agent queries. Consistent frontmatter enables consistent querying across any tool.

7.6 Frontmatter Extension Policy

Instance-specific frontmatter fields MAY be added to any entity type. The following rules govern extensions:

  1. Custom fields MAY be added freely to any content file’s frontmatter
  2. Custom fields SHOULD use a project-specific prefix (e.g., bio_target_class, crm_deal_stage) when the field name could conflict with future standard fields
  3. Standard fields (those defined in §7.2 and per-type templates) MUST NOT be repurposed to carry different semantics
  4. Migration tools MUST preserve custom fields — standard version upgrades MUST NOT strip unrecognized frontmatter fields
  5. Projects SHOULD document their custom fields in the relevant AGENTS.md or template files

7.7 Decision-Record Ratification Discipline

Decision records (ADRs, what/decisions/) carry a lifecycle status whose advancement beyond proposed is a human act. Effective v2.5 (ADR-046, folding the discipline installed after an agent thread self-marked an ADR accepted without an operator gate):

  1. Agents author; operators ratify. An agent MAY fully author an ADR — context, decision, consequences, alternatives, references — and MAY set or keep status: proposed (or draft). An agent MUST NOT set accepted, ratified, or rejected; those transitions require an operator gate.
  2. Ratification record. Any ADR moving beyond proposed MUST carry a structured ratification block with all four fields present and non-empty:
    • Ratifier — the named human operator/authority. An agent or persona may be named only as author/steward, never as ratifier.
    • Gate / reference — a verifiable pointer to the discrete ratification event: the gate file and/or its output record, the ratifying session id, and/or the ratifying commit.
    • Ratification date — distinct from the authored/created date.
    • Scope of authority — exactly what the ratification authorizes, plus any pending co-signs that keep seams non-operative.
  3. Retroactivity. ADRs accepted before v2.5 SHOULD be backfilled with ratification blocks; a pre-v2.5 accepted ADR without one is NOT thereby non-conformant. (This clause is what keeps the v2.5 cut a minor version under §15.4.)
  4. Batch ceremonies. An N-ADRs-at-once ratification ceremony MAY substitute a single ceremony record for per-ADR gate references, provided each covered ADR’s block points to it.
  5. Validation. Conformance tooling SHOULD check structure only — the four fields present and non-empty — never the truth of the gate; truth is the operator’s, at the gate. Recommended rollout: warn first, promote to fail after a backfill pass.
  6. Exemption. Lifecycle-neutral back-references (e.g., adding superseded_by once the superseding ADR is itself ratified) are exempt from rule 1.