0.3.x design spec: release, distribution, isolation, and upgrade

[jasonhnd]

Status: doc-first DESIGN issue. Deliverable is one design spec document only --
no Go code, no .delivery.yml change, no command behavior change. Implementation
is filed as separate code issues only after this spec merges (docs/PROCESS.md).

Deliverable

Write docs/specs/0212-release-distribution-and-upgrade.md (this is issue
#212) with the standard YAML frontmatter:

---
id: 212
title: Release, Distribution, Isolation, and Upgrade
status: draft
date: 2026-06-28
issue: 212
pr: null
supersedes: []
superseded_by: []
---

English only.

Context

loopcoder must be adoptable by many users across many machines, installed and
upgraded through standard tooling -- never hand-copied. The maintainer develops
loopcoder using loopcoder (self-hosting). Define the permanent, canonical design
for (1) how a version is released and distributed, and (2) how development and
upgrades work across multiple co-located and remote projects without conflict.

Required design decisions to capture (document these; do not re-derive)

1. Source of truth = GitHub Releases. Tag -> CI builds cross-platform binaries
   (win/mac/linux x amd64/arm64) + SHA256SUMS + a signing path (cosign/minisign)
   as release assets. No machine-to-machine copying.
2. Two tracks: ONE world-facing stable release line consumed by all consumer
   projects/users; plus the maintainer's local dev source build (the only special
   case). The maintainer's own consumer projects install the published release
   like everyone else.
3. Install without Go: an install script (unix curl|sh, Windows irm|iex) that
   fetches the right asset into ~/.loopcoder/bin and onto PATH, with --version;
   plus go install ...@vx; package managers later.
4. Self-upgrade: loopcoder upgrade [--version] queries GitHub Releases,
   downloads + checksum-verifies, atomically swaps the binary (handle the Windows
   running-exe case), and refreshes the bundled playbook. This is the mass-upgrade
   path.
5. Bundle the conductor playbook (SKILL.md + skill files) INSIDE the binary via Go
   embed; loopcoder skill install / loopcoder init write the version-matched
   playbook to the Claude skill dir and the Codex AGENTS entrypoint. "A version" =
   one artifact; binary and brain never skew.
6. Multi-project isolation: a ~/.loopcoder/ home (versioned binaries + stable
   playbook copy); per-project binary selection via the existing LOOPCODER_BIN
   resolution; per-repo .delivery.yml / .loopcoder / worktree / state-branch /
   lease / worktree-lock already isolate delivery state (the worktree lock is keyed
   by canonical repo path). The dev repo pins its own go build binary plus its
   own in-repo playbook (a separate loopcoder-dev skill), never a junction that
   mutates the global stable skill.
7. Version and compatibility: .delivery.yml version (existing) + a new optional
   min_loopcoder_version; loopcoder doctor checks compatibility and reports the
   project's track/version; a semver-based stability policy for .delivery.yml
   schema, CLI flags, and label names within 0.x, with migration guidance.
8. Prerequisites and integrity: the conductor runtime (Claude Code or Codex) is
   not shipped by the release; doctor checks for it and for provider CLI auth.
   Every release publishes checksums (+ signing) so downloads can be verified.
9. Multi-machine: identical mechanism everywhere -- each machine independently
   installs/pins/upgrades from GitHub Releases; no consumer machine is special.

Also document (process, permanent in the repo)

• How to release a version (maintainer runbook): tag -> CI build/sign/publish ->
  verify assets -> consumers loopcoder upgrade. Step by step.
• The self-hosting development model (how all future development is done):
  doc-first (spec merges before code); worker-driven (the conductor dispatches one
  worker per issue, an independent verifier reviews, the human merges); two-track
  dev/stable isolation; and the self-modification guard for load-bearing code
  (smoke-check merged binary/playbook changes before relying on them in the same
  run).

Constraints

• English-only repo artifacts. doc-first: this PR adds the design doc ONLY.
• One concern per PR; no code or .delivery.yml change here.
• Cross-platform Go, no new runtime dependency in the eventual implementation.
• Human-merge gate stays; model/effort inherit-by-default; reviewer-not-worker.
• Follow docs/specs frontmatter + docs/reference living-doc conventions (spec 0165).

Acceptance criteria

• One spec file docs/specs/0212-release-distribution-and-upgrade.md with
  valid frontmatter (status: draft).
• Captures decisions 1-9 plus the two process sections.
• Lists the follow-on code issues it will spawn (release workflow; install script;
  upgrade; embed playbook + skill install/init; ~/.loopcoder home + pin; doctor +
  version/min-version; stability policy), in dependency order, without implementing
  them.
• No Go code, no .delivery.yml change, no new runtime dependency.

Dependencies

None blocking (this is a design doc). It is a 0.3.x peer of specs 0192
(guardrails) and 0194 (loopreview).