stage-11-agentics/c11/release

Release

Run this workflow to prepare and publish a c11 release.

Pre-flight

Surface these five facts in one batch before touching anything else:

1. Branch state. git branch --show-current + git status -s. If HEAD

isn't on main, surface it — the operator may not realize. Wrong-branch is easy to miss and load-bearing for every step downstream.

1. Dirty tree disposition. Enumerate tracked diffs. For each, surface

what it does and ask: commit on the release branch, stash, or discard? Untracked files are usually fine; tracked code needs an explicit call.

1. In-flight PRs. gh pr list --state open --json number,title,headRefName.

Each open PR is an explicit include-or-defer decision.

1. In-flight sub-agents (c11 only). c11 tree --no-layout; read each

panel's role / task / status metadata. If another agent has unfinished work that belongs in the release, surface it now — not after the release branch is cut.

1. Previous release merged back. git fetch origin main 'refs/tags/v*:refs/tags/v*' && git merge-base --is-ancestor "$(git tag -l 'v*' --sort=-v:refname | head -1)" origin/main (fetching only v* tags avoids the moving nightly tag). A silent exit 0 means it merged back. If the newest v* tag is not on main (exit 1), its merge-back (step 11) is outstanding. That is a blocker: main still carries the old version, so the next bump would reuse it, and git describe on main would skip that tag and widen the changelog range.

If the operator says "skip pre-flight," skip. Otherwise run all five every time.

Workflow

1. Determine the version:

• Read MARKETING_VERSION from GhosttyTabs.xcodeproj/project.pbxproj.
• Default to a minor bump unless the user explicitly requests patch/major/specific version.

1. Create a release branch from current main:

• git fetch origin main && git checkout -b release/vX.Y.Z origin/main

1. Gather user-facing changes and contributors since the last versioned release tag:

• git describe --tags --abbrev=0 --match 'v*' (artifact tags such as nightly and xcframework-* are not releases)
• git log --oneline <last-tag>..HEAD --no-merges
• Keep only end-user visible changes (features, bug fixes, UX/perf behavior).
• Collect contributors: For each PR, get the author with gh pr view <N> --repo Stage-11-Agentics/c11 --json author --jq '.author.login'. Also check linked issue reporters with gh issue view <N> --json author --jq '.author.login'.
• Build a deduplicated list of all contributor @handles.

1. Update changelogs:

• Update CHANGELOG.md.
• The ## [X.Y.Z] - YYYY-MM-DD section is the release body; release.yml and release-local.sh refuse a tag without it.
• Do not edit a separate docs changelog file; web/app/[locale]/docs/changelog/page.tsx renders from CHANGELOG.md.
• Use categories Added, Changed, Fixed, Removed.
• Credit contributors inline (see Contributor Credits below).
• If no user-facing changes exist, confirm with the user before continuing.

1. Bump app version metadata:

• Prefer ./scripts/bump-version.sh:
• ./scripts/bump-version.sh (minor)
• ./scripts/bump-version.sh patch|major|X.Y.Z
• Ensure both MARKETING_VERSION and CURRENT_PROJECT_VERSION are updated.

Security threat-model recheck

Before the version bump lands, look at whether this release moved any security-sensitive surface. The canonical posture lives in docs/security-threat-model.md; the diff signals below tell you when a re-read is warranted. Run this grep against the release range and read the threat-model doc end-to-end if any signal fires:

git diff "$(git describe --tags --abbrev=0 --match 'v*')..HEAD" -- \
  Resources/Info.plist \
  c11.entitlements \
  Resources/c11.sdef \
  Sources/SocketControlSettings.swift \
  'Sources/SocketControl*' \
  Sources/AppDelegate.swift \
  Sources/Panels/BrowserPanel.swift \
  Sources/Panels/BrowserPanelView.swift \
  Sources/BrowserWindowPortal.swift \
  Sources/Panels/MarkdownWebRenderer.swift \
  Sources/UntrustedRepositoryGit.swift \
  Sources/MarkdownAssetPolicy.swift \
  Sources/MarkdownCorpusIndex.swift \
  Sources/SocketHandlers/MarkdownFeedbackHandlers.swift \
  Resources/markdown-viewer/ \
  Sources/Events/EventLog.swift \
  Sources/PanelLinkActivation.swift

The URL handler around Sources/AppDelegate.swift:2301 (application(_:open:)) and any new WKWebViewConfiguration / WKContentController configuration are the highest-attention sub-targets — they are the chief untrusted-input vectors into the app. If a signal fires, update docs/security-threat-model.md to match the new posture and surface the change in the release notes so reviewers can see the security posture moved. Benign diffs (NSUsageDescription string tweaks, version bumps that touch the plist incidentally) do not require an update — acknowledge the diff and continue.

This is a checklist trigger, not a CI gate.

1. Commit and push branch:

• Stage release files (changelog + version updates).
• Commit with Bump version to X.Y.Z.
• git push -u origin release/vX.Y.Z.

6.5. Build the tagged staging artifact:

• Build from a clean, pushed tree (git status -s empty), because remote-build.sh also ships dirty files. Write git rev-parse HEAD into the release PR body as the tested head; a shell variable does not survive until the tag. Every later fix or merge on the branch replaces it, and staging, the smoke and CI then run again on the new head.
• ./scripts/reloads.sh --tag rel-vX.Y.Z produces c11 STAGING rel-vX.Y.Z.app

