Merge pull request #72 from TrentBrown/tb-portreeve-release-versioning

Fix coordinated preview release identity

Author: TrentBrown

.agents/skills/release-portreeve/SKILL.md

@@ -55,6 +55,12 @@ bun run release:prepare -- \
   --version 0.1.0-preview.1
 ```
 
+The requested version is the installed identity of every release output. Preview builds
+inject the full prerelease into the CLI, client package, Desktop metadata, formula, and
+cask while leaving checked-in package files at the matching semantic core. Never edit
+multiple package files as an operator precondition or accept a formula/cask that drops
+the prerelease suffix.
+
 For the complete hosted rehearsal:
 
 ```sh

apps/desktop/main/index.js

@@ -28,7 +28,10 @@ import { createStackDocumentService } from './stack-document.js';
 import { registerDesktopIpc } from './ipc.js';
 import { registerRendererProtocol } from './protocol.js';
 import { createUpdateAdapter } from './update.js';
-import { resolveDesktopReleaseChannel } from './release-channel.js';
+import {
+  resolveDesktopReleaseChannel,
+  resolveDesktopReleaseVersion,
+} from './release-channel.js';
 import { desktopUpdateStatePath, resolveDesktopUserDataPath } from './user-data.js';
 import { createLauncherRuntime } from '../../../src/launcher/runtime.js';
 import { resolveRuntimePaths } from '../../../src/platform/paths.js';
@@ -104,8 +107,13 @@ async function startDesktop() {
           ? { overridePath: process.env.PORTREEVE_DESKTOP_CLI_PATH }
           : {}),
       });
