Release Commit Procedure

When the user asks to prepare a release commit (e.g., "prep a commit for v217"), follow these steps in order. After a successful push, follow references/github-release.md for the GitHub release.

Preflight: nothing outstanding on GitHub (blocking, before step 0)

Run this from the release checkout (the repo root, on dev) before anything else, and again right before the push (python3 on macOS):

python dev/release_preflight.py

• BLOCKING: open Dependabot, code-scanning or secret-scanning alerts; draft or triage security advisories (private vulnerability reports); open Dependabot PRs; a red latest push-CI run of any workflow on main or dev; a failed third-party check on either tip; real commits on main that the release checkout lacks (a hotfix never merged back: merge origin/main in and push). A check it cannot run also blocks, so a failed API call never reads as "nothing open".
• WARNING: other open PRs, every open issue (tagged NEW since the last release), merged branches left on the remote.
• Exit 1 = STOP. Show the user every item. Each blocker gets resolved (a Dependabot PR merged only after its platform e2e run is green, or closed; alerts fixed or dismissed with a reason; hotfixes back-merged) or the user explicitly accepts it. Only then re-run with --ack "<key>", and only for keys the user named. Never ack on your own judgment.
• Report the warnings in the same message. List any acked items in the release commit body so the decision is on record.

Why: on 2026-09-11 embody.tools sign-in was down ~23h after a dependency bump (PR #105) and specimen submit had been broken 4 days by a rename; two hotfixes then sat on main without dev. The preflight keeps outstanding GitHub state from being skipped; the platform e2e gate is what catches a breaking bump.

0. Save the Project

The entire save call is project.save() -- no arguments. TD increments the .toe filename's trailing build, the onProjectPreSave hook in dev/embody/execute_src_ctrl.py bumps par.Version, deletes the prior release .tox, and exports the new one. Filename and par.Version stay in lock-step.

The release export honors pre_release/post_release hook DATs placed directly under the Embody COMP (none exist today; they fire on EVERY project.save, always in LIVE mode -- the Embody comp is never copy-staged, so such hooks would mutate the live comp). On any export failure the manifest is NOT written and the prior version's stale manifest is removed: a pre_release abort or save failure leaves NO release .tox for the new version, while a post_release failure leaves the fresh .tox WITHOUT a manifest -- check the log and release/ before pushing. The self-updater's rollback backup export passes run_hooks=False, so shipped hooks never fire in user projects during updates.

Don't pass a path (TD increments from your path's build, desyncing by one). Don't pre-set par.Version. Don't call ExportPortableTox directly.

The portable export captures LIVE DAT state, so a file landed just before a save can ship old (v6.0.133 palette_catalog, v6.3.1 two Convoy host DATs). onProjectPreSave reloads any synced DAT behind its file first and writes no tox if one stays behind; the upgrade leg's source_dats step compares the installed build against the repo, excusing only files changed after the commit that cut the tox.

If you've already mis-saved: rename the off-by-one .toe on disk to match par.Version, and do not save again -- the hook will delete the just-correct release .tox. The rename fixes git, not the session: a .toe keeps its own name, so the renamed file reopens under the OLD one (Embody-6.379.toe reopened as Embody-6.378.toe, 2026-10-26). Make the NEXT release save project.save('<dev>/Embody-6.<N-1>.toe'), where N is the build the new version belongs to: TD increments the number in the path it is given, so it writes N and the session is back in lock-step.

1. Audit All Changes

• Run git diff --stat and git diff HEAD --name-status to identify every changed, added, and deleted file.
• Read the diffs for all core source files (EmbodyExt.py, TDXNExt.py, EnvoyExt.py, etc.) to understand what was fixed/added.
• Read diffs for new test files to understand coverage additions.
• Read diffs for docs, schema, and rule/skill files.

1b. Docs Audit: every change in this release is documented

