# 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.spec.md`
- `kaptan-runtime/src/scheduler.rs`
- `kaptan-runtime/src/scheduler.spec.md`

## Compile-Time Linking

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

Example:

```rust
use kaptan_spec::spec;

#[spec("control_loop.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 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:

```markdown
# --- 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:

```text
- 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:

```markdown
# --- 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.