kaptan/SPECIFICATIONS.md

Specifications

Formal Kaptan specifications should normally live next to the code item they govern.

Examples:

• kaptan-runtime/src/control_loop.rs
• kaptan-runtime/src/control_loop.v0.1.0.spec.md
• kaptan-runtime/src/scheduler.rs
• kaptan-runtime/src/scheduler.v0.1.0.spec.md

Compile-Time Linking

Code implementations should link to their governing spec through #[spec("...")].

Example:

use kaptan_spec::spec;

#[spec("control_loop.v0.1.0.spec.md")]
pub struct ControlLoop;

The attribute expands to a compile-time file inclusion guard. If the linked file does not exist, compilation fails.

Spec Format

Formal specs are expected to declare these keys in YAML frontmatter:

• title
• status
• owners

Allowed statuses are:

• in-progress
• implemented
• deprecated

Owner entries must use full name and email address in this format:

- Full Name <name@example.com>

The spec path is the identifier for linkage and traceability.

• The code path plus the #[spec("...")] reference identifies the governing spec.
• The version is part of the spec filename and therefore part of the spec identity.

Template

Use this starter when creating a new colocated spec:

---
title: Replace with title
status: in-progress
owners:
  - Full Name <name@example.com>
---

# TODO