Merge remote-tracking branch 'origin/main' into spacedock-ensign/boot-metrics-record-and-pr-delta

# Conflicts:
#	cmd/spacedock-release/main.go

Author: Spike Test

.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

@@ -150,18 +150,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
@@ -244,6 +246,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
@@ -252,14 +255,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
@@ -329,10 +332,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,31 +19,35 @@ 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 journey-delta <previous-ledger.json> --metrics-dir <dir> --pr <number>
 //	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`. journey-delta renders and posts the per-PR
-// journey-cost delta against the previously published release ledger's
-// latest-by-captured_at baseline per scenario/model, updating a single sticky
-// PR comment found by its HTML marker. The AC-4 release-ledger backfill (a
-// captain-flagged one-time manual procedure, never a CI step) is a documented
-// runbook, not a shipped subcommand: extraction reuses the exported
-// ensigncycle.BuildShallowBootWindowRecord via a throwaway `go run` script
-// against each archived stream, and the pre-upload safeguard is
+// 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`. journey-delta
+// renders and posts the per-PR journey-cost delta against the previously
+// published release ledger's latest-by-captured_at baseline per scenario/model,
+// updating a single sticky PR comment found by its HTML marker. The AC-4
+// release-ledger backfill (a captain-flagged one-time manual procedure, never a
+// CI step) is a documented runbook, not a shipped subcommand: extraction reuses
+// the exported ensigncycle.BuildShallowBootWindowRecord via a throwaway `go run`
+// script against each archived stream, and the pre-upload safeguard is
 // `jq -S .scenarios <original> | diff - <(jq -S .scenarios <rebuilt>)` —
 // any diff output means STOP, do not upload. 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).
@@ -152,7 +156,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
@@ -358,13 +371,13 @@ 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 journey-delta <previous-ledger.json> --metrics-dir <dir> --pr <number>
   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")
+	}
+}