The changelog says a release HAPPENED; docs/ is what users read to USE the thing. A feature or a behavior change that ships with only a changelog bullet is undocumented -- and the drift is invisible, because nothing fails.

Walk the release diff (step 1) and, for EVERY user-visible change, name the docs/ page that now describes it. Not "does a page exist" -- does the page say the new truth.

Mechanics:

• git diff HEAD --name-status -> for each source file, ask what a USER could observe. If the answer is "nothing", write that down; if it is anything else, the docs edit is part of THIS release, not the next one.
• Grep before you write: grep -rn "<old behavior phrase>" docs/ finds the copies that would otherwise go stale. Fix all of them.
• New page -> add it to mkdocs.yml nav, or it ships invisible.
• mkdocs build --strict must pass (broken internal links are errors). It proves the page BUILDS; step 7 is what makes it PUBLISHED.
• Docs written in this pass are part of the release commit, so the changelog bullet and the page land together.

Report the audit as a short list -- "changed X -> documented at docs/...", "changed Y -> internal only" -- so a skipped obligation is visible rather than implied.

2. Update Changelog

Add a new entry at the top of docs/changelog.md:

## v5.0.XXX

One-line summary of the release themes.

- **Feature/fix name.** What changed, in 1-2 sentences.
- ...

Length is a hard cap (standing user directive)

One line of theme. 3-5 bullets, one to two lines each. Under ~160 words.

Nobody reads a wall of bullets, and an exhaustive one reads as AI slop. Twelve changes still get <= 5 bullets: group by theme, and give the leftovers one combined Fixes. bullet rather than a bullet each. The detail lives in the commit log and the diff.

But too short is also wrong -- do not drop a user-facing feature to make the count. A shipped tool, a new install path or a fixed crash each earn their line; only internals get cut. A small release can be one bullet (v6.0.250 in docs/changelog.md is the model); a big one uses all five.

Unreleased intermediate versions fold into the published entry. project.save() bumps the version on every save, so most numbers never ship. Consolidate the whole tag-to-tag range (git log <lasttag>..HEAD) into the one entry -- and never leave a shipped feature out of it because it landed under a version that was superseded.

Always cut:

• incident stories, repro narratives, root-cause retelling
• internal mechanisms -- protocol shapes, private names, fallback ladders
• a superseded version, beyond one short parenthetical
• test counts, beyond +N tests folded into a bullet

Then COUNT. Over 5 bullets or ~160 words, cut before shipping -- never ship long and offer to trim after.

3. Update README.md

• Version badge + minimum-build statements are AUTOMATED: project.save() (via execute_src_ctrl.updateVersionDocs) rewrites the README version badge from par.Version and the minimum-TD-build lines in README.md, docs/index.md, and CONTRIBUTING.md from the running app.build (the build we save with IS the support floor). Verify they match rather than editing by hand; the test_version_sync suite fails on any drift.
• Release history: Add a one-line entry at the top of the "Recent releases" list.
• Test suite count: Update the count if new test files were added (count dev/embody/unit_tests/test_*.py).

4. Verify Template Sync

When updating a rule or skill in .claude/, also update the corresponding template DAT in dev/embody/Embody/templates/ if one exists. This applies on every edit, not just at release time -- drift between source and template ships stale guidance to user projects.

Templates in dev/embody/Embody/templates/ must stay in sync with their .claude/ counterparts:

This table is the source of truth for what ships; keep it in sync with _TEMPLATE_MAP_RULES / _TEMPLATE_MAP_SKILLS in EmbodyExt.py (the actual shipping map). Template files that exist on disk but are NOT in that map (e.g. text_rule_commit_push_checklist.md, text_rule_github_release.md, text_rule_refresh_after_commit.py) are orphans -- do not add them here.

Templates should be UTF-8 with LF line endings and no BOM. Each template carries an Embody/Envoy generated-by HTML comment, and otherwise must match its .claude/ counterpart in content -- diff them (normalizing any legacy BOM + line endings) and fix any drift.

Dev-only rules and skills (e.g. .claude/rules/commit-push-checklist.md, .claude/rules/skill-prerequisites.md, .claude/rules/code-brevity.md, .claude/rules/multi-agent-review.md, .claude/rules/destructive-tests.md, .claude/rules/embody-code-conventions.md, .claude/rules/refresh-after-commit.md, .claude/skills/release/ (this skill, incl. references/github-release.md), .claude/skills/agent-tests/, .claude/skills/add-mcp-tool/, .claude/skills/run-tests/) live under .claude/ for Embody developers only and are NOT shipped to user projects -- they have no template counterpart. The root CLAUDE.md and dev/embody/Embody/templates/text_claude.md serve different audiences and are maintained independently.

4b. Re-Vendor the Convoy Host App

The Convoy host-app daemon exists TWICE on purpose: the source of truth in dev/convoy/, and a vendored copy at dev/embody/Embody/convoy/host/ carried inside the .tox as text DATs so that installing works with no network access. If the vendored copy is stale, the release ships an installer that writes an OLD daemon -- and nothing about the running project looks wrong.

python dev/convoy/vendor_host_modules.py --check    # exit 1 = drift
python dev/convoy/vendor_host_modules.py            # re-vendor, then SAVE

The vendored DATs are syncfile=True, so copying the file is the whole re-vendor -- TD reloads the DAT on its own. The new content only reaches the shipped .tox on the next project.save(), so re-vendor BEFORE step 0's save, never after.

--check reports four drift classes; only the first is fixed by copying:

test_convoy_host_vendor.py asserts the same thing on the CI matrix, comparing newline-normalized text (Embody writes CRLF on Windows; .gitattributes stores LF, so the committed bytes are identical). Do not "fix" a CRLF diff by changing how Embody writes files -- that path is shared by every externalized DAT in the project.

Note convoy_install.HOST_MODULES is a hardcoded manifest and has gone stale twice already. It is not the gate; the parity test is. If you add a daemon module, the test tells you what else to do.

5. Fresh-Install Smoke (before the release commit)

Cold-open smoke of the DEV project is not enough: a fresh install runs a different path (the shipped .tox in a virgin project -- init() lifecycle, baked par values, no dev checkout, no externalized files). The v6.0.145 empty-Update-Status miss shipped precisely because this step was skipped.

Run it after step 0's save (it reads the manifest that save wrote), from the repo root -- one command, same on Windows and macOS:

dev/.venv-tests/Scripts/python.exe dev/release_testing/smoke_run.py

(python3 dev/release_testing/smoke_run.py on a CI runner.) Options: --tox, --td, --out (default RUNNER_TEMP or the system temp dir; it REFUSES a path inside the repo), --timeout, --no-mcp, --keep-td.

It takes the .tox that release/embody-release.json names and refuses on a sha256/size mismatch (never a directory glob); stages a fresh <out>/embody-smoke/<platform>-<timestamp>/ with the template, the bootstrap and a smoke_run.json sidecar; launches TD by absolute path; waits for ready.flag, then features.flag (both written INTO the run dir, and ready.flag stamps run_id / platform / tox); probes MCP over HTTP; quits only the TD it launched. It deletes nothing.

PASS reads ready PASS, features 7/7, every MCP step ok, last line result: PASS. Exit 0 all PASS, 1 a verdict failed, 2 could not run (no TD, bad manifest, no flag by the deadline) -- a 2 is never a green. Evidence: result.json in the run dir (its path ends the summary), beside ready.flag and features.flag.

The release gate is the full command, not the bare smoke:

dev/.venv-tests/Scripts/python.exe dev/release_testing/smoke_run.py --legs upgrade,faults,uninstall

--legs runs three more legs against the same smoke TD after the MCP probe (always in that order; dev/release_testing/smoke_legs/): upgrade installs the PREVIOUS release first (from git history by tag, or --upgrade-from) and drives its self-updater to the build under test, rolls back to the updater's backup and updates again; faults breaks the venv interpreter, the port, the server socket and the instance registry and proves each self-heal from the logs; uninstall removes Embody the way a user does and checks what is left. PASS then also reads upgrade PASS, faults PASS, uninstall PASS in the summary; a failed leg is exit 1 with the failed step named. Nothing has been release-smoked until all three legs pass on BOTH machines (v6.2.57 shipped with only the bare smoke -- the legs were still being built).

The Convoy leg installs and starts the REAL per-user Convoy host app on the machine that runs it (on a machine that already has it, the summary says host app reused -- the install path was not exercised). Run the same command on the Mac (TEC-MBA: git pull --ff-only origin dev, then python3 dev/release_testing/smoke_run.py); first verified there 2026-09-18 on the default port, teardown via Envoy.

In CI, .github/workflows/release-smoke.yml runs the macOS leg on the TEC-MBA self-hosted runner on every push to dev/main (and tags) that touches the release asset, the harness or Embody's source; the run directory is the uploaded artifact. The preflight treats a red run as a blocker, so check gh run list --workflow=release-smoke.yml -L 3 before the release push. A job that sits queued while the runner flaps online/offline is the Mac's network (a dead WireGuard tunnel did this on 2026-09-18), not the smoke.

5b. Live Product Check -- MANDATORY before ANY readiness or confidence claim

Green tests and a green smoke are NOT the product. On 2026-09-05 a full in-TD run (4245/4369), smoke 7/7 and an MCP probe 9/9 were all reported as "high confidence" while the dev instance's Convoy sat at Install failed -- see log with 0 nodes -- visible in the Embody panel the whole time. Dylan found it by looking. Never again: no sentence containing "confident", "ready", "green" or "release" is written until every row below has been read from the LIVE dev instance AFTER the last test run, save, or smoke -- test runs and smoke instances mutate this state. For a release, the smoke instance's rows come from its run directory instead (result.json, ready.flag, features.flag): step 5 quits that TD, so those files are the only evidence left.

Any row red = NOT ready. Fix it or say so first; a confidence claim with a red row is the failure mode this step exists to end.

6. Stage and Commit

• Stage all changed, added, and deleted files explicitly (avoid git add -A).
• Include new .toe and .tox files; include deletions of old versioned .toe/.tox files.
• Commit message format:

  Embody vX.Y.Z: <comma-separated themes>

• Add any preflight items the user accepted (--ack) to the commit body.
• Do NOT push unless the user asks. Re-run the preflight immediately before the push; it must exit 0.

7. Publish the Docs (main only)

The changelog entry from step 2 -- and every other docs/ edit in the release -- is invisible to users until it reaches main. .github/workflows/docs.yml triggers on a push to main touching docs/** or mkdocs.yml; a commit sitting on dev deploys nothing.

When the user asks to push a release:

1. Push dev, then merge dev -> main and push main (the same flow the earlier Merge pull request commits used).
2. Verify the deploy actually ran: gh run list --workflow=docs.yml -L 3. A queued or failed run means the site still serves the previous version.
3. Confirm the published page, then report the URL. Until then, describe the state accurately ("committed, not yet deployed") rather than linking as though it were live.

git log origin/main..HEAD --oneline -- docs/ mkdocs.yml lists doc commits that have not reached main yet -- run it against origin/main, since a local main branch can be many commits stale and makes the gap look larger than it is.

The push also triggers CI (bridge-tests, Actions Security). Watch EVERY triggered run to green and auto-remediate failures per .claude/rules/commit-push-checklist.md (After Pushing) before reporting the deploy done -- a deploy is not finished with a red run on either branch.

This step is NOT release-only: the same chain applies to any standalone docs fix. See .claude/rules/commit-push-checklist.md (Documentation Audit).