-  const releaseChannel = resolveDesktopReleaseChannel(
-    JSON.parse(await readFile(resolve(app.getAppPath(), 'package.json'), 'utf8')),
+  const desktopMetadata = JSON.parse(
+    await readFile(resolve(app.getAppPath(), 'package.json'), 'utf8'),
+  );
+  const releaseChannel = resolveDesktopReleaseChannel(desktopMetadata);
+  const desktopVersion = resolveDesktopReleaseVersion(
+    desktopMetadata,
+    app.getVersion(),
   );
   diagnose('artifact-verified', artifact.filename);
   const lifecycle = createDesktopLifecycleController(artifact);
@@ -114,7 +122,7 @@ async function startDesktop() {
     console.log(
       `PORTREEVE_DESKTOP_SMOKE ${JSON.stringify({
         schemaVersion: 1,
-        desktopVersion: app.getVersion(),
+        desktopVersion,
         controllerVersion: lifecycle.compatibility.version,
         artifactVersion: artifact.version,
         mode: status.mode,
@@ -161,7 +169,7 @@ async function startDesktop() {
   const coordinator = createStateCoordinator({
     artifact: {
       ...artifact,
-      desktopVersion: app.getVersion(),
+      desktopVersion,
       controller: lifecycle.compatibility,
     },
     lifecycle,
@@ -180,7 +188,7 @@ async function startDesktop() {
     }),
     launchers,
     updates: createUpdateAdapter({
-      desktopVersion: app.getVersion(),
+      desktopVersion,
       channel: releaseChannel,
       statePath: desktopUpdateStatePath(app.getPath('userData')),
       openExternal: (url) => shell.openExternal(url),

apps/desktop/main/release-channel.js

@@ -12,3 +12,19 @@ export function resolveDesktopReleaseChannel(metadata) {
   }
   return /** @type {const} */ ('preview');
 }
+
+/** @param {unknown} metadata @param {string} fallback */
+export function resolveDesktopReleaseVersion(metadata, fallback) {
+  if (
+    metadata !== null &&
+    typeof metadata === 'object' &&
+    'portreeveReleaseVersion' in metadata &&
+    typeof metadata.portreeveReleaseVersion === 'string' &&
+    /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.test(
+      metadata.portreeveReleaseVersion,
+    )
+  ) {
+    return metadata.portreeveReleaseVersion;
+  }
+  return fallback;
+}

docs/issues/tb-portreeve-release-versioning/completion-report.md

@@ -0,0 +1,43 @@
+# Completion Report - Coordinated Preview Release Identity
+
+**Status:** Complete and awaiting human review in PR
+[#72](https://github.com/TrentBrown/portreeve/pull/72)
+
+## Outcome
+
+PortReeve now treats an operator-supplied release version such as
+`0.1.0-preview.4` as the observable identity of every distributed component. CLI
+binaries, the client archive, records and manifests, Homebrew metadata, Desktop
+metadata and update comparison, and release filenames agree on that identity.
+
+Checked-in packages remain at their base development version. The release engine
+requires the requested version to share that semantic core and injects the full version
+only into immutable outputs. Apple bundle metadata remains numeric while PortReeve's
+own packaged metadata retains the prerelease.
+
+## Acceptance and Rubric
+
+All acceptance criteria AC1-AC5 and rubric criteria R1-R5 pass. The complete evidence
+packet is [`pr-72/boundary.json`](pr-72/boundary.json).
+
+## Verification Summary
+
+- Full repository gate: 550 tests passed, 0 failed; typecheck, lint, formatting, and
+  generated documentation passed.
+- Real preview.4 candidate: all four native formats built; the macOS ARM64 executable
+  reported preview.4 and passed native server smoke.
+- Desktop: ARM64 package and launch smoke reported preview.4 while Apple's short version
+  remained 0.1.0.
+- Homebrew: the generated formula and cask retain preview.4, and Homebrew orders it after
+  preview.3 and before stable 0.1.0.
+- Publication: not performed; preview.3 and public distribution state remain untouched.
+
+## Retention
+
+The feature-final workflow check reports `tracked`: every feature-record file is retained
+in Git, and no human retention exception is required.
+
+## Remaining Human Action
+
+Review and merge PR #72. A later, separately authorized preview release will provide the
+first public end-to-end exercise of the corrected identity.

docs/issues/tb-portreeve-release-versioning/decisions.md

@@ -0,0 +1,48 @@
+# Decisions - tb-portreeve-release-versioning
+
+**Feature start:** 2026-08-18
+
+Permanent record of decisions promoted from `scratchpad.md`.
+
+---
+
+## Inject release identity without mutating source package versions
+
+**Confidence:** HIGH
+
+**Blast Radius:** native builds, client packing, Desktop packaging, records,
+Homebrew metadata, and update checks
+
+Keep checked-in package versions as the development base and inject the
+operator-approved coordinated version into immutable release outputs. Validate
+that their semantic cores match before building.
+
+**Triggered by:** preview.2 and preview.3 both appearing to Homebrew as `0.1.0`
+
+**Alternatives considered:**
+- Homebrew revision only - leaves every other distributed identity inconsistent.
+- Edit all package versions before release - adds manual ceremony and conflicts
+  with the clean-source release precondition.
+
+**Promoted:** 2026-08-18. PR: #72.
+
+---
+
+## Preserve numeric Apple bundle version separately
+
+**Confidence:** HIGH
+
+**Blast Radius:** macOS packaging and Desktop update identity
+
+Keep the source base version in `CFBundleShortVersionString`, but embed the
+coordinated semantic release version in PortReeve package metadata and use it
+for product reporting and update comparisons.
+
+**Triggered by:** Apple bundle version constraints do not model semantic
+prerelease identifiers cleanly.
+
+**Alternatives considered:**
+- Put the prerelease string directly in the Apple bundle version - avoid because
+  stable signing/notarization will require Apple-conformant numeric metadata.
+
+**Promoted:** 2026-08-18. PR: #72.

docs/issues/tb-portreeve-release-versioning/design.md

@@ -0,0 +1,61 @@
+# Design - tb-portreeve-release-versioning
+
+**Feature:** `tb-portreeve-release-versioning`
+**Created:** 2026-08-18
+**Status:** approved
+
+## Problem
+
+PortReeve currently records `0.1.0-preview.N` as the GitHub release identity but
+builds and publishes components identified as `0.1.0`. Homebrew compares the
+component version, so it cannot discover a later preview of the same base
+version. Desktop update comparison has the same blind spot.
+
+## Chosen model
+
+The operator-supplied coordinated semantic release version is authoritative for
+every distributed PortReeve surface:
+
+- compiled CLI behavior and native artifact filenames;
+- packed JavaScript client metadata and runtime client identity;
+- release record component versions and manifest versions;
+- Homebrew formula and cask versions;
+- Desktop DMG filenames, packaged PortReeve release identity, update metadata,
+  and update comparison.
+
+Checked-in package files retain a base development version. Release building
+validates that the coordinated version's semantic core equals that base version,
+then injects the coordinated version into immutable release outputs. This keeps
+release invocation deterministic and avoids a manual multi-file version-bump
+precondition.
+
+The macOS `CFBundleShortVersionString` may remain the numeric base version because
+Apple defines that field independently from semantic prerelease identity. A
+packaged PortReeve metadata field carries the coordinated version, and Desktop
+uses it instead of `app.getVersion()` for product identity and update checks.
+
+## Invariants
+
+1. All release-record component versions equal the coordinated release version.
+2. Every native executable reports the coordinated version through `--version`.
+3. Formula and cask versions equal the coordinated version.
+4. The packed client package and exported client version equal the coordinated
+   version.
+5. The packaged Desktop reports and compares the coordinated version even when
+   its Apple bundle version remains numeric.
+6. A stable release has no prerelease suffix; a preview release has one; both
+   must share their semantic core with source component versions.
+7. Existing public releases and assets are never rewritten.
+
+## Rejected alternatives
+
+- **Homebrew-only revision bumps:** fixes one installer while leaving CLI,
+  Desktop updates, records, and client identity inconsistent.
+- **Manual edits to all package files before release:** introduces an operator
+  ceremony and dirty-checkout problems into an otherwise deterministic pipeline.
+- **Treat preview.3 as a one-time exception:** repeats the defect at preview.4.
+
+## Approval record
+
+Approved by the user on 2026-08-18 through the instruction to correct the
+recurring preview-version problem immediately.

docs/issues/tb-portreeve-release-versioning/interview.md

@@ -0,0 +1,42 @@
+# Interview - tb-portreeve-release-versioning
+
+**Feature start:** 2026-08-18
+**Status:** complete
+
+## Trigger
+
+Publishing `0.1.0-preview.3` exposed that the public release identity and every
+installed component still reported `0.1.0`. Homebrew therefore treated an
+installed preview.2 as current after the tap moved to preview.3.
+
+## Settled intent
+
+- The defect is recurring for every preview sharing the same base version, not
+  a one-time repair for the current sole user.
+- The coordinated semantic release version supplied to release preparation is
+  the installed identity of the CLI, JavaScript client, Desktop release, formula,
+  and cask.
+- Homebrew must order successive previews and the eventual stable version as
+  `preview.2 < preview.3 < preview.4 < 0.1.0`.
+- Development checkouts may retain the base source version (`0.1.0`). Release
+  preparation must inject the coordinated identity deterministically rather
+  than requiring an operator to edit several package files before every run.
+- macOS bundle metadata that is constrained to numeric versions may retain the
+  base version. PortReeve's own packaged runtime identity and update comparison
+  must still use the coordinated prerelease version.
+- Published preview.3 remains immutable. The correction applies to future
+  releases beginning with preview.4.
+
+## Boundaries
+
+- Do not republish or alter preview.3.
+- Do not add npm publication; the packed client remains release evidence only.
+- Preserve the build-once evidence and protected publication model.
+- Reject a coordinated release whose semantic core does not match the checked-in
+  base component version.
+
+## Approval
+
+The user approved correcting this immediately after the release audit explained
+the recurring behavior and recommended one coordinated version across distributed
+surfaces.

docs/issues/tb-portreeve-release-versioning/issues.md

@@ -0,0 +1,43 @@
+# Issues - tb-portreeve-release-versioning
+
+**Feature:** `tb-portreeve-release-versioning`
+**Spec:** [`spec.md`](spec.md)
+**Plan:** [`plan.md`](plan.md)
+**Created:** 2026-08-18
+
+Operational task breakdown derived from the plan.
+
+## I-1 - Establish coordinated version mechanics
+
+- **Status:** in-review
+- **Estimate:** 2h
+- **Plan steps:** P1, P2
+- **Rubric criteria:** R1, R2, R4
+- **Depends on:** none
+- **PR:** [#72](https://github.com/TrentBrown/portreeve/pull/72)
+
+Validate release/source compatibility, inject the release identity into compiled
+CLI artifacts, and stage the client archive with the same identity.
+
+## I-2 - Coordinate Desktop and installer identity
+
+- **Status:** in-review
+- **Estimate:** 2h
+- **Plan steps:** P3
+- **Rubric criteria:** R2, R3
+- **Depends on:** I-1
+- **PR:** [#72](https://github.com/TrentBrown/portreeve/pull/72)
+
+Use coordinated release identity for Desktop runtime/update surfaces, DMGs, and
+the Homebrew cask while preserving numeric Apple bundle metadata.
+
+## I-3 - Verify and document release versioning
+
+- **Status:** in-review
+- **Estimate:** 2h
+- **Plan steps:** P4
+- **Rubric criteria:** R1-R5
+- **Depends on:** I-1, I-2
+- **PR:** [#72](https://github.com/TrentBrown/portreeve/pull/72)
+
+Update the runbook and exercise focused, runtime, Homebrew, and full checks.

docs/issues/tb-portreeve-release-versioning/plan.md

@@ -0,0 +1,44 @@
+# Plan - tb-portreeve-release-versioning
+
+**Feature:** `tb-portreeve-release-versioning`
+**Spec:** [`spec.md`](spec.md)
+**Design:** [`design.md`](design.md)
+**Interview:** [`interview.md`](interview.md)
+**Created:** 2026-08-18
+
+**Implementation status:** Complete in PR [#72](https://github.com/TrentBrown/portreeve/pull/72); awaiting review.
+
+## Inputs
+
+- `spec.md` controls scope, required behavior, and rubric mapping.
+- `design.md` supplies the chosen architecture, constraints, and boundaries.
+- `interview.md` supplies supporting examples, rationale, references, and edge cases.
+
+## Strategy
+
+Introduce release-version helpers and deterministic build-time injection while
+leaving checked-in package versions as development bases. Flow the coordinated
+version through native build, staged client packing, Desktop packaging, Homebrew
+generation, records, and update comparison. Verify both metadata and executable
+behavior with preview.4 fixtures.
+
+## Steps
+
+- **P1.** Add semantic-core validation and a reusable Bun build-time server
+  version override. **Advances:** R1, R4.
+- **P2.** Use the coordinated identity for native artifact names, compiled CLI,
+  staged client package/version source, manifests, records, and formula.
+  **Advances:** R1, R2, R4.
+- **P3.** Flow the coordinated identity through Desktop bundles, DMG/cask
+  metadata, runtime reporting, and update checks without placing a prerelease in
+  constrained Apple numeric version fields. **Advances:** R2, R3.
+- **P4.** Update runbook and focused tests; prove Homebrew ordering, candidate
+  smoke behavior, and full repository health. **Advances:** R1-R5.
+
+## Verification
+
+- Focused release and Desktop unit/integration tests.
+- Local native preview build and `--version` execution on the host architecture.
+- Disposable Homebrew preview-upgrade behavior where practical.
+- `bun run check`.
+- **Final step:** Run full rubric evaluation and produce the completion report.