Frontmatter Schemas

Every Contextia artifact is a Markdown file with YAML frontmatter. The frontmatter provides structured metadata that Contextia uses for indexing, linking, validation, and context assembly. This reference documents the complete schema for each artifact type.

General rules

• Frontmatter uses YAML 1.2 syntax, parsed with ruamel.yaml.
• Required fields cause a validation error if missing. The error includes the field name, file path, and expected type.
• Optional fields default to null (not missing keys) when not provided.
• All id fields must be unique within their artifact type.
• All paths fields use paths relative to the project root and support glob patterns.
• List fields accept empty lists [] but not null when they are required.

Note

Contextia validates frontmatter against these schemas when reading artifacts. Invalid frontmatter is reported by contextia check and causes tool errors in the MCP server. Always validate after editing frontmatter by hand.

SpecMeta

Schema for behavioral specification files in .contextia/system/specs/.

---
id: SPEC-001                    # Required. Unique identifier. Pattern: SPEC-\d+
title: User authentication      # Required. Short descriptive title.
description: >-                 # Optional. One-line summary for indexes and search.
  JWT-based login, token refresh, and session validation.
status: approved                # Required. One of: draft, approved, implemented, deprecated.
decisions:                      # Optional. List of decision IDs this spec depends on.
  - DEC-001
  - DEC-002
norms:                          # Optional. List of norm IDs this spec must comply with.
  - NORM-SEC-001
paths:                          # Optional. Source file paths implementing this spec.
  - src/auth/router.py
  - src/auth/service.py
tags:                           # Optional. Free-form tags for search and filtering.
  - authentication
  - security
---

Field reference

Field	Type	Required	Default	Description
id	string	Yes	—	Unique identifier matching pattern SPEC-\d+.
title	string	Yes	—	Human-readable title, used in indexes and context output.
description	string	No	null	One-line summary. Appears in search results and --depth meta output.
status	string	Yes	—	Lifecycle state. Valid values: draft, approved, implemented, deprecated.
decisions	list[string]	No	[]	IDs of decisions this spec references. Used for link-following in context assembly.
norms	list[string]	No	[]	IDs of norms this spec must comply with. Loaded alongside the spec in context.
paths	list[string]	No	[]	Source file paths or glob patterns. Creates top-down links from spec to code.
tags	list[string]	No	[]	Free-form labels for categorization and search.

Status lifecycle

draft  -->  approved  -->  implemented  -->  deprecated

• draft: Under discussion, may change. Agents flag draft specs during implementation.
• approved: Reviewed and accepted as a contract.
• implemented: Code satisfying all behaviors exists and is annotated.
• deprecated: No longer active. Retained for historical reference.

DecisionMeta

Schema for architectural decision records in .contextia/system/rationale/.

---
id: DEC-001                     # Required. Unique identifier. Pattern: DEC-\d+
title: JWT for session tokens   # Required. Short descriptive title.
status: accepted                # Required. One of: proposed, accepted, superseded, deprecated.
date: 2026-01-15                # Optional. Date the decision was made. ISO 8601 format.
superseded_by: DEC-015          # Optional. ID of the decision that replaces this one.
specs:                          # Optional. List of spec IDs this decision supports.
  - SPEC-001
tags:                           # Optional. Free-form tags for search.
  - security
  - authentication
---

Field reference

Field	Type	Required	Default	Description
id	string	Yes	—	Unique identifier matching pattern DEC-\d+.
title	string	Yes	—	Concise description of the decision.
status	string	Yes	—	Current state. Valid values: proposed, accepted, superseded, deprecated.
date	string	No	null	ISO 8601 date when the decision was made (e.g., 2026-01-15).
superseded_by	string	No	null	ID of a newer decision that replaces this one. Set when status changes to superseded.
specs	list[string]	No	[]	IDs of specs this decision relates to. Provides back-references for navigation.
tags	list[string]	No	[]	Free-form labels for search.

Status lifecycle

proposed  -->  accepted  -->  superseded
                          -->  deprecated

• proposed: Under consideration, alternatives being evaluated.
• accepted: Team has agreed on this approach. Implementation proceeds.
• superseded: Replaced by a newer decision. The superseded_by field links to the replacement.
• deprecated: No longer relevant (e.g., the feature was removed).

Tip

When a decision is superseded, keep the original document and set superseded_by. This preserves the historical context of why the original choice was made and why it changed.

NormMeta

Schema for project norms (conventions, standards, rules) in .contextia/system/norms/.