(com.stage11.c11.staging), Release configuration, runs side-by-side with the operator's prod c11.

• To keep the Release build off the laptop, run it on Atlas instead:

./scripts/remote-build.sh --tag rel-vX.Y.Z --mode release runs the same reloads.sh there and returns the STAGING app (about 3 min on a fresh tag for v1.4.0). A fresh release worktree needs git submodule update --init ghostty vendor/bonsplit first, or remote-build refuses with "ghostty must be provisioned". Launch it on the operator's Mac yourself as soon as it is built or replaced, without waiting to be asked: env -i HOME="$HOME" open --env C11_QA_LAUNCH=fresh <app> keeps the startup dialogs closed. The env -i matters: open from inside a c11 terminal passes that shell's C11_SOCKET*, CMUX_SOCKET* and C11_PANEL_ID to the app, which then holds the daily c11's socket path. If a staging copy is already running, ask the operator before quitting it. Prune both Atlas caches for the tag afterwards (c11-hotload, Tag hygiene).

• Once the staging app is built and launched, write a spin script for it: one

bash file the operator runs inside a staging terminal (staging accepts socket commands only from its own terminals). It sets up a live demo of every changelog item through the bundled CLI: workspaces, panels, a local page and a Markdown panel of clickable links, a browser-automation step, a mail round trip with receipts. Each step prints what it did and what to click next. It refuses to run unless its socket is the staging socket, and --cleanup removes what it created. Hand the operator the one command to run it.

• Before handing off, screenshot the staging window and inspect every surface

the changelog touches (sheets, titlebar, sidebar, new or redesigned modals). Release-only layout regressions have shipped past Debug builds before.

• Hand off to the operator for a smoke pass against the changelog's

user-facing bullets. The smoke list should mirror what goes in the PR's test plan.

6.6. When staging surfaces a bug:

• Fix on the release branch. Commit. Push.
• Then choose explicitly:
• Rebuild staging (default when the fix touches anything timing- or

layout-sensitive — SwiftUI layout, animation, focus, paste, anything Release-mode could behave differently from Debug). The 0.47.0 New Workspace dialog regression was exactly this shape: dev/staging Debug masked a prod-only bug.

• Ship without re-test (acceptable only for trivial cosmetic / doc /

build-script changes AND only with explicit operator accept-the-risk).

• Don't drift past this decision. Default is rebuild; deviating is explicit.

6.7. Pre-build the release on Atlas, in parallel with staging and CI:

• Releases build and publish on Atlas, so the operator's Mac can sleep. Atlas's ~/c11-release is used only for those two runs (6.7 and step 10); commits, pushes, the release PR and its checks stay in your release-branch checkout.
• On Atlas (over ssh), check out the tested head detached, with submodules: cd ~/c11-release && git fetch origin release/vX.Y.Z && git checkout --detach <tested head> && git submodule update --init --recursive ghostty vendor/bonsplit. Then run C11_SIGNING_KEYCHAIN=$HOME/Library/Keychains/acetate-release.keychain-db scripts/release-local.sh --host local --dry-run vX.Y.Z there. --host local builds in place through the same admission slots as remote-build.sh. It builds the production app (cold, wholemodule, Apple silicon only, Xcode 26.3; about 6-7 minutes), signs it with the Developer ID from the release keychain, rehearses every step up to notarization, and keeps the build in build-release-local/vX.Y.Z/pristine for the real run to reuse.
• Run both Atlas commands in a login shell (ssh atlas 'zsh -lc "…"', escaping \$HOME): a plain ssh command lacks /opt/homebrew/bin, and preflight stops with missing tool: gh.
• The tree must be clean: a build that carried uncommitted files cannot be reused. Rerun 6.7 whenever the tested head changes.
• The pristine build keeps its dSYMs, so the real run can upload them to Sentry when SENTRY_AUTH_TOKEN is set there.
• Signing-keychain mode takes one launchd unlock lease of Atlas's release keychain and relocks it on every exit path. That keychain holds the Developer ID identity (team UKQ4QALWD4), the acetate-notary profile and the c11mux Sparkle key. Notarization uses c11-notary, else acetate-notary (C11_NOTARY_PROFILE picks one), and the log names the profile and team. Before the first release from a machine, run scripts/atlas-signing-check.sh and scripts/move-sparkle-key-to-atlas.sh --check from your own Mac, not from the Atlas shell: both drive Atlas over ssh, and Atlas cannot ssh to itself.

1. Create release PR:

• gh pr create --title "Release vX.Y.Z" --body "..."
• Include a concise changelog summary in the PR body.

1. Watch CI and resolve failures:

• gh pr checks --watch
• Fix failing checks, push, and wait for green.
• A conflicting PR gets no pull_request CI. If the release PR conflicts with main before tagging, merge origin/main into the branch, push, and repeat 6.5 through 8 on the new head.

The tag goes on the tested release-branch head, never on a merge into main. main keeps moving while a release is in flight: a commit that lands after the cut ships in the next release, and nothing forces a re-cut or a merge hold.