Bump skill↔binary contract version 1->2 so 0.23.0 skills reject a contract-1 binary (#443)

clkao · claude · web-flow · commit ba18936d684f · 2026-06-29T23:05:05.000-07:00
The 0.23.0 skills hard-require binary verbs absent from a contract-1 (v0.22.0)
binary (state ready/commit/sweep, merge guard) but the contract version stayed
1, so an upgrade-skills-not-binary user passed the boot gate (1 ∈ [1,2)) and
broke cryptically on the missing verbs instead of getting the clean
"binary too old — upgrade" abort.

- CONTRACT_VERSION 1 -&gt; 2 (internal/contract/contract.go); the only non-test
  source change — no verb behavior touched.
- Both plugin manifests requires-contract &gt;=1,&lt;2 -&gt; &gt;=2,&lt;3.
- first-officer-shared-core Startup contract-version-gate range text -&gt; &gt;=2,&lt;3
  (byte-neutral: same length, stays 28583).
- Doctor/bracketing fixtures retargeted to keep their verdicts: compatible.json
  and vendored testdata/plugin.json -&gt; &gt;=2,&lt;3; too-old-binary.json -&gt; &gt;=3,&lt;4.
- TestCompatibleUpgradeHint cases pairing CONTRACT_VERSION with the range, the
  gate predicate cases, and the install/decoupling/codex manifest fixtures
  tracked to the new pair.
- New skills/integration AC-1 skew test: the live repo range rejects a contract-1
  binary (too-old-binary) and admits the current CONTRACT_VERSION — divergeable,
  fails if either side is left at 1 / &gt;=1,&lt;2.

Co-authored-by: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -16,7 +16,7 @@
     "automation"
   ],
   "skills": "./skills/",
-  "requires-contract": ">=1,<2",
+  "requires-contract": ">=2,<3",
   "interface": {
     "displayName": "Spacedock",
     "shortDescription": "Plain text workflows for AI agents",
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
@@ -16,7 +16,7 @@
     "automation"
   ],
   "skills": "./skills/",
-  "requires-contract": ">=1,<2",
+  "requires-contract": ">=2,<3",
   "interface": {
     "displayName": "Spacedock",
     "shortDescription": "Plain text workflows for AI agents",
diff --git a/internal/cli/codex_name_match_test.go b/internal/cli/codex_name_match_test.go
@@ -100,7 +100,7 @@ func buildCodexNamedMarketplace(t *testing.T, root, marketplaceName, entryName s
 }
 `)
 	mustWrite(t, filepath.Join(plugin, ".codex-plugin", "plugin.json"),
-		`{ "name": "spacedock", "version": "0.0.0", "requires-contract": ">=1,<2", "skills": "./skills/" }
+		`{ "name": "spacedock", "version": "0.0.0", "requires-contract": ">=2,<3", "skills": "./skills/" }
 `)
 	mustWrite(t, filepath.Join(plugin, "skills", "demo", "SKILL.md"), "---\nname: demo\ndescription: demo skill\n---\ndemo\n")
 	return marketplace
diff --git a/internal/cli/decoupling_behavior_test.go b/internal/cli/decoupling_behavior_test.go
@@ -121,7 +121,7 @@ func buildPluginGitRepo(t *testing.T, root string) string {
 func writePluginVersion(t *testing.T, root, version string) {
 	t.Helper()
 	mustWrite(t, filepath.Join(root, ".claude-plugin", "plugin.json"),
-		fmt.Sprintf(`{ "name": "spacedock", "version": "%s", "requires-contract": ">=1,<2", "skills": "./skills/" }`+"\n", version))
+		fmt.Sprintf(`{ "name": "spacedock", "version": "%s", "requires-contract": ">=2,<3", "skills": "./skills/" }`+"\n", version))
 	mustWrite(t, filepath.Join(root, "skills", "demo", "SKILL.md"),
 		fmt.Sprintf("---\nname: demo\ndescription: demo\n---\nbody v%s\n", version))
 }
