fix(release): close the blind-run 16-18 gaps -- back-fill floor, run-pre-tag diagnosis, apply-bump

[SUaDtL]

Summary

Closes the open findings from blind agent-judgment runs 16-18 against the release skill (issues #585, #584, #583).

• _tree_state()'s internal probe now carries the same audit-scratch exemption (:/ + ,top exclusions for gate-events.log and .markers/) the release skill already requires everywhere an agent runs the check by hand, so a mid-window log append is no longer read as a mutating pre-tag command (release lane: four portability/diagnosis gaps below HIGH from blind exercise run 17 #584 MEDIUM-1).
• run-pre-tag now distinguishes four outcomes instead of two: exit 5 (a command RAN and reported drift), exit 6 (a command MUTATED the tree), new exit 7 (a command's interpreter/program could not be located at all -- NOT drift, no discard needed), and new exit 8 (the tree-state probe itself failed -- no verdict about any command exists) (release lane: Back-fill's first release cannot clear step 3, plus six lesser gaps (blind run 18) #585 MEDIUM-2, release lane: four portability/diagnosis gaps below HIGH from blind exercise run 17 #584 MEDIUM-1/MEDIUM-3).
• Every declared pre-tag command now runs with PY set to this process's own resolved interpreter, so a row may portably spell "$PY" instead of a hardcoded interpreter (release skill: three portability gaps below HIGH from blind exercise run 16 #583 MEDIUM-2, release lane: four portability/diagnosis gaps below HIGH from blind exercise run 17 #584 MEDIUM-3).
• New apply-bump <base> <word> subcommand mechanizes the version-bump arithmetic that was the release lane's last by-eye step; refuses none and any non-major/minor/patch word (release lane: Back-fill's first release cannot clear step 3, plus six lesser gaps (blind run 18) #585 MEDIUM-3).
• first_release_baseline already took the oldest of several additions (git log prints newest-first, the function takes the last line) -- pinned with an additional CLI-level two-file test.
• SKILL.md prose:
  • Floors the first-release footer check on the earliest addition of CONTEXT.md OR release-targets.md, so a Back-fill consumer's own first release can clear Phase 1 step 3 (release lane: Back-fill's first release cannot clear step 3, plus six lesser gaps (blind run 18) #585 HIGH).
  • Checks the $REBUILD subshell's own exit code before trusting any freshness assertion (release lane: Back-fill's first release cannot clear step 3, plus six lesser gaps (blind run 18) #585 MEDIUM).
  • Documents exit 7/8 in the 6d and Phase-1-gate exit-code prose (release lane: Back-fill's first release cannot clear step 3, plus six lesser gaps (blind run 18) #585 MEDIUM-2, release lane: four portability/diagnosis gaps below HIGH from blind exercise run 17 #584 MEDIUM-3).
  • States the declared-command PY portability contract in "Targets" (release skill: three portability gaps below HIGH from blind exercise run 16 #583 MEDIUM-2, release lane: four portability/diagnosis gaps below HIGH from blind exercise run 17 #584 MEDIUM-3).
  • Rekeys the CONTEXT.md default-branch fallback on the FACT being unresolvable rather than the FILE being absent (release lane: four portability/diagnosis gaps below HIGH from blind exercise run 17 #584 MEDIUM-2).
  • Hardens the python3 App Execution Alias probe to actually run it, not just resolve it (release lane: four portability/diagnosis gaps below HIGH from blind exercise run 17 #584 LOW).
  • Adds git fetch --tags before LAST_TAG resolution (release lane: Back-fill's first release cannot clear step 3, plus six lesser gaps (blind run 18) #585 LOW).
  • Spells the one sanctioned multi-valued-field split (release lane: Back-fill's first release cannot clear step 3, plus six lesser gaps (blind run 18) #585 LOW).
  • Fixes a stale $REBUILD cross-reference and two LOW wording items (release lane: Back-fill's first release cannot clear step 3, plus six lesser gaps (blind run 18) #585 LOW, release skill: three portability gaps below HIGH from blind exercise run 16 #583 LOW).
• Version bumps for the payload changes above: ca 2.11.2, ca-codex 0.4.1, ca-pi 0.2.1 (root package.json regenerated via ca-pi's declared generate command, never hand-edited). README badge, README's "currently ships ca-codex X.Y.Z" line, and ca/ca-pi CHANGELOG top sections updated to match and verified against check_badge_consistency.py, site/test/content/readme-professional.test.ts, and test_release_trace.py.

Deliberately NOT included: Part 3 (rewriting .codearbiter/release-targets.md's hardcoded python3)

The spec asked for this repo's own declared rows (ca's three pre-tag entries, ca-pi's generate and pre-tag) to be rewritten from hardcoded python3 to "$PY". Measured before making that edit:

run-pre-tag executes declared commands via subprocess.run(command, shell=True, cwd=project_root). On Windows, shell=True always dispatches through cmd.exe (via COMSPEC), regardless of what shell launched the outer Python process (git-bash, PowerShell, or otherwise) -- this is a CPython subprocess module behavior, not a host configuration. cmd.exe does not perform $VAR-style expansion, so a declared row spelled "$PY" is passed to cmd.exe as the literal string "$PY", which is not a recognized command.

Verified end-to-end on this Windows 11 host: a declared pre-tag command "$PY" --version (with PY correctly exported into the child's environment) returns '"$PY"' is not recognized as an internal or external command and exit code 1 -- not one of the new exit-7 codes (126/127/9009), so it would be misdiagnosed as exit 5 ("ran and disagreed"), exactly the anti-pattern this whole issue cluster exists to close. Meanwhile this repo's currently-hardcoded python3 actually resolves and runs correctly via cmd.exe on this host (a real python3.exe, not just an App-Execution-Alias stub). Making the row-rewrite change as specified would therefore regress this repo's own release lane on the exact host used to develop and maintain it, while doing nothing to fix the Windows-cmd.exe case Part 3 also doesn't address (a hardcoded-python3-only host with no bash and no python3 still fails, just under a different, now-correctly-diagnosed exit code).

This is a structural gap in the "$PY"-for-declared-commands design itself (1d/2g), not a row-authoring mistake: run-pre-tag's subprocess.run(shell=True) needs to dispatch declared commands through a POSIX-compatible shell on Windows (e.g. executable=<path-to-bash>) before row authors can safely follow the "$PY" convention Part 3 asked for. I've left this repo's release-targets.md untouched and recommend filing this as a follow-up issue before Part 3 is attempted again. Everything else in the spec (1a-1g, all of Part 2's prose, Parts 4/5/6) is otherwise complete and independent of this gap.

Follow-up commit on this branch: the first commit shipped the "$PY" recommendation in run-pre-tag's exit-7 remedy text and in SKILL.md's interpreter-convention prose without this Windows caveat -- i.e. it told every consumer to do the thing just measured as broken here, on the exact platform the surrounding prose names as its intended beneficiary. A second commit (fix(release): stop recommending "$PY" on the platform it breaks) corrects both: the exit-7 stderr and SKILL.md's "Targets"/6d prose now state explicitly that "$PY" is safe on a POSIX-hosted row and NOT yet safe on a Windows-hosted one, with the same measured explanation as above. Prose/message-only change; the 357-test suite is unaffected.

Mutation-proof table

Every new test was shown to FAIL against the unfixed code (temporarily reverted the specific change, ran the test, observed failure, restored):

Test	What was broken	Observed failure
test_run_pre_tag_exempts_a_mid_window_gate_events_log_append	Reverted _tree_state()'s probe to bare git status --porcelain (no exemption)	6 != 0, BLOCK on the gate-events.log append
test_run_pre_tag_exports_PY_to_declared_commands	Removed env={**os.environ, "PY": sys.executable} from the declared-command subprocess.run	5 != 0, the check command exited 1 (no PY in env)
test_could_not_run_recognizes_only_the_documented_codes	_could_not_run hardcoded to return False	126/127/9009 subtests all failed (expected True)
test_run_pre_tag_exits_7_when_a_declared_command_could_not_run	Same _could_not_run mutant	5 != 7, missing "COULD NOT RUN"/"NOT drift" in stderr
test_run_pre_tag_exits_8_when_the_tree_state_probe_fails	Reverted the baseline-probe-failure return 8 to return 6	6 != 8
test_apply_bump_patch_minor_major / test_apply_bump_cli_prints_exactly_the_version	Broke the major arithmetic (f"{major}.0.0" instead of f"{major + 1}.0.0")	'2.0.0' != '3.0.0'
test_apply_bump_refuses_none_and_nonsense_words / test_apply_bump_cli_exits_2_on_none_nonsense_or_bad_base	Removed the word not in _BUMP_WORDS check	none/nonsense silently bumped to '2.3.5' instead of refusing -- confirms the word-check is load-bearing, not vacuously covered by the CLI's generic bad-invocation arm
test_apply_bump_refuses_a_non_semver_base / same CLI test	Added a or _PLAIN_SEMVER_RE.fullmatch("0.0.0") fallback	not-a-version silently resolved to '0.0.1' instead of refusing
test_adoption_commit_cli_two_file_pathspec_prints_the_oldest_addition	Changed first_release_baseline's shas[-1] to shas[0]	'bbbbbbb' != 'aaaaaaa'

Test plan

• .github/scripts/test_release_lib.py: 346 -> 357 tests, all passing (346 before any new tests; +11 new tests)
• .github/scripts/test_release_trace.py + .github/scripts/test_build_surface.py: 69 passing
• plugins/ca/hooks/tests (NO_COLOR unset): 1580 passing (excludes two files with a known, pre-existing, unrelated worktree-environment artifact -- same failures reproduce on unmodified origin/main in this worktree)
• tools/sync-core.py --check and tools/build-surface.py --check: both pass
• payload_version_gate.py for ca and ca-codex, build-host-packages.py --check --release-guard-base origin/main for ca-pi: all pass against the committed HEAD
• check_badge_consistency.py, check_command_catalog.py: pass
• site/test/content/readme-professional.test.ts + full site suite (512 tests): pass
• git diff --check: clean, no CRLF

Closes #585
Closes #584
Closes #583

https://claude.ai/code/session_01QjJeSbcwPHwMmd6CEZeagB

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 008e5983-9c1e-46c1-8475-806ee2121dc8

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}