Replace the contract-integer compatibility gate with minor-version coupling (#468)

* Replace the contract-integer compatibility gate with minor-version coupling

Removes CONTRACT_VERSION, ParseRange, and the integer Compare math from
internal/contract in favor of a minor-exact major.minor compare over the
binary's own display version and the plugin manifest's version field — the
existing release stamps already couple both sides, so the floor now moves on
every release with zero hand-maintained integer to forget.

- internal/contract: new ParseMajorMinor + Compare(host, pluginVersion,
  binaryVersion); PluginPredatesContract folds into TooOldPlugin;
  MalformedRange renames to MalformedVersion.
- D3: the module root embeds .claude-plugin/plugin.json so an unstamped dev
  build reports <checkout-version>+dev instead of the bare `dev` sentinel,
  closing the always-pass carve-out.
- D4: two frozen cross-era sentinels preserved for integer-era installs — the
  manifest tombstone requires-contract ">=3,<4" and the (contract 3)
  --version token — so an old binary/FO still gets the correct abort remedy.
- D5: the FO shared-core Startup gate rewritten to parse the version line and
  carry a single release-stamped "required binary minor" literal.
- D6: gateHost stops printing for too-old-plugin; both front doors now
  auto-heal it (install, re-gate once, refuse on a second miss) alongside the
  existing no-plugin-found heal. --skip-contract-check renames to
  --skip-compat-check throughout.
- Fixture manifests and cli tests migrate off static contract-range fixtures
  to versions derived from the effective binary version, so gating tests stay
  self-consistent as the repo's own manifest version advances.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Release tooling: prose-stamp .md handler, minor-only tag gate, AC-1 fixture

Adds the D5 release-pipeline half of minor-version coupling:

- internal/release: StampProseVersion/ProseMinor rewrite and read back the FO
  shared-core's single "required binary minor" literal, erroring on zero or
  multiple matches (atomic by construction) or an unparseable release version.
- cmd/spacedock-release: stamp-version and manifest-tag-gate now dispatch by
  file extension — a .md argument takes the prose handler/minor-only tag
  compare, a .json argument keeps the existing full-version handling, in the
  same multi-file invocation.
- EvaluateProseMinorTagGate compares a tag's major.minor against the
  prose-stamped minor (the prose carries no patch, unlike the JSON gate).
- TestStampVersionFlipsCompatibilityFloor is AC-1's divergeable proof:
  restamping ONLY the release version (no hand-edited integer) moves the SAME
  fixed binary version from Compatible to TooOldBinary against both the
  manifest and the prose gate.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* release.yml: wire the FO prose file into all three stamp-version call sites

The D5 prose gate needs the same release-stamp coverage the plugin manifests
already get, or a branch's skills contradict their own manifest (next carries
manifests at X.(Y+1).0-pre1 while un-restamped prose still says the prior
minor). Adds skills/first-officer/references/first-officer-shared-core.md to
the manifest-tag-gate arg list, the main-reconcile stamp-version call + its
git diff/commit path lists, and the next edge-bump stamp-version call + its
commit path list.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* internal/contractlint: sync test binds the FO prose minor to the manifests

Pins D5's cross-file invariant in the quarantine-sanctioned home for a check
that reads an instruction file: the FO shared-core's release-stamped "required
binary minor" literal must equal the major.minor each vendored plugin manifest
parses to, and the D4 tombstone (requires-contract ">=3,<4") stays frozen on
both manifests. skills/integration's manifest tests drop the now-duplicated
tombstone assertion, keeping only the manifest-shape checks that don't need an
instruction-file read.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: reword the deleted contract-integer mechanism out of user-visible docs

docs/releasing.md's stamp-then-tag step now carries the FO prose file
alongside the manifests, notes the go-install proxy build's cosmetic +dev
suffix; docs/runtime-live-ci.md's --skip-contract-check example renames to
--skip-compat-check; the proof-policy worked example (docs/site/contributing/
proof-policy.md and docs/dev/README.md) rewords "the plugin manifest's
contract range bracketing the binary's contract version" to "the plugin
manifest's version sharing a major.minor with the binary's version" — the old
example named a mechanism this task deletes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* internal/ensigncycle: rename --skip-contract-check to --skip-compat-check

