From 099644a47131f651df257ff59b68673c799deb92 Mon Sep 17 00:00:00 2001
From: JarbasAi <jarbasai@mailfence.com>
Date: Sun, 24 May 2026 04:33:02 +0100
Subject: [PATCH] docs: document the draft-stage versioning rule

While a spec is in Draft, the Version field doubles as a
compatibility signal with current OVOS:

- v1 = drop-in compatible
- v2 = incompatible (requires OVOS-side changes)

Compatible changes during draft fold into the current version
rather than bumping. Only incompatible features bump.

The rule applies only while a spec is in Draft; once promoted
out of Draft, every normative change bumps the version per the
standard rule.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md | 11 ++++++++---
 README.md    | 33 +++++++++++++++++++++++++++++----
 2 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c9625fa..80c629b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,9 +1,14 @@
 # Changelog
 
 Each entry records a versioned change to a specification in this repository.
-Each specification is versioned independently, starting at version 1. Every
-pull request that alters normative content bumps the affected spec's `Version`
-field and adds an entry here.
+Each specification is versioned independently, starting at version 1.
+
+Every pull request that alters normative content adds an entry here. The
+version field is bumped per the standard rule (one PR, one bump) **unless**
+the spec is in **Draft** status, in which case the
+[draft-stage versioning rule](README.md#draft-stage-versioning) applies:
+compatible changes fold into the current version; only incompatible features
+bump.
 
 ## OVOS-INTENT-1 — Sentence Template Grammar
 
diff --git a/README.md b/README.md
index 74749e3..8964b51 100644
--- a/README.md
+++ b/README.md
@@ -105,10 +105,10 @@ Specifications are **versioned documents, not living wikis**. Any
 change to a spec — however small — **MUST** be submitted as a pull
 request, never committed directly.
 
-Each PR that alters normative content **MUST**:
-
-- bump the spec's `Version` field in its header;
-- add a corresponding entry to [CHANGELOG.md](CHANGELOG.md).
+Each PR that alters normative content **MUST** add a
+corresponding entry to [CHANGELOG.md](CHANGELOG.md) and, **unless
+the draft-stage rule below applies**, bump the spec's `Version`
+field in its header.
 
 A version identifies an exact, citable state of a document, so
 implementations and conformance results can name the version they
@@ -118,6 +118,31 @@ PRs that touch only the non-normative material —
 [APPENDIX.md](APPENDIX.md), [GLOSSARY.md](GLOSSARY.md), this
 README, examples — do not require a version bump.
 
+### Draft-stage versioning
+
+While a specification carries **Status: Draft**, the `Version`
+field also doubles as a **compatibility signal** with current
+OVOS:
+
+- **v1** — drop-in compatible with current OVOS. A conforming
+  implementation runs against today's OVOS unchanged.
+- **v2** — incompatible: requires OVOS-side changes (renamed
+  topics, new orchestrator responsibilities, payload-shape
+  changes, etc.).
+
+PRs in draft therefore follow a refined rule:
+
+- A PR that adds, refines, or loosens content **without** breaking
+  compatibility with current OVOS **MAY** keep the spec at its
+  current version (typically v1) and fold the change into that
+  version's CHANGELOG entry.
+- A PR that introduces an incompatible feature **MUST** bump the
+  spec to v2 (or the next major).
+
+The rule applies only while the spec is in **Draft** status; once
+a spec is promoted out of Draft, every normative change bumps the
+version per the standard rule above.
+
 ---
 
 ## Credits