---
id: NORM-SEC-001                # Required. Unique identifier. Pattern: NORM-[A-Z]+-\d+
title: Password handling        # Required. Short descriptive title.
status: active                  # Required. One of: draft, active, deprecated.
paths:                          # Optional. Scope: which source paths this norm applies to.
  - src/auth/**
  - src/core/security.py
tags:                           # Optional. Free-form tags.
  - security
  - passwords
---

Field reference

Field	Type	Required	Default	Description
id	string	Yes	—	Unique identifier. Convention: NORM-{CATEGORY}-\d+ where category is a short label like SEC, API, UI, A11Y.
title	string	Yes	—	Descriptive title of the norm.
status	string	Yes	—	Current state. Valid values: draft, active, deprecated.
paths	list[string]	No	[]	Source paths this norm applies to. When empty, the norm applies project-wide. When specified, contextia check only validates compliance within these paths. Supports glob patterns.
tags	list[string]	No	[]	Free-form labels for search.

Path scoping

The paths field scopes where a norm applies:

# Applies only to API source code
paths:
  - packages/api/src/**

# Applies to all source code (same as omitting paths)
paths: []

# Applies to specific files
paths:
  - src/core/security.py
  - src/auth/password.py

When an agent loads context for a task, norms are included based on whether their paths overlap with the spec’s paths. A norm with paths: [src/auth/**] is included when the task’s spec references files in src/auth/.

TaskMeta

Schema for task (work order) files in .contextia/work/tasks/.

---
id: TASK-001                    # Required. Unique identifier. Pattern: TASK-\d+
title: Implement login endpoint # Required. Short descriptive title.
description: >-                 # Optional. Detailed description of the work.
  Implement the POST /auth/login endpoint per SPEC-001.
status: open                    # Required. One of: open, active, blocked, completed, cancelled.
kind: feature                   # Required. One of: feature, bugfix, refactor, chore, spike.
priority: high                  # Optional. One of: critical, high, medium, low.
specs:                          # Optional. List of spec IDs this task implements or modifies.
  - SPEC-001
depends_on:                     # Optional. List of task IDs that must complete before this one.
  - TASK-000
tags:                           # Optional. Free-form tags.
  - auth
  - mvp
---

Field reference

Field	Type	Required	Default	Description
id	string	Yes	—	Unique identifier matching pattern TASK-\d+.
title	string	Yes	—	Short description of the work item.
description	string	No	null	Longer description with implementation details or requirements.
status	string	Yes	—	Current state. Valid values: open, active, blocked, completed, cancelled.
kind	string	Yes	—	Type of work. Valid values: feature, bugfix, refactor, chore, spike.
priority	string	No	null	Priority level. Valid values: critical, high, medium, low.
specs	list[string]	No	[]	IDs of specs this task relates to. The primary link for context assembly.
depends_on	list[string]	No	[]	IDs of tasks that must be completed before this task can start.
tags	list[string]	No	[]	Free-form labels for search and filtering.

Status lifecycle

open  -->  active  -->  completed
      -->  blocked -->  active
      -->  cancelled

• open: Ready to be picked up. Not yet started.
• active: Currently being worked on. Has an active working directory in work/active/.
• blocked: Cannot proceed due to a dependency or unresolved question.
• completed: Work is done and verified. Working directory archived.
• cancelled: Task was abandoned. Not implemented.

Note

Task status lives in YAML frontmatter and is updated by contextia task activate, contextia task complete, etc. Tasks are never moved between directories to represent status changes.

SessionLogMeta

Schema for session log entries in .contextia/work/active/{task-id}/logs/.

---
task_id: TASK-001               # Required. ID of the associated task.
session_id: ses-20260302-1430   # Required. Unique session identifier.
started_at: 2026-03-02T14:30:00Z  # Required. ISO 8601 timestamp.
ended_at: 2026-03-02T16:45:00Z    # Optional. Set when session is closed.
agent: claude-opus-4-6              # Optional. Identifier of the AI agent.
status: closed                  # Required. One of: active, closed.
---

Field reference

Field	Type	Required	Default	Description
task_id	string	Yes	—	ID of the task this session log belongs to.
session_id	string	Yes	—	Unique identifier for the session. Convention: ses-{date}-{time}.
started_at	string	Yes	—	ISO 8601 timestamp when the session began.
ended_at	string	No	null	ISO 8601 timestamp when the session ended. Set by close: true.
agent	string	No	null	Identifier of the AI agent or tool that created the log.
status	string	Yes	—	Session state. Valid values: active, closed.

Session log body

The body of a session log contains timestamped entries:

## Entries

- **14:30** [progress] Started implementing login endpoint per SPEC-001.
- **14:45** [decision] Used `python-jose` library for JWT operations based on DEC-001.
- **15:20** [progress] Completed authentication service with bcrypt password hashing.
- **15:30** [blocker] SPEC-001 does not specify behavior for locked accounts. Need clarification.
- **16:00** [progress] Added rate limiting per NORM-SEC-001 rule 5.
- **16:45** [summary] Implemented login endpoint. Pending: locked account behavior.

Entry types: progress, decision, blocker, summary, note.

Next steps

• See the Configuration Reference for config.yaml schema.
• Read the Annotation Reference for code annotation syntax.
• Check the Directory Structure for where each artifact type lives.