Mechanical follow-through of the front-door flag rename in the (build-tag
live) runtime-live drive fixtures, so a live-tagged run of these tests still
invokes a flag the binary recognizes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Cleanup pass: rename remaining stray contract-integer mentions in test prose

Grep-level sweep for CONTRACT_VERSION / ParseRange / MalformedRange /
PluginPredatesContract / --skip-contract-check turned up three leftover
prose spots the earlier passes missed: a subtest name, a doc comment citing
the renamed MalformedVersion verdict, and pi's --help negative-assertion list.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Add D6 test coverage: too-old-plugin auto-heal was implemented but untested

resolveHealableGate's too-old-plugin arm (announce, install, re-gate once,
refuse on a second miss) had no direct test — the tooOldPluginManifest fixture
helper existed but nothing called it. Adds: gateHost stays silent for
too-old-plugin (mirrors the NoPluginFound silence test); both front doors
auto-refresh + re-gate + launch on success; --no-install refuses with the
gate's own mismatch remedy; a persisted mismatch after refresh refuses without
looping (exactly one Install call).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Add AC-5 dev-build coverage: the embed unit test and a real go-build fixture

displayVersion()'s dev-fallback (D3) had implementation but no dedicated
test: the unit half (embeddedManifestVersion reads this checkout's own
manifest, displayVersion falls back only when unstamped) and the behavior
fixture half (an actual `go build ./cmd/spacedock` + `--version` reports
<checkout-version>+dev on line 1) were both missing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Spike Test <spike@example.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

.claude-plugin/plugin.json

@@ -16,7 +16,7 @@
     "automation"
   ],
   "skills": "./skills/",
-  "requires-contract": ">=2,<3",
+  "requires-contract": ">=3,<4",
   "interface": {
     "displayName": "Spacedock",
     "shortDescription": "Plain text workflows for AI agents",

.codex-plugin/plugin.json

@@ -16,7 +16,7 @@
     "automation"
   ],
   "skills": "./skills/",
