kaptan/SPECIFICATIONS.md

Specifications

Formal Kaptan specifications live next to the file-backed module they govern.

Examples:

• kaptan-runtime/src/runtime.rs
• kaptan-runtime/src/runtime.spec.md
• kaptan-runtime/src/scheduler.rs
• kaptan-runtime/src/scheduler.spec.md

Automatic Sidecar Checks

Kaptan build checks require a same-name .spec.md sidecar for every file-backed Rust module under a checked crate's src/ tree.

For example, control_loop.rs requires control_loop.spec.md in the same directory. A checked module must have exactly one of:

• its sidecar specification; or
• a top-level no_spec!("reason"); declaration.

no_spec! is only for module files that intentionally have no formal specification, such as a crate root that only declares child modules. It must provide a non-empty reason and must not be used for types, functions, or individual items.

Example for a crate root without standalone runtime behavior:

use kaptan_spec::no_spec;

no_spec!("Crate root declares child modules only.");

The build fails if a required sidecar is missing or a module contains both a sidecar and no_spec!(...).

Spec Format

Formal spec files are append-only records for one governed module or package.

Each file may contain one or more spec entries. Each entry starts with a version heading, followed by YAML frontmatter and a Markdown body.

Use this exact heading form for each entry:

# --- version: 0.1.0 ---

Each spec entry must then 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 spec file path identifies the governed module or package.
• Individual spec revisions are identified by the version heading.
• A single spec file can carry multiple revisions for the same governed module.
• New revisions should be appended as new spec entries in the same file instead of creating new filenames.
• Within the body of a spec entry, # is reserved for version headings. Spec content should start at ## and below.

Template

Use this starter when creating a colocated spec entry:

# --- version: 0.1.0 ---

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

## TODO

When the spec evolves, append another entry in the same shape with a new version heading.