[JacobStephens2]

Summary

This Spec adds thirdshift release as a native Release run Command, scoped to JacobStephens2/thirdshift. It replaces scripts/release.sh, scripts/release-experiment.py and the hidden --release-summary shim; scripts/release-notes.sh stays for release-notes.yml.

• Without <version> (bare, or with --patch, --minor or --major) it runs as a Pass.
• With thirdshift release <version> it runs as a direct Command that cuts or resumes that version.

thirdshift release [<version> | --major | --minor | --patch] [--with-experiment] [--review]
  fences: Linux · not inside a factory Session · origin is JacobStephens2/thirdshift
  Pass admission: live Experiment / Quota wait → quiet skip (Activity log, dedup)
  ~/.thirdshift/release.lock + origin release reservation (outside the Command limit)
  recovery::discover                       # unfinished release-X.Y.Z / PR / unpublished vX.Y.Z
    machine-recoverable → resume or recut   # pushed branch, open non-draft PR, failed unpublished workflow
    human-blocked       → Pass skips / direct fails
  selection::candidate                     # newest green first-parent main commit with shipped paths
    pending main CI → waits; record live in Working, reachable by Stop
    all red → Pass skips / direct fails
  summary::select                          # one tool-less bwrap Session: minor|patch + notes (never major)
    failure → patch + generated notes outside the empty summary markers
  [--with-experiment] in-process Experiment against the last release tag
  bump commit (Cargo.toml + Cargo.lock only) → Release X.Y.Z PR (in-progress while live)
  wait for checks and mergeability (5-minute grace) · ≤1 targeted Fix run (--no-merge --no-base-fix)
  push vX.Y.Z → wait for release.yml → merge the bump PR → Done (or Needs you)

Around the command:

 Review run / Fix run Passes
+  skip release-* PRs into main (targeted `thirdshift fix <pr> --no-merge` still works)
 POST /api/v1/start, Console Start controls
+  release (version | bump, with_experiment, harness/email fields) behind admin scope
+  release --review stays CLI-only (ADR 0026 parity exclusion)
 Destructive-command signals
+  thirdshift release, git push --tags / refs/tags/
 .github/workflows/release.yml (generated)
+  release-tag-guard: github.actor == JacobStephens2 and the tag tree == main ancestor + exact version bump
+  processes/** in RELEASE_PATHS
 scripts/
+  setup-release-tags.sh   # Day shift wizard for the Admin-only v* tag ruleset
+  release-tag-guard.py
-  release.sh, release-experiment.py, release-summary.md

Whole-Spec review fixes (c950a6f):

• A resumed bump PR whose body still names its content base keeps its summary, including one edited with --review. Before this fix, every resume ran a new summary Session and overwrote the body.
• The --with-experiment pin is fetched from the run's own isolated repository by path, so the Launch directory's origin settings (uploadpack, sshCommand, credential helpers) never run.
• The pin is removed once release-X.Y.Z is on origin. An abandoned version no longer blocks every later Pass with "awaits its Experiment".
• Hints printed during the bump-PR wait (… then thirdshift release X.Y.Z) keep --with-experiment when the run used it.
• The manual now lists the Plan usage skip and says when a resumed summary is kept. Test changes: Console start requests use the 45-second helper, pending-CI waits use WAIT_BOUND, and the gh fake's unreachable --jq branch is removed.

Earlier review fixes (c98a51f): a Pass without --with-experiment never publishes a pinned version; a Pass waiting on main CI keeps a live record; release waits have their 5-minute grace; a failed summary leaves the markers empty; a refused Experiment prints per-suite results.

Tests sit at one seam, the thirdshift release binary run against a bare origin with fake gh and Harnesses (tests/release/, tests/experiments/release.rs), plus the Console API (tests/console/start.rs) and the workflow generator unit tests.

Closes #2054. This also resolves #336, and #653 for local-file reads. The remaining toolchain binds are tracked in #2230.

Evidence

Execution evidence

This host now has a C toolchain, so every run below was made here, directly.

• Before (HEAD df76d0f): the reviewers' tests, added to tests/release/native.rs and run with cargo test --locked --test release -- resuming_an_open_bump_pr_keeps release_experiment_pin_does_not_run an_abandoned_experiment_cut_leaves_no_pin (plus the two declined tests listed under Unaddressed findings):

  native::resuming_an_open_bump_pr_keeps_its_reviewed_summary_when_the_base_is_unchanged
    panicked: resume overwrote the reviewed summary: … <!-- release-summary:start -->\nRegenerated summary.
  native::release_experiment_pin_does_not_run_launch_repository_git_programs
    panicked: Release run executed the Launch directory's remote.origin.uploadpack
  native::an_abandoned_experiment_cut_leaves_no_pin_that_blocks_later_passes
    panicked: … Release run skipped: unfinished local release 0.2.0 awaits its Experiment; resume it with thirdshift release 0.2.0 --with-experiment
  

  cargo test --locked --test experiments -- native_release_resumes_its_experiment_and_refuses_an_unattended_inconclusive_verdict, with the new --with-experiment hint assertion:

  panicked at tests/experiments/release.rs:121:5:
  thirdshift: no release bump checks appeared at 89b23c78…; inspect GitHub Actions, then thirdshift release 0.2.0
  

  After (c950a6f): each of those commands gives test result: ok, with 1 or 3 passed and 0 failed.
• Release suite: cargo test --locked --test release gave 141 passed; 0 failed; 3 ignored at df76d0f and 144 passed; 0 failed; 3 ignored after the fixes.
• scripts/affected-tests refs/remotes/origin/main chose the full suite:
  • npm test --prefix site: PASS.
  • cargo build --locked: PASS.
  • npm test --prefix console: one failure, Fleet Inbox polls with page subscriptions, retains rows, and fits a phone, a 5-second locator timeout while the machine was loaded. On its own, node --test tests/fleet.test.cjs gives ℹ pass 2 ℹ fail 0.
  • The script stops at its first failure, so I ran its remaining steps by hand. python3 -m unittest discover -s scripts -p test_generate_release.py ran 10 tests, OK, and test_affected_tests.py ran 46 tests, OK.
  • Full Rust suite, cargo test --locked --no-fail-fast: 4648 passed, 2 failed and 207 ignored.
    • release experiments::repaired_content_waits_for_its_own_experiment_before_tagging timed out under full-suite load: Experiment at 520067a5… never reached waiting_on_rechecks. Run alone, it gives 1 passed, and the release suite on its own gave 144 passed.
    • plan_usage plan_usage_shows_configured_routes_in_order_and_omits_api_key_and_unused_harnesses asserts that agy is not installed, but this host has ~/.local/bin/agy. With that directory off PATH it gives 1 passed. This diff doesn't touch it.
• Other checks:
  • cargo clippy --locked --all-targets -- -D warnings: clean.
  • cargo fmt --all: applied.
  • cargo test --locked --bin thirdshift prompts_page: 14 passed.
  • npm run docs:check --prefix site: exits 0 after regenerating the manual.
  • python3 scripts/generate-release.py --check: exits 0 with a clean tree.

Visual evidence

The whole-Spec review fixes (c950a6f) change no rendered UI, so these captures, from the earlier round, still show the Console change.

Console Start work, signed in with full scopes, for a JacobStephens2/thirdshift Launch directory, with the machine name redacted to host.example. Before is the Base branch main at 864c1b8; After is this branch, with Start Release run opened.

Desktop 1440×900:

Mobile 390×844:

The hand-written site page changes are text only: release wording, the five-minute grace and the start-options scopes.

Review coverage

• This review covered the whole Spec branch, refs/remotes/origin/main...df76d0f1 (104 files). Each axis had one follow-up pass for files it had not read.
• Standards: read every changed file except the three generated paths below; that includes the removed scripts/release.sh in full.
• Spec: opened every changed file except the three generated paths below. It read some only in part:
  • removed scripts/release.sh lines 230-405, 470-590 and 720-1049;
  • tests/release.rs lines 1050-1799 and 1885-2199, read only as a test-name list;
  • tests/release/recovery.rs lines 60-150 and the tests/release/experiments.rs helpers, skimmed by name.
• Both axes excluded these generated paths and did not read them:
  • site/docs/index.html, generated from docs/guide.md; npm run docs:check --prefix site exits 0.
  • .github/workflows/release.yml, generated by scripts/generate-release.py with scripts/release-tag-guard.py; python3 scripts/generate-release.py --check exits 0. Both reviewers checked that its guard job gates plan, host and custom-publish-crates.
  • prompts/README.md and site/prompts/index.html, generated from src/prompt.rs and src/prompts_page.rs; cargo test --bin thirdshift prompts_page passes 14 tests. prompts/release-*.md were read directly.
• Changed files left unread: none.

Unaddressed findings

Standards

All of these are judgement calls under the smell baseline, with no documented standard behind them and no defect shown.

• Test #1, Spec: thirdshift, turn a GitHub issue into a ready-for-review PR unattended #2, Walking skeleton: a fresh run on the happy path #3, Pre-flight checks #16: Primitive Obsession and Duplicated Code (String versions, string workflow conclusions, merge-base ancestry checks, repeated Cut literals). These are refactors with no behaviour change, and the release suite pins the behaviour. They are left for an Architecture review rather than churned into this Spec's last pass.
• Pre-flight checks #4, LiveLabel vs review::reservation::Reservation. Reservation also owns the Review run's acquisition and stale-disposal rules (ADR 0014), which a Release run must not inherit. LiveLabel only adds and removes in-progress for ADR 0029.
• The Failed run path #5, the hard-coded repository in src/console/start_controls.rs:111. crate::release exists only on Linux (src/main.rs, #[cfg(target_os = "linux")] mod release;), while the Console builds on every platform.
• Continuation of an existing Issue branch #6, start scopes in three encodings. tests/console/start.rs (release_start_schema_exposes_pass_bumps_and_standard_options) checks the published OpenAPI x-command-scopes, x-scope and x-any-scopes. Unifying PageRoute scopes is a Console-wide refactor beyond this Spec.
• Numbered Issue branches after a merged or closed PR #7, Progress lines on stderr #10, flag arguments and the 7-parameter fix::targeted_at. These are judgement calls on existing interfaces this Spec extended.
• Keeping the PR mergeable: merge the Base branch and conflict Repair #8, part of it. The doc comment now sits on run, and Ok(None) is documented. The repeated --review and session checks are deliberate layers: main.rs refuses before Setup, as the Spec requires ("validated up front before expensive work"), and release::run guards the in-process entry used by the Console.
• #12a, THIRDSHIFT_POLL_MS=1. Raising it would slow every polling test in the suite. The waits are bounded by pending_polls and are not deadlines, so the Deadlines rule does not apply.
• #12c and #12e. The five live-wait loops differ in what they watch for, and the RELEASE_GRACE test is a one-line guard. Both are judgement calls.
• Make a command to read the thirdshift activity logs #14, two shipped-path lists. RELEASE_PATHS (scripts/generate-release.py:22) decides which PRs exercise release.yml. The Pass filter is the Spec's list of shipped paths, plus .cargo/ and askama.toml, which change the compiled binary. The two answer different questions, and docs/ci-performance.md names both.
• README, credit and install docs #15, rewritten historical docs, except the typo. The lower-case "the former…" in docs/research/eval-build-vs-buy.md is fixed. Restoring scripts/release.sh:NNN references would point at a file this Spec deletes.
• Print progress lines on stderr #18, the bump rule in Rust and in release-tag-guard.py. native_release_publishes_green_content_without_reading_the_launch_tree (tests/release/native.rs) runs scripts/release-tag-guard.py against the tag the Release run actually pushed, so the two implementations are checked against each other end to end, though on fixture manifests. A check against this repository's own manifests is a reasonable follow-up, but no drift exists today.

Spec

• Spec: thirdshift, turn a GitHub issue into a ready-for-review PR unattended #2, the Done row does not link the published Release. The reviewer's test fails on HEAD (Done row does not link the published Release: {… "pull_request":"https://github.com/JacobStephens2/thirdshift/pull/4" …}). This is already filed as Release run Done rows do not link the published GitHub Release #2228 (needs-triage): it needs a new public Command record field served through the Console API (ADR 0026), which is a Day shift decision. The test is left out of the branch and quoted in Release run Done rows do not link the published GitHub Release #2228.
• Pre-flight checks #4, the summary sandbox binds host toolchains. The reviewer's test fails on HEAD (summary Session read a host toolchain file). Filed as Release summary sandbox can read host toolchain directories #2230 (needs-triage), with the test. Narrowing the binds would break Harnesses installed through npm: harness_into binds only Kimi Code's package and relies on node from the bound ~/.nvm. Choosing between that, a per-Harness runtime bind and amending ADR 0013 is the Day shift's call. Cargo credentials stay blanked.
• The Failed run path #5, Passes skip when no route has Plan usage. This is not scope creep. ADR 0031 says "When every allowed route is unavailable, scheduled Passes skip without sleeping", and the Release Pass shares command_limit::early_skip with every other Pass. The undocumented part is fixed: the #releasing skip list now names Plan usage.

Security

• None. The one finding introduced by this change was fixed in this branch; see below.
• Fixed: an open fork PR named release-X.Y.Z blocked every Release run (low, introduced by this change).
  • Cause: recovery::inspect (src/release/recovery.rs) treated any open PR whose head is named release-* as a live unfinished release. That included a fork PR from any GitHub account, even when origin had no branch or tag for that version.
  • Proof: tests/release/native.rs an_open_fork_pr_on_a_release_branch_name_does_not_block_releases opens such a fork PR and then runs thirdshift release 0.2.0.
    • On HEAD before the fix it failed: "unfinished release 9.0.0 is live; finish it with thirdshift release 9.0.0 before releasing 0.2.0".
    • At the merge base, the same scenario against scripts/release.sh passed.
    • After the fix it passes, and it stays as a regression test.
  • Fix: a cross-repository PR counts only when origin already holds that version's branch or unpublished tag. A fork PR that shadows a real release branch is still refused (a_resumed_bump_pr_from_another_repository_is_refused).

Security review outcome

No unaddressed introduced findings.

Merge Danger

Door: two-way for the code. Each release a scheduled Pass publishes is a one-way door: tags on GitHub Releases are never moved.

Blast Radius: release pipeline.

• Merging enables unattended releases from main.
• The release.yml tag guard refuses tags not pushed by JacobStephens2 or not an exact version bump of a main ancestor.
• Review and Fix Passes stop touching release-* PRs.
• Console release starts need admin; /api/v1/start-options now accepts run or admin.
• The tag ruleset still has to be provisioned by hand with scripts/setup-release-tags.sh.

Tickets

• Fence release bump PRs, session tag pushes, and workflow tag publication #2156 done
• Tracer-bullet thirdshift release <version>: Release run Command, Console admin start, Cron jobs, and happy-path release #2157 done
• Scheduled Release Pass, shipped-path gate, and single-session minor / patch selection #2158 done
• Resume, targeted Fix recovery, unpublished-tag recovery, --with-experiment, and --review #2159 done
• Port release integration suite, retire legacy release script and summary flag, and update manual and site docs #2160 done

Built with claude 2.1.317 · claude-opus-5-5 · high

[JacobStephens2]

Delivery completed on agent-authored or reviewed head df76d0f.