-  "requires-contract": ">=2,<3",
+  "requires-contract": ">=3,<4",
   "interface": {
     "displayName": "Spacedock",
     "shortDescription": "Plain text workflows for AI agents",

.github/workflows/release.yml

@@ -124,18 +124,20 @@ jobs:
           echo "release commit for $GITHUB_REF_NAME: $RELEASE_COMMIT"
           go run ./cmd/spacedock-release e2e-gate "$RELEASE_COMMIT"
 
-      # Assert the tagged commit's plugin manifests already carry the tag's semver
-      # — the stamp-then-tag ordering docs/releasing.md documents. The checkout
-      # above is at the tagged commit, so these are the tagged commit's manifests.
-      # A mismatch (the v0.20.0 pre-stamp inversion: tag 0.20.0, manifest 0.19.9)
-      # exits non-zero and blocks the cut, since goreleaser needs: this job. The
-      # `if` skips pre-releases (a vX.Y.Z-pre.N tag legitimately differs from its
-      # X.Y.Z manifest), matching the stamp step's pre-release carve-out below.
-      - name: Gate the cut on the tagged manifest matching the tag semver
+      # Assert the tagged commit's plugin manifests AND the FO shared-core prose
+      # already carry the tag's semver/minor — the stamp-then-tag ordering
+      # docs/releasing.md documents. The checkout above is at the tagged commit,
+      # so these are the tagged commit's files. A mismatch (the v0.20.0 pre-stamp
+      # inversion: tag 0.20.0, manifest 0.19.9; or a forgotten prose stamp) exits
+      # non-zero and blocks the cut, since goreleaser needs: this job. The `if`
+      # skips pre-releases (a vX.Y.Z-pre.N tag legitimately differs from its
+      # X.Y.Z manifest/prose), matching the stamp step's pre-release carve-out
+      # below.
+      - name: Gate the cut on the tagged manifest/prose matching the tag semver
         if: "!contains(github.ref, '-')"
         run: |
           set -euo pipefail
-          go run ./cmd/spacedock-release manifest-tag-gate "$GITHUB_REF_NAME" .claude-plugin/plugin.json .codex-plugin/plugin.json
+          go run ./cmd/spacedock-release manifest-tag-gate "$GITHUB_REF_NAME" .claude-plugin/plugin.json .codex-plugin/plugin.json skills/first-officer/references/first-officer-shared-core.md
 
   goreleaser:
     needs: e2e-gate
@@ -218,6 +220,7 @@ jobs:
         run: |
           set -euo pipefail
           RELEASE_VERSION="${GITHUB_REF_NAME#v}"
+          FO_PROSE=skills/first-officer/references/first-officer-shared-core.md
           # The tagged commit is the SHA the e2e-gate greened and the manifest-tag
           # gate matched. Resolve it BEFORE switching to main, so the stable ref
           # below advances to exactly THIS commit, not whatever main HEAD happens to
@@ -226,14 +229,14 @@ jobs:
           git fetch origin main
           git switch main
           go run ./cmd/spacedock-release stamp-version "$RELEASE_VERSION" \
-            .claude-plugin/plugin.json .codex-plugin/plugin.json
-          if git diff --quiet -- .claude-plugin/plugin.json .codex-plugin/plugin.json; then
-            echo "plugin manifests already at $RELEASE_VERSION; nothing to commit"
+            .claude-plugin/plugin.json .codex-plugin/plugin.json "$FO_PROSE"
+          if git diff --quiet -- .claude-plugin/plugin.json .codex-plugin/plugin.json "$FO_PROSE"; then
+            echo "plugin manifests and FO prose already at $RELEASE_VERSION; nothing to commit"
           else
             git config user.name "github-actions[bot]"
             git config user.email "github-actions[bot]@users.noreply.github.com"
-            git commit -m "release: stamp plugin manifests to $RELEASE_VERSION" \
-              -- .claude-plugin/plugin.json .codex-plugin/plugin.json
+            git commit -m "release: stamp plugin manifests and FO prose to $RELEASE_VERSION" \
+              -- .claude-plugin/plugin.json .codex-plugin/plugin.json "$FO_PROSE"
             git push origin main
           fi
           # Advance the stable channel ref to the TAGGED commit. The
@@ -303,10 +306,11 @@ jobs:
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git merge -X theirs --no-edit "$RELEASE_COMMIT" \
             -m "next: reconcile edge line to $GITHUB_REF_NAME"
+          FO_PROSE=skills/first-officer/references/first-officer-shared-core.md
           go run ./cmd/spacedock-release stamp-version "$DEV_VERSION" \
-            .claude-plugin/plugin.json .codex-plugin/plugin.json
+            .claude-plugin/plugin.json .codex-plugin/plugin.json "$FO_PROSE"
           git commit -m "next: bump dev pre-version to $DEV_VERSION" \
-            -- .claude-plugin/plugin.json .codex-plugin/plugin.json
+            -- .claude-plugin/plugin.json .codex-plugin/plugin.json "$FO_PROSE"
 
       # Both paths end here: bump the marketplace calendar key (the moving-branch
       # re-pull key `claude plugin update` / `codex` read) and fast-forward `next`.

cmd/spacedock-release/main.go

@@ -19,21 +19,25 @@ import (
 //
 // Usage:
 //
-//	spacedock-release stamp-version <release-version> <plugin.json> [<plugin.json> ...]
+//	spacedock-release stamp-version <release-version> <manifest-or-prose> [<manifest-or-prose> ...]
 //	spacedock-release bump-calendar <marketplace.json>
 //	spacedock-release dev-preversion <stable-version>
 //	spacedock-release e2e-gate <release-commit-sha>
 //
-// stamp-version rewrites each manifest's top-level `version` to the release
-// version (AC-4). bump-calendar advances the marketplace plugin entry's calendar
-// key to today's `0.0.YYYYMMDDNN` (AC-2d). Both rewrite in place. dev-preversion
-// prints the post-release dev pre-version (X.(Y+1).0-pre1) the stable-tag edge
-// advance stamps onto `next`. e2e-gate is the
+// stamp-version rewrites each argument to the release version: a `.json`
+// plugin.json gets its top-level `version` field rewritten (AC-4); a `.md`
+// argument is the FO shared-core prose, whose single release-stamped "required
+// binary minor" literal is rewritten to the release's major.minor (D5) —
+// erroring unless the literal appears exactly once. bump-calendar advances the
+// marketplace plugin entry's calendar key to today's `0.0.YYYYMMDDNN` (AC-2d).
+// All rewrite in place. dev-preversion prints the post-release dev pre-version
+// (X.(Y+1).0-pre1) the stable-tag edge advance stamps onto `next`. e2e-gate is the
 // release-time precondition: it passes (exit 0) only when a conclusion:success
 // Runtime Live E2E run exists for the commit, or when SPACEDOCK_E2E_GATE_WAIVER
 // is set, and blocks the cut (exit 1) otherwise. manifest-tag-gate blocks the cut
-// unless every tagged plugin.json's version equals the tag semver (the stamp-then-tag
-// ordering). notes summarizes the commit log
+// unless every tagged `.json` manifest's version equals the tag semver AND every
+// tagged `.md` prose's stamped minor equals the tag's major.minor (the
+// stamp-then-tag ordering). notes summarizes the commit log
 // since the last tag into clean release notes and, on confirmation, cuts the
 // annotated tag whose body carries them (CI extracts that body and feeds
 // goreleaser via --release-notes).
@@ -140,7 +144,16 @@ func stampVersion(args []string) int {
 			fmt.Fprintf(os.Stderr, "read %s: %v\n", path, err)
 			return 1
 		}
-		out, err := release.StampVersion(data, version)
+		// D5: a `.md` argument is the FO shared-core prose — one release-stamped
+		// "required binary minor" literal, rewritten by StampProseVersion. Every
+		// other extension (the plugin.json manifests) keeps the existing JSON
+		// full-version stamp. One invocation, one atomic multi-file rewrite.
+		var out []byte
+		if strings.HasSuffix(path, ".md") {
+			out, err = release.StampProseVersion(data, version)
+		} else {
+			out, err = release.StampVersion(data, version)
+		}
 		if err != nil {
 			fmt.Fprintf(os.Stderr, "stamp %s: %v\n", path, err)
 			return 1
@@ -346,12 +359,12 @@ func usage() {
 	fmt.Fprint(os.Stderr, `spacedock-release is the release-pipeline version tool.
 
 Usage:
-  spacedock-release stamp-version <release-version> <plugin.json> [<plugin.json> ...]
+  spacedock-release stamp-version <release-version> <manifest-or-prose> [<manifest-or-prose> ...]
   spacedock-release bump-calendar <marketplace.json>
   spacedock-release dev-preversion <stable-version>
   spacedock-release journey-costs <release-version> --metrics-dir <dir> --out <path>
   spacedock-release e2e-gate <release-commit-sha>
-  spacedock-release manifest-tag-gate <tag> <plugin.json> [<plugin.json> ...]
+  spacedock-release manifest-tag-gate <tag> <manifest-or-prose> [<manifest-or-prose> ...]
   spacedock-release notes <release-version>
 `)
 }

cmd/spacedock-release/manifest_tag_gate.go

@@ -1,44 +1,59 @@
-// ABOUTME: `spacedock-release manifest-tag-gate <tag> <plugin.json>...` — blocks
-// ABOUTME: the cut unless every tagged manifest's version equals the tag semver.
+// ABOUTME: `spacedock-release manifest-tag-gate <tag> <manifest-or-prose>...` —
+// ABOUTME: blocks the cut unless every tagged manifest/prose agrees with the tag.
 package main
 
 import (
 	"fmt"
 	"os"
+	"strings"
 
 	"github.com/spacedock-dev/spacedock/internal/release"
 )
 
-// runManifestTagGate asserts the tag semver equals the version stamped into each
-// plugin manifest the cutter is about to tag. It reads the manifest version from
-// each file (an independent value from the tag), runs the pure decision predicate,
-// records the outcome to $GITHUB_STEP_SUMMARY, and returns the process exit code:
-// 0 when every manifest matches the tag, 1 when any diverges or cannot be read, 2
-// on a usage error. This is the divergeable guard behind the reconciled
-// releasing.md's stamp-then-tag ordering: a tag-vs-manifest mismatch (the pre-stamp
-// inversion) is caught before goreleaser fires.
+// runManifestTagGate asserts the tag semver agrees with each tagged file the
+// cutter is about to tag: a `.json` plugin manifest's version must equal the
+// tag semver exactly; a `.md` prose file's stamped minor (D5) must equal the
+// tag's major.minor. It reads each file's value (independent of the tag), runs
+// the pure decision predicate, records the outcome to $GITHUB_STEP_SUMMARY, and
+// returns the process exit code: 0 when every file matches the tag, 1 when any
+// diverges or cannot be read, 2 on a usage error. This is the divergeable guard
+// behind the reconciled releasing.md's stamp-then-tag ordering: a
+// tag-vs-manifest/prose mismatch (the pre-stamp inversion) is caught before
+// goreleaser fires.
 func runManifestTagGate(args []string) int {
 	if len(args) < 2 {
-		fmt.Fprintln(os.Stderr, "spacedock-release manifest-tag-gate: need <tag> <plugin.json> [<plugin.json> ...]")
+		fmt.Fprintln(os.Stderr, "spacedock-release manifest-tag-gate: need <tag> <manifest-or-prose> [<manifest-or-prose> ...]")
 		return 2
 	}
-	tag, manifests := args[0], args[1:]
-	for _, path := range manifests {
+	tag, files := args[0], args[1:]
+	for _, path := range files {
 		data, err := os.ReadFile(path)
 		if err != nil {
 			reason := fmt.Sprintf("manifest-tag gate BLOCKED for %s: cannot read %s (%v)", tag, path, err)
 			fmt.Fprintln(os.Stderr, reason)
 			recordManifestTagSummary(reason)
 			return 1
 		}
-		version, err := release.ManifestVersion(data)
-		if err != nil {
-			reason := fmt.Sprintf("manifest-tag gate BLOCKED for %s: cannot parse %s (%v)", tag, path, err)
-			fmt.Fprintln(os.Stderr, reason)
-			recordManifestTagSummary(reason)
-			return 1
+		var dec release.ManifestTagDecision
+		if strings.HasSuffix(path, ".md") {
+			minor, err := release.ProseMinor(data)
+			if err != nil {
+				reason := fmt.Sprintf("manifest-tag gate BLOCKED for %s: cannot read prose minor from %s (%v)", tag, path, err)
+				fmt.Fprintln(os.Stderr, reason)
+				recordManifestTagSummary(reason)
+				return 1
+			}
+			dec = release.EvaluateProseMinorTagGate(tag, minor)
+		} else {
+			version, err := release.ManifestVersion(data)
+			if err != nil {
+				reason := fmt.Sprintf("manifest-tag gate BLOCKED for %s: cannot parse %s (%v)", tag, path, err)
+				fmt.Fprintln(os.Stderr, reason)
+				recordManifestTagSummary(reason)
+				return 1
+			}
+			dec = release.EvaluateManifestTagGate(tag, version)
 		}
-		dec := release.EvaluateManifestTagGate(tag, version)
 		if !dec.Pass {
 			reason := fmt.Sprintf("%s (%s)", dec.Reason, path)
 			fmt.Fprintf(os.Stderr, "spacedock-release manifest-tag-gate: %s\n", reason)
@@ -47,7 +62,7 @@ func runManifestTagGate(args []string) int {
 		}
 		fmt.Printf("%s (%s)\n", dec.Reason, path)
 	}
-	recordManifestTagSummary(fmt.Sprintf("manifest-tag gate PASSED for %s: all %d manifest(s) match the tag semver", tag, len(manifests)))
+	recordManifestTagSummary(fmt.Sprintf("manifest-tag gate PASSED for %s: all %d file(s) match the tag", tag, len(files)))
 	return 0
 }
 

cmd/spacedock-release/manifest_tag_gate_test.go

@@ -62,3 +62,37 @@ func TestManifestTagGateCommandBlocksUnreadableManifest(t *testing.T) {
 		t.Fatalf("manifest-tag-gate exit = 0 on an unreadable manifest; want non-zero")
 	}
 }
+
+// writeProse writes an FO shared-core prose fixture stamped at the given minor
+// to a temp .md file and returns its path.
+func writeProse(t *testing.T, minor string) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "first-officer-shared-core.md")
+	body := "These skills require binary minor " + minor + " (same major.minor; patch and prerelease skew are fine).\n"
+	if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
+
+// TestManifestTagGateCommandChecksProseMinor — D5: the subcommand also takes the
+// FO shared-core `.md` prose file, gating on its stamped minor (not the full
+// manifest version) against the tag's major.minor.
+func TestManifestTagGateCommandChecksProseMinor(t *testing.T) {
+	manifest := writeManifest(t, "0.24.0")
+	prose := writeProse(t, "0.24")
+	if code := runManifestTagGate([]string{"v0.24.0", manifest, prose}); code != 0 {
+		t.Fatalf("manifest-tag-gate exit = %d, want 0 when both manifest and prose agree with the tag", code)
+	}
+}
+
+// TestManifestTagGateCommandBlocksOnProseMinorMismatch — a stable tag whose
+// major.minor disagrees with the prose-stamped minor (a forgotten prose stamp)
+// blocks the cut even when the JSON manifest agrees.
+func TestManifestTagGateCommandBlocksOnProseMinorMismatch(t *testing.T) {
+	manifest := writeManifest(t, "0.24.0")
+	staleProse := writeProse(t, "0.23") // forgotten stamp
+	if code := runManifestTagGate([]string{"v0.24.0", manifest, staleProse}); code == 0 {
+		t.Fatalf("manifest-tag-gate exit = 0 with a prose minor lagging the tag; want non-zero")
+	}
+}

cmd/spacedock-release/stamp_version_test.go

@@ -0,0 +1,65 @@
+// ABOUTME: `spacedock-release stamp-version` CLI test — one invocation stamps a
+// ABOUTME: JSON manifest AND the FO prose file, dispatching by file extension.
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestStampVersionCommandStampsManifestAndProseInOneInvocation is D5's atomic
+// multi-file round-trip: one `stamp-version` call over a `.json` manifest AND a
+// `.md` prose fixture rewrites the manifest's `version` field AND the prose's
+// pinned minor literal — the shape release.yml's stamp steps actually invoke
+// (the plugin manifests plus the FO shared-core file in one command).
+func TestStampVersionCommandStampsManifestAndProseInOneInvocation(t *testing.T) {
+	dir := t.TempDir()
+	manifestPath := filepath.Join(dir, "plugin.json")
+	prosePath := filepath.Join(dir, "first-officer-shared-core.md")
+
+	if err := os.WriteFile(manifestPath, []byte(`{"name": "spacedock", "version": "0.23.0", "skills": "./skills/"}`+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(prosePath, []byte("These skills require binary minor 0.23 (blah).\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	if code := stampVersion([]string{"0.24.0", manifestPath, prosePath}); code != 0 {
+		t.Fatalf("stampVersion exit = %d, want 0", code)
+	}
+
+	manifestOut, err := os.ReadFile(manifestPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(manifestOut), `"version": "0.24.0"`) {
+		t.Fatalf("manifest not stamped: %s", manifestOut)
+	}
+
+	proseOut, err := os.ReadFile(prosePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(proseOut), "These skills require binary minor 0.24 ") {
+		t.Fatalf("prose not stamped: %s", proseOut)
+	}
+	if strings.Contains(string(proseOut), "minor 0.23") {
+		t.Fatalf("prose still carries the old minor: %s", proseOut)
+	}
+}
+
+// TestStampVersionCommandErrorsOnUnstampableProse locks that a `.md` argument
+// with no pinned literal (or a duplicated one) errors the whole invocation
+// rather than silently leaving the prose untouched.
+func TestStampVersionCommandErrorsOnUnstampableProse(t *testing.T) {
+	dir := t.TempDir()
+	prosePath := filepath.Join(dir, "no-literal.md")
+	if err := os.WriteFile(prosePath, []byte("no pinned literal here\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if code := stampVersion([]string{"0.24.0", prosePath}); code == 0 {
+		t.Fatalf("stampVersion exit = 0 on an unstampable prose file; want non-zero")
+	}
+}