diff --git a/internal/cli/frontdoor_test.go b/internal/cli/frontdoor_test.go
@@ -45,7 +45,7 @@ func (f *fakeHost) Install(host, source, branch string) (string, error) {
 }
 
 // compatibleManifest returns a fixture path whose requires-contract brackets
-// CONTRACT_VERSION (the testdata/compatible.json fixture is >=1,<2).
+// CONTRACT_VERSION (the testdata/compatible.json fixture is >=2,<3).
 func compatibleManifest(t *testing.T) string {
 	t.Helper()
 	p, err := filepath.Abs(filepath.Join("..", "contract", "testdata", "compatible.json"))
diff --git a/internal/cli/install_behavior_codex_test.go b/internal/cli/install_behavior_codex_test.go
@@ -184,7 +184,7 @@ func buildCodexMarketplaceAtVersion(t *testing.T, root, version string) string {
 }
 `)
 	mustWrite(t, filepath.Join(plugin, ".codex-plugin", "plugin.json"),
-		`{ "name": "spacedock", "version": "`+version+`", "requires-contract": ">=1,<2", "skills": "./skills/" }
+		`{ "name": "spacedock", "version": "`+version+`", "requires-contract": ">=2,<3", "skills": "./skills/" }
 `)
 	mustWrite(t, filepath.Join(plugin, "skills", "demo", "SKILL.md"), "---\nname: demo\ndescription: demo skill\n---\ndemo\n")
 	return marketplace
