improve specification versioning

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

README.md

@@ -28,7 +28,10 @@ The repository is currently in infrastructure setup. Formal project specificatio
 
 Formal specs should be colocated with the code or board package they govern.
 
-- Implementation-linked specs should use versioned sidecar filenames such as `control_loop.v0.1.0.spec.md` next to the related module or package.
+- Implementation-linked specs should use stable sidecar filenames such as `control_loop.spec.md` next to the related module or package.
+- Version history should live inside the same spec file as additional spec entries, not in the filename.
+- Each appended spec entry should begin with version marker such as `# --- version: 0.1.0 ---`.
+- Inside a spec entry, `#` is reserved for version markers and content headings should start at `##`.
 - Rust items should link to those sidecar specs through `#[spec("...")]`.
 - Missing linked spec files must fail compilation.
 
@@ -37,6 +40,6 @@ Example:
 ```rust
 use kaptan_spec::spec;
 
-#[spec("control_loop.v0.1.0.spec.md")]
+#[spec("control_loop.spec.md")]
 pub struct ControlLoop;
 ```

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.

kaptan-spec/src/lib.rs

@@ -20,8 +20,8 @@ fn parse_spec_path(attr: TokenStream) -> Result<String, String> {
         ] if name.to_string() == "path" && is_equals(eq) && is_string_literal(path) => {
             Ok(path.to_string())
         }
-        [] => Err("missing spec path; use #[spec(\"file.v0.1.0.spec.md\")]".into()),
+        [] => Err("missing spec path; use #[spec(\"file.spec.md\")]".into()),
-        _ => Err("invalid spec attribute; use #[spec(\"file.v0.1.0.spec.md\")]".into()),
+        _ => Err("invalid spec attribute; use #[spec(\"file.spec.md\")]".into()),
     }
 }
 

kaptan-spec/tests/ui/fail_missing_sidecar.rs

@@ -1,6 +1,6 @@
 use kaptan_spec::spec;
 
-#[spec("fail_missing_sidecar.v0.1.0.spec.md")]
+#[spec("fail_missing_sidecar.spec.md")]
 struct MissingSpec;
 
 fn main() {

kaptan-spec/tests/ui/fail_missing_sidecar.stderr

@@ -1,5 +1,5 @@
-error: couldn't read `$DIR/tests/ui/fail_missing_sidecar.v0.1.0.spec.md`: No such file or directory (os error 2)
+error: couldn't read `$DIR/tests/ui/fail_missing_sidecar.spec.md`: No such file or directory (os error 2)
  --> tests/ui/fail_missing_sidecar.rs:3:1
   |
-3 | #[spec("fail_missing_sidecar.v0.1.0.spec.md")]
+3 | #[spec("fail_missing_sidecar.spec.md")]
-  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

kaptan-spec/tests/ui/flight_core_contract.rs

@@ -1,6 +1,6 @@
 use kaptan_spec::spec;
 
-#[spec("flight_core_contract.v0.1.0.spec.md")]
+#[spec("flight_core_contract.spec.md")]
 struct FlightCore;
 
 fn main() {

kaptan-spec/tests/ui/flight_core_contract.spec.md

@@ -0,0 +1,25 @@
+# --- version: 0.1.0 ---
+
+---
+title: Flight core contract
+status: in-progress
+owners:
+  - Flight Systems <flight@example.com>
+---
+
+## Contract
+
+Initial control contract.
+
+# --- version: 0.2.0 ---
+
+---
+title: Flight core contract
+status: implemented
+owners:
+  - Flight Systems <flight@example.com>
+---
+
+## Contract
+
+Revised control contract.

kaptan-spec/tests/ui/flight_core_contract.v0.1.0.spec.md

@@ -1,10 +0,0 @@
----
-title: Flight core contract
-status: in-progress
-owners:
-  - Test Name <name@test.com>
----
-
-# Summary
-
-Minimal spec for compile-time linkage testing.