improve specification versioning

Signed-off-by: Onur Özkan <work@onurozkan.dev>

SPECIFICATIONS.md

@@ -5,9 +5,9 @@ Formal Kaptan specifications should normally live next to the code item they gov
 Examples:
 
 - `kaptan-runtime/src/control_loop.rs`
-- `kaptan-runtime/src/control_loop.v0.1.0.spec.md`
+- `kaptan-runtime/src/control_loop.spec.md`
 - `kaptan-runtime/src/scheduler.rs`
-- `kaptan-runtime/src/scheduler.v0.1.0.spec.md`
+- `kaptan-runtime/src/scheduler.spec.md`
 
 ## Compile-Time Linking
 
@@ -18,7 +18,7 @@ Example:
 ```rust
 use kaptan_spec::spec;
 
-#[spec("control_loop.v0.1.0.spec.md")]
+#[spec("control_loop.spec.md")]
 pub struct ControlLoop;
 ```
 
@@ -26,7 +26,17 @@ The attribute expands to a compile-time file inclusion guard. If the linked file
 
 ## Spec Format
 
-Formal specs are expected to declare these keys in YAML frontmatter:
+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`
@@ -47,19 +57,27 @@ Owner entries must use full name and email address in this format:
 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.
+- 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 new colocated spec:
+Use this starter when creating a colocated spec entry:
 
 ```markdown
+# --- version: 0.1.0 ---
+
 ---
 title: Replace with title
-status: in-progress
+status: deprecated
 owners:
   - Full Name <name@example.com>
 ---
 
-# TODO
-```
+## TODO
+```
+
+When the spec evolves, append another entry in the same shape with a new version heading.