diff --git a/internal/cli/install_behavior_test.go b/internal/cli/install_behavior_test.go
@@ -78,7 +78,7 @@ func TestClaudePluginInstallIsHostNative(t *testing.T) {
 
 // buildLocalMarketplace writes a minimal valid local-path marketplace under root
 // and returns the marketplace directory. The plugin manifest carries a
-// requires-contract bracketing CONTRACT_VERSION (>=1,<2).
+// requires-contract bracketing CONTRACT_VERSION (>=2,<3).
 func buildLocalMarketplace(t *testing.T, root string) string {
 	t.Helper()
 	marketplace := filepath.Join(root, "marketplace")
@@ -95,7 +95,7 @@ func buildLocalMarketplace(t *testing.T, root string) string {
   ]
 }
 `)
-	mustWrite(t, filepath.Join(plugin, ".claude-plugin", "plugin.json"), `{ "name": "spacedock", "version": "0.0.0", "requires-contract": ">=1,<2", "skills": "./skills/" }
+	mustWrite(t, filepath.Join(plugin, ".claude-plugin", "plugin.json"), `{ "name": "spacedock", "version": "0.0.0", "requires-contract": ">=2,<3", "skills": "./skills/" }
 `)
 	mustWrite(t, filepath.Join(plugin, "skills", "demo", "SKILL.md"), "---\nname: demo\ndescription: demo skill\n---\ndemo\n")
 	return marketplace
diff --git a/internal/cli/upgrade_from_stale_test.go b/internal/cli/upgrade_from_stale_test.go
@@ -16,7 +16,7 @@ import (
 // installed from a stale marketplace (no requires-contract, the 0.12.1 shape)
 // resolves to the plugin-predates-contract verdict (exit 1, the dead-end the
 // captain hit); running installArgvSequence against an upgraded marketplace
-// (requires-contract >=1,<2) then leaves doctor reporting compatible (exit 0).
+// (requires-contract >=2,<3) then leaves doctor reporting compatible (exit 0).
 // This proves plain `plugin install` no-ops on an already-installed plugin and
 // the inserted `plugin uninstall` is what moves the stale install off. The
 // remove step is tolerated — a fresh `marketplace remove` may exit 1 in some
diff --git a/internal/contract/contract.go b/internal/contract/contract.go
@@ -14,7 +14,7 @@ import (
 // display semver and from the build version. Bump it only when a change to the
 // binary alters the observable surface the FO/ensign contracts call — never as a
 // side effect of a routine release bump (see the entity's OPEN-2 bump discipline).
-const CONTRACT_VERSION = 1
+const CONTRACT_VERSION = 2
 
 // Verdict is the compatibility class produced by comparing a binary's contract
 // version against a plugin's declared requires-contract range.
diff --git a/internal/contract/contract_test.go b/internal/contract/contract_test.go
@@ -106,7 +106,7 @@ func TestCompare(t *testing.T) {
 func TestCompatibleUpgradeHint(t *testing.T) {
 	t.Run("behind-plugin-hints", func(t *testing.T) {
 		for _, host := range []string{"claude", "codex"} {
-			res := Compare(CONTRACT_VERSION, ">=1,<2", host, "0.19.8", "0.20.0")
+			res := Compare(CONTRACT_VERSION, ">=2,<3", host, "0.19.8", "0.20.0")
 			if res.Verdict != Compatible {
 				t.Fatalf("host %s: verdict = %v, want Compatible (the hint must not change the verdict)", host, res.Verdict)
 			}
@@ -124,7 +124,7 @@ func TestCompatibleUpgradeHint(t *testing.T) {
 
 	// Negative: equal versions carry no hint — there is nothing to upgrade to.
 	t.Run("equal-version-no-hint", func(t *testing.T) {
-		res := Compare(CONTRACT_VERSION, ">=1,<2", "claude", "0.20.0", "0.20.0")
+		res := Compare(CONTRACT_VERSION, ">=2,<3", "claude", "0.20.0", "0.20.0")
 		if res.Verdict != Compatible {
 			t.Fatalf("verdict = %v, want Compatible", res.Verdict)
 		}
@@ -136,7 +136,7 @@ func TestCompatibleUpgradeHint(t *testing.T) {
 	// Negative: an unstamped `dev` binary version is not valid semver — the hint
 	// must not fire (no false "you must upgrade" against a dev build).
 	t.Run("dev-binary-no-hint", func(t *testing.T) {
-		res := Compare(CONTRACT_VERSION, ">=1,<2", "claude", "0.19.8", "dev")
+		res := Compare(CONTRACT_VERSION, ">=2,<3", "claude", "0.19.8", "dev")
 		if res.Verdict != Compatible {
 			t.Fatalf("verdict = %v, want Compatible", res.Verdict)
 		}
@@ -148,7 +148,7 @@ func TestCompatibleUpgradeHint(t *testing.T) {
 	// Negative: a binary OLDER than the plugin (but still contract-compatible)
 	// carries no hint — the hint is for a behind plugin, not a behind binary.
 	t.Run("older-binary-no-hint", func(t *testing.T) {
-		res := Compare(CONTRACT_VERSION, ">=1,<2", "claude", "0.21.0", "0.20.0")
+		res := Compare(CONTRACT_VERSION, ">=2,<3", "claude", "0.21.0", "0.20.0")
 		if res.Verdict != Compatible {
 			t.Fatalf("verdict = %v, want Compatible", res.Verdict)
 		}
@@ -162,7 +162,7 @@ func TestCompatibleUpgradeHint(t *testing.T) {
 	// sorts BEFORE "0.9.0" ("1" < "9"), so a lexical-compare regression of
 	// semverCompare would wrongly suppress the hint here. Pins the integer compare.
 	t.Run("behind-plugin-double-digit-minor-hints", func(t *testing.T) {
-		res := Compare(CONTRACT_VERSION, ">=1,<2", "claude", "0.9.0", "0.10.0")
+		res := Compare(CONTRACT_VERSION, ">=2,<3", "claude", "0.9.0", "0.10.0")
 		if res.Verdict != Compatible {
 			t.Fatalf("verdict = %v, want Compatible", res.Verdict)
 		}
@@ -176,7 +176,7 @@ func TestCompatibleUpgradeHint(t *testing.T) {
 	// so a lexical-compare regression would wrongly FIRE the hint on this older
 	// binary. The two boundary cases together RED any lexical compare.
 	t.Run("older-binary-double-digit-minor-no-hint", func(t *testing.T) {
-		res := Compare(CONTRACT_VERSION, ">=1,<2", "claude", "0.10.0", "0.9.0")
+		res := Compare(CONTRACT_VERSION, ">=2,<3", "claude", "0.10.0", "0.9.0")
 		if res.Verdict != Compatible {
 			t.Fatalf("verdict = %v, want Compatible", res.Verdict)
 		}
@@ -189,7 +189,7 @@ func TestCompatibleUpgradeHint(t *testing.T) {
 	// dotted-int semver — the conservative gate emits no hint. Pins that
 	// parseDottedInts rejects a `-rc1` suffix rather than stripping it.
 	t.Run("prerelease-binary-no-hint", func(t *testing.T) {
-		res := Compare(CONTRACT_VERSION, ">=1,<2", "claude", "0.19.8", "0.20.0-rc1")
+		res := Compare(CONTRACT_VERSION, ">=2,<3", "claude", "0.19.8", "0.20.0-rc1")
 		if res.Verdict != Compatible {
 			t.Fatalf("verdict = %v, want Compatible", res.Verdict)
 		}
diff --git a/internal/contract/gate_test.go b/internal/contract/gate_test.go
@@ -27,9 +27,9 @@ func TestStartupGateAbortsBeforeDiscover(t *testing.T) {
 		wantProceed   bool
 		wantPinned    string // abort-message substring (empty when proceeding)
 	}{
-		{"too-old-binary-aborts", "0", ">=1,<2", false, "Upgrade the binary to continue."},
-		{"too-old-plugin-aborts", "5", ">=1,<2", false, "Update the plugin to continue."},
-		{"compatible-proceeds", "1", ">=1,<2", true, ""},
+		{"too-old-binary-aborts", "1", ">=2,<3", false, "Upgrade the binary to continue."},
+		{"too-old-plugin-aborts", "5", ">=2,<3", false, "Update the plugin to continue."},
+		{"compatible-proceeds", "2", ">=2,<3", true, ""},
 	}
 	for _, c := range cases {
 		t.Run(c.name, func(t *testing.T) {
diff --git a/internal/contract/testdata/compatible.json b/internal/contract/testdata/compatible.json
@@ -1,6 +1,6 @@
 {
   "name": "spacedock",
   "version": "0.12.1",
-  "requires-contract": ">=1,<2",
+  "requires-contract": ">=2,<3",
   "skills": "./skills/"
 }
diff --git a/internal/contract/testdata/plugin.json b/internal/contract/testdata/plugin.json
@@ -16,7 +16,7 @@
     "automation"
   ],
   "skills": "./skills/",
-  "requires-contract": ">=1,<2",
+  "requires-contract": ">=2,<3",
   "interface": {
     "displayName": "Spacedock",
     "shortDescription": "Plain text workflows for AI agents",
diff --git a/internal/contract/testdata/too-old-binary.json b/internal/contract/testdata/too-old-binary.json
@@ -1,6 +1,6 @@
 {
   "name": "spacedock",
   "version": "0.13.0",
-  "requires-contract": ">=2,<3",
+  "requires-contract": ">=3,<4",
   "skills": "./skills/"
 }
diff --git a/skills/first-officer/references/first-officer-shared-core.md b/skills/first-officer/references/first-officer-shared-core.md
@@ -6,7 +6,7 @@ Shared first-officer semantics — the boot-resident core. The dispatch and merg
 
 **Launcher command invariant:** Resolve ONE launcher at the version gate — `SPACEDOCK_BIN` when set/executable, else `spacedock` on `$PATH` — report its path/version, and use THAT launcher (written `${SPACEDOCK_BIN:-spacedock}`) for every later Spacedock helper call. Never drift to a bare `spacedock` mid-session — a different `$PATH` binary shifts the command surface. Bare `spacedock` is fine only for naming a command (prose, `→` binding lines), the fallback probe, and diagnostic/install hints — never a post-gate helper invocation.
 
-1. **Contract version gate.** Before discovery or boot read, run `${SPACEDOCK_BIN:-spacedock} --version` and parse `contract <N>`. Confirm `<N>` satisfies this contract's range `>=1,<2`. Abort by class:
+1. **Contract version gate.** Before discovery or boot read, run `${SPACEDOCK_BIN:-spacedock} --version` and parse `contract <N>`. Confirm `<N>` satisfies this contract's range `>=2,<3`. Abort by class:
    - **Binary absent or non-executable** — `${SPACEDOCK_BIN:-spacedock} --version` is not found or emits no parseable `contract <N>` token. If `SPACEDOCK_BIN` is unusable, retry once with bare `spacedock` on `$PATH`; if still absent, ABORT and tell the operator `spacedock` is not on PATH. Install hint: `brew install spacedock-dev/homebrew-tap/spacedock`, or source build `go build -o spacedock ./cmd/spacedock`. Do NOT run `spacedock doctor` — the binary is missing. Once spacedock is on PATH, launch with `spacedock claude` to start your first officer.
    - **Binary present but contract out of range** — `<N>` is below the lower bound (binary too old) or at/above the upper bound (plugin too old). ABORT with the mismatch message and run `${SPACEDOCK_BIN:-spacedock} doctor` for the per-class remedy.
 
diff --git a/skills/integration/contract_skew_test.go b/skills/integration/contract_skew_test.go
@@ -0,0 +1,56 @@
+// ABOUTME: AC-1 skew test — the live repo manifest range rejects a contract-1
+// ABOUTME: binary (the published v0.22.0) and admits the current CONTRACT_VERSION.
+package integration
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/spacedock-dev/spacedock/internal/contract"
+)
+
+// liveRequiresContract reads the requires-contract range declared by the named
+// repo plugin manifest (".claude-plugin" or ".codex-plugin").
+func liveRequiresContract(t *testing.T, pluginDir string) string {
+	t.Helper()
+	path := filepath.Join(repoRoot(t), pluginDir, "plugin.json")
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read %s: %v", path, err)
+	}
+	var m struct {
+		RequiresContract string `json:"requires-contract"`
+	}
+	if err := json.Unmarshal(data, &m); err != nil {
+		t.Fatalf("parse %s: %v", path, err)
+	}
+	return m.RequiresContract
+}
+
+// TestContract1BinaryRejectedByLiveRange locks AC-1: a contract-1 binary (the
+// published v0.22.0, which reports `contract 1`) is REJECTED by the live skill
+// range with the too-old-binary verdict, while the current binary's
+// CONTRACT_VERSION is admitted as compatible. Both plugin manifests are exercised
+// so the Claude and Codex ranges agree. The test reads the live range and the
+// live CONTRACT_VERSION — leaving either side at contract 1 / `>=1,<2` makes the
+// contract-1 case Compatible and fails here.
+func TestContract1BinaryRejectedByLiveRange(t *testing.T) {
+	const contract1 = 1 // the published v0.22.0 binary's reported contract
+	for _, pluginDir := range []string{".claude-plugin", ".codex-plugin"} {
+		raw := liveRequiresContract(t, pluginDir)
+
+		stale := contract.Compare(contract1, raw, "claude", "0.22.0", "0.23.0")
+		if stale.Verdict != contract.TooOldBinary {
+			t.Fatalf("%s range %q: contract-1 binary verdict = %v, want too-old-binary (a contract-1 v0.22.0 binary must be rejected)",
+				pluginDir, raw, stale.Verdict)
+		}
+
+		current := contract.Compare(contract.CONTRACT_VERSION, raw, "claude", "0.23.0", "0.23.0")
+		if current.Verdict != contract.Compatible {
+			t.Fatalf("%s range %q: current CONTRACT_VERSION=%d verdict = %v, want compatible",
+				pluginDir, raw, contract.CONTRACT_VERSION, current.Verdict)
+		}
+	}
+}

Original file line number	Diff line number	Diff line change
`@@ -100,7 +100,7 @@ func buildCodexNamedMarketplace(t *testing.T, root, marketplaceName, entryName s`
`100`	`100`	`}`
`101`	`101`	`)
`102`	`102`	`mustWrite(t, filepath.Join(plugin, ".codex-plugin", "plugin.json"),`
`103`		- `{ "name": "spacedock", "version": "0.0.0", "requires-contract": ">=1,<2", "skills": "./skills/" }
	`103`	+ `{ "name": "spacedock", "version": "0.0.0", "requires-contract": ">=2,<3", "skills": "./skills/" }
`104`	`104`	`)
`105`	`105`	`mustWrite(t, filepath.Join(plugin, "skills", "demo", "SKILL.md"), "---\nname: demo\ndescription: demo skill\n---\ndemo\n")`
`106`	`106`	`return marketplace`
Original file line number	Diff line number	Diff line change
`@@ -121,7 +121,7 @@ func buildPluginGitRepo(t *testing.T, root string) string {`
`121`	`121`	`func writePluginVersion(t *testing.T, root, version string) {`
`122`	`122`	`t.Helper()`
`123`	`123`	`mustWrite(t, filepath.Join(root, ".claude-plugin", "plugin.json"),`
`124`		- fmt.Sprintf(`{ "name": "spacedock", "version": "%s", "requires-contract": ">=1,<2", "skills": "./skills/" }`+"\n", version))
	`124`	+ fmt.Sprintf(`{ "name": "spacedock", "version": "%s", "requires-contract": ">=2,<3", "skills": "./skills/" }`+"\n", version))
`125`	`125`	`mustWrite(t, filepath.Join(root, "skills", "demo", "SKILL.md"),`
`126`	`126`	`fmt.Sprintf("---\nname: demo\ndescription: demo\n---\nbody v%s\n", version))`
`127`	`127`	`}`
Original file line number	Diff line number	Diff line change
`@@ -45,7 +45,7 @@ func (f *fakeHost) Install(host, source, branch string) (string, error) {`
`45`	`45`	`}`
`46`	`46`
`47`	`47`	`// compatibleManifest returns a fixture path whose requires-contract brackets`
`48`		`-// CONTRACT_VERSION (the testdata/compatible.json fixture is >=1,<2).`
	`48`	`+// CONTRACT_VERSION (the testdata/compatible.json fixture is >=2,<3).`
`49`	`49`	`func compatibleManifest(t *testing.T) string {`
`50`	`50`	`t.Helper()`
`51`	`51`	`p, err := filepath.Abs(filepath.Join("..", "contract", "testdata", "compatible.json"))`
Original file line number	Diff line number	Diff line change
`@@ -184,7 +184,7 @@ func buildCodexMarketplaceAtVersion(t *testing.T, root, version string) string {`
`184`	`184`	`}`
`185`	`185`	`)
`186`	`186`	`mustWrite(t, filepath.Join(plugin, ".codex-plugin", "plugin.json"),`
`187`		- `{ "name": "spacedock", "version": "`+version+`", "requires-contract": ">=1,<2", "skills": "./skills/" }
	`187`	+ `{ "name": "spacedock", "version": "`+version+`", "requires-contract": ">=2,<3", "skills": "./skills/" }
`188`	`188`	`)
`189`	`189`	`mustWrite(t, filepath.Join(plugin, "skills", "demo", "SKILL.md"), "---\nname: demo\ndescription: demo skill\n---\ndemo\n")`
`190`	`190`	`return marketplace`