McRitchie Studio

DESIGN LOCKED (2026-06-22 w/ Mr. McRitchie): McRitchie Studio = ecosystem DevOps hub; releases span ALL repos, NO per-app lanes; conductor producer-first (gems->apps). D1: gems publish at PROD ship; consumers BRANCH-reference the gem pre-publish so gem-dependent feature work + QA are NOT blocked; conductor AUTO-REPINS consumers to ~> x.y + bundle + commit at ship (automates this session's manual repin). D2: every customer-facing app has a QA env (qa.turfmonster.media, qa.mcritchie.studio); hub QA-deploys via bin/qa-server -> qa.<app>, prod via each repo's own recipe (turf bin/deploy, mcr push heroku). SEQUENCING: build AFTER gems-first #82 (task-1c92c482df6e) merges — this extends that registry/member-kind/producer-first substrate, not a parallel rework. DEPENDS ON task-1c92c482df6e.

ARCHITECTURE (Plan pass): thin bin/release shell + all logic in testable models. Key pieces: (1) config/release_repos.yml apps list -> HASH with per-app prod_deploy adapter (mcr: git_push_heroku; turf/tax/chain: repo_script -> bin/deploy --yes). QA already multi-app via bin/qa-server (resolves siblings). (2) Release::Conductor.repo_plan = member_plan grouped by repo, producer-first, w/ release_branch+qa_app+prod_deploy. (3) Per-repo release branches cut in the PRIMARY sibling checkouts (/Users/alex/projects/<repo>), driven by git -C. (4) Release::GemfileRepin (pure) — rewrite consumer Gemfile github-branch ref -> ~> x.y, idempotent; ship runs it AFTER gem publish, BEFORE that consumer deploys. (5) repo-aware eligibility (reject :unknown repos); --prod becomes default (warn on local DB); board shows deploy target. DECOMPOSED into 4 PRs: (a) registry+repo_plan+eligibility+GemfileRepin [pure, building now]; (b) per-repo prepare branches+QA; (c) multi-repo ship + gem auto-repin; (d) --prod default + eligibility warn + board deploy-target. Seq a->b->c, d parallel after a. OPEN DECISIONS for operator: #1 who sets the pre-publish branch ref (build-time convention?); #4 single Release.qa_url/production_url cols vs N repos (v1 derives per-repo from registry); #5 multi-repo ship is NOT atomic across Heroku+RubyGems -> producer-first + abort-on-first-failure + idempotent re-run (biggest risk).

BRANCHING-MODEL CHANGE (Mr. McRitchie, decision #3) — adopt a PERSISTENT 'release' branch per repo. Feature agents PR INTO 'release' (not main); 'release' deploys to QA; ship = ff 'release' -> main -> prod. This SUPERSEDES the ephemeral release/<slug> + per-member-merge model phases (a)/(b) built: prepare becomes 'deploy each repo's release branch to QA' (members already integrated via their PRs into release); ship becomes 'ff release->main + per-repo prod deploy'. IMPACT: re-plan phase (c) around it; lightly revise phase (b) prepare (drop per-member merge); UPDATE ALL DOCS so future agents PR to 'release' (AGENTS.md, CLAUDE.md adapter, devops-cycle-design.md, worktrees + PR/kickoff guidance) — docs MUST land WITH the conductor change to avoid drift (don't tell agents to PR to release before the conductor deploys release). Gem caveat persists: consumers branch-ref the gem during QA, repin to the published version at ship (publish-at-prod). Phases (a)/(b) already merged on main remain valid building blocks (registry, repo_plan, GemfileRepin, repo_path) — the change is the prepare/ship orchestration + the branch convention.

RE-ARCHITECTURE (Plan pass, release-branch model). CORE INVERSION: integration moves from conductor-pulls (prepare cuts release/<slug> + merges members) to feature-pushes (members land on the persistent per-repo 'release' branch via their own PRs, base=release). So: prepare stops doing git surgery (just deploys origin/release to QA); membership flips reviewed->assembled AT MERGE (new Release::Conductor.adopt! wrapping gh pr merge --base release + Release.add); 'release' is permanent (main always ancestor), collapses to main on ship's ff, re-accumulates after. DECOMPOSITION (a+b merged stay valid building blocks): PR1 = convention + membership-at-merge + revised prepare (deploy origin/release) + bin/release init (create release branches) + ALL docs/UI (PR-to-release); PR2 = per-repo ship (gems->hub->satellites, publish + auto-repin + partial-ship + test_cmd gate, ship the QA-frozen SHA); PR3 = bin/agent-worktree base cutover (branch+PR base=release, gates vs release); PR4 = --prod default + board. RESOLUTIONS (adopting plan recs): branch+PR base = origin/release; membership-at-merge (add auto-reopens an assembled release on a late merge); ship the SHA recorded at prepare (release.metadata qa_shas) NOT release HEAD (no un-QA'd ship); hub-first app ordinal; skip conductor test_cmd/smoke for repo_script apps (turf self-gates); enforce PR base=release. JUDGMENT CALLS for operator: abandon! protocol on a durable branch (revert-merge -m1 vs reset-to-main+re-merge keepers); migration/cutover (create release branches per repo via init; land PR1 only when Release.current is nil; retarget any open main-based PRs --base release). Gem registry needs a gem->consumers mapping for auto-repin.

CUTOVER COMPLETE 2026-06-22 — multi-repo conductor + persistent-release model LIVE on mcritchie-studio prod v85 (app.mcritchie.studio /up 200). Sequence: drained #76/#83/#86 -> merged PR1 #87 (conductor+prepare+init+docs, f138364) -> merged PR2 #89 (multi-repo ship, e96cb12) -> regenerated root AGENTS.md/CLAUDE.md (team now PRs into release) -> bin/release init created origin/release on 5 repos (studio-engine, solana-studio, mcritchie-studio, turf-monster, chain-ops; tax-studio deferred, not cloned) -> deployed prod v85. Full suite 961/0 gated the deploy. REMAINING (separate tasks): PR3 bin/agent-worktree --base release default + qa-intake; PR4 --prod default + board deploy-target (task-7ab627d488df); tax-studio release branch when cloned; gem frozen-SHA in prepare; first real multi-repo production ship.