Redlamp Release

The release room

Every release happens in one canvas, the release room: what ships, its What's New, the checks, the problems, the owner's approvals and the plan that publishes it. It carries the next release from the moment one ships, so the owner can keep a chat open on it or start this skill at any time. Nothing in the release plan runs until the owner has approved the release.

Where

• The room: ~/.cursor/projects/<workspace>/canvases/release-room.canvas.tsx (<workspace> is the Cursor project folder for this repository, Users-pedrogomes-src-darkroom). One room for every release; it is never replaced, only brought up to date.
• Its template: template.tsx. Edit only the room object; the rendering code is shared. A change to the rendering goes into the template and the room together.
• Read ~/.cursor/skills-cursor/canvas/SKILL.md once per session before the first write. Link the room in every reply that changes it: [Release room](/absolute/path/release-room.canvas.tsx).
• The release copy: ~/src/redlamp-release, a worktree of this repository kept only for releases. The candidate's checks that need a checkout (every test suite, the regression suite, the dry run) and the release itself run there, never in the main checkout, which other sessions share. Put it on the commit being checked with git checkout --detach <commit>; it has the gitignored build inputs (AGENTS.md, A fresh worktree). If it's missing, make it with git worktree add --detach ~/src/redlamp-release origin/main and copy those inputs in.

The owner runs the release

The agent never runs mise run release without DRY_RUN=1: notarizing needs the owner's keychain and a connection to Apple that the agent's sandbox doesn't have, and publishing is the owner's act. When the plan reaches it, give the owner the exact line to run in their own Terminal, as a blocking Needs you item and in the chat, then verify what it did. Start it with caffeinate -i, so a Mac that sleeps or locks doesn't stop notarizing halfway; the notarize task reports any failure of notarytool history as a missing profile, so ask the owner to run xcrun notarytool history --keychain-profile <profile> to see the real error.

Every time: know where things stand

1. Read the owner's marks first. Needs you takes Done, Skip and Ask the agent (Done reads Approve on the approval). They are kept in release-room.canvas.data.json under needsYou as { "<id>": { "state": "done" | "skipped" | "asked", "at": "…" } }. Fold them into room as .cursor/skills/workstream-canvas/SKILL.md describes; never write that file.
2. Run scripts/release-status.py (--json for the details). Never take versions from memory. It reports:
   • the latest release (GitHub's Latest, or the newest v* tag) and the upcoming one, by mise run release's rule: Version.xcconfig on origin/main, or its next patch when that version is already tagged; the build number is the count of commits on main;
   • the commits on origin/main since the latest release, by tracker row, and those rows' statuses: a row with commits in the release that isn't Done ships part of a feature;
   • What's New on origin/main for the upcoming version; unmerged branches and unpushed commits on local main; open bug and in-app reports; CI's latest run on main; the tracker rows In progress or Blocked; the README's Known limitations.
3. Bring the room up to date in the same turn: upcoming (version, build, stage, summary, gate, base commit), scope, heldBack, whatsNew, checks, problems, needsYou, a log entry and updated. Say plainly what you didn't check.

Preparing a release

The stages are preparing, awaiting approval, approved, releasing and released. While preparing:

1. Scope. What's on origin/main ships; nothing else does. List each change in scope (user-facing or internal). Put whatever isn't on origin/main in heldBack (unmerged branches, unpushed commits on local main) and ask the owner which of them go in. Never merge or push another session's branch without the owner saying so. For each user-facing change, name the regression scenarios that cover it (packages/RedlampAutomation/Sources/Scenarios/); a change without one is a problem, fixed before approval, so the suite always covers what the release ships.
2. What's New. Offer the release's user-facing changes as candidates and let the owner choose (at most four, AskQuestion with several answers allowed). Write each chosen highlight in web/content/whats-new/<id>/ as web/README.md (What's New) describes, with a real screenshot of the app (apps/RedlampMac/Sources/DebugSnapshot.swift lists the capture commands), and show the owner captures of the window. A highlight is approved only when the owner says so; it is published once https://redlamp.app/api/whats-new serves it. It must be live before the release is, since 0.2.4 and later open it straight after updating.
3. Release notes. Offer the release's main changes and let the owner choose its highlights. Write them, plainly, in docs/releases/<version>.md (Highlights: then a bullet each); mise run release puts that file above the commit list in the GitHub release and the update window. It must be on origin/main before the release runs.
4. Checks. Run them on the release candidate: origin/main with whatever the owner put in scope merged. Each records its result, with counts and the commit, and the time.
   • Every test suite on this Mac (Redlamp-Workspace): it runs the GPU tests CI skips, so it is the one that counts. Read ProcessStabilityTests on its own: an existing edit that renders differently blocks the release.
   • CI on main (gh run list --branch main --workflow ci.yml). A failure that this Mac doesn't reproduce is a problem for the owner to decide, not a pass.
   • Lint and the repository's checks: mise exec -- swiftformat --lint ., scripts/check-engine-purity.sh, scripts/roadmap-sync.py --check, scripts/camera-list.py --check.
   • The site: cd web && npm test && npm run typecheck && npm run build.
   • The regression suite (README.md, Regression suite): mise run e2e -- --tier release in the release copy, on the candidate with nothing uncommitted, while no other session is building. About 15 minutes; it drives a test build of the app through every feature and writes report.md in build/e2e/<commit>-<time>/. Record its verdict, the counts (passed, flaky, failed), the claims covered, stalls, isolation and the storage section. mise run release accepts this report for the same commit rather than running the suite again.
   • A dry run in the release copy: REF=<candidate> DRY_RUN=1 SKIP_DMG="the agent's sandbox can't mount disk images" mise run release (signed, not notarized). Making and checking the disk image mounts it, which the sandbox refuses, so the agent's dry run leaves it out and the owner's release makes and checks it.
   • An update from an older copy: scripts/test-update.sh, which needs the owner to click Install Update.
   • Performance on a quiet Mac: scripts/perf-record.sh, against the last record (.cursor/rules/performance.mdc).
   • Trying the candidate: the owner's, as a Needs you item listing what to try.
5. Problems. Each failing check, each scenario the suite reports as flaky or each storage problem it finds, each partly shipped row, each open bug or in-app report that touches the release (the reports room lists them, and the fixes from reports the release brings), and any risk (unpushed work, a relay that isn't switched on, a feature that depends on something outside the app). Each takes the owner's decision: ship as is, fix first, leave out or later. The README's Known limitations go in as one row, with what's new among them.
6. Docs. The README (What works today, In progress, Known limitations), the tracker's statuses, scripts/roadmap-sync.py and the landing page's by-hand items (.cursor/rules/landing-page.mdc) say what the release brings.

Needs you holds only what the owner does or decides: the scope, each problem, What's New's copy, trying the candidate, and, always last and blocking, Approve the release. Move the stage to awaiting approval when everything else is settled. The owner's marks are kept by item ID, so each release's items carry its version in their IDs (scope-0.3.0, approve-0.3.0; the Approve button shows on any ID starting with approve), and a mark on one release never settles the next.