Add versioning contract: semver policy, breaking change sections, schema_version guard

- CHANGELOG: add ### Breaking Changes section to all versions (None for 1.1–1.3)
- README: add Versioning section with semver table and floating tag explanation
- schema/config-schema.json: add schema_version field (const: 1, optional)
- lib/config.sh: fail fast if schema_version is present and unsupported

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 1.3.0
 
+### Breaking Changes
+
+_None._
+
 ### Features
 
 - **Linearize fallback for reverse sync**: When josh-proxy rejects a push due to unmappable merge commits, reverse sync automatically falls back to linearizing the history — cherry-picking regular commits individually and squashing only the problematic merge commits via `cherry-pick -m 1`. Preserves individual commit granularity while handling complex merge topologies that josh cannot map. PR body notes when linearization was used.
@@ -19,6 +23,10 @@
 
 ## 1.2.0
 
+### Breaking Changes
+
+_None._
+
 ### Features
 
 - **File exclusion**: `exclude` config field removes files/directories from the subrepo at the josh-proxy transport layer. Patterns are embedded inline in the josh-proxy URL using `:exclude[::pattern,...]` syntax — no extra files to generate or commit.
@@ -38,6 +46,10 @@
 
 ## 1.1.0
 
+### Breaking Changes
+
+_None._
+
 ### Features
 
 - **`onboard` command**: Interactive, resumable workflow for importing existing subrepos into the monorepo. Walks through: prerequisites check, import (creates PRs), wait for merge, reset (pushes josh-filtered history). Checkpoint/resume at every step.

README.md

@@ -63,6 +63,18 @@ Run `josh-sync preflight` to validate your setup.
 - **[Architecture Decision Records](docs/adr/)** — Design rationale and trade-offs
 - **[Changelog](CHANGELOG.md)** — Version history
 
+## Versioning
+
+josh-sync follows [semver](https://semver.org/):
+
+| Bump | Meaning | Action required |
+|------|---------|-----------------|
+| **Patch** (1.x.**y**) | Bug fixes only | Safe to upgrade |
+| **Minor** (1.**y**.0) | New optional config fields, new commands, new action inputs | Safe to upgrade; new features are opt-in |
+| **Major** (**y**.0.0) | Removed or renamed config fields, CLI flags, action inputs, env vars, or state format | Read the **Breaking Changes** section in the changelog before upgrading |
+
+CI workflows pin to a floating major tag (e.g. `@v1`). A breaking change bumps the major version and moves the tag — `@v1` workflows keep working until you explicitly update to `@v2`.
+
 ## CLI
 
 ```

lib/config.sh

@@ -16,6 +16,11 @@ parse_config() {
   local config_json
   config_json=$(yq -o json "$config_file") || die "Failed to parse ${config_file}"
 
+  # Schema version check (optional field — absent means v1)
+  local schema_version
+  schema_version=$(echo "$config_json" | jq -r '.schema_version // 1')
+  [ "$schema_version" = "1" ] || die "Unsupported schema_version ${schema_version} in ${config_file} (this version of josh-sync supports schema_version 1 — see CHANGELOG.md for migration instructions)"
+
   # Export global values
   export JOSH_PROXY_URL
   JOSH_PROXY_URL=$(echo "$config_json" | jq -r '.josh.proxy_url')

schema/config-schema.json

@@ -5,6 +5,11 @@
   "type": "object",
   "required": ["josh", "targets", "bot"],
   "properties": {
+    "schema_version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Schema version. Bump when config fields are removed or renamed (matches josh-sync major version)."
+    },
     "josh": {
       "type": "object",
       "required": ["proxy_url", "monorepo_path"],