.claude/skills/parity-review/SKILL.md

name: parity-review description: Review new stable upstream CodexBar releases for Linux/Plasma parity, probe changed CLI contracts in isolation, and update TODO.md with a dated research note in one docs PR. Use when a new official CodexBar release appears, when the scheduled release monitor runs, or when the user asks for a parity review. Do not use to implement the gaps it finds or to release the widget.

Review upstream releases for parity

The procedure and its rules live in upstream release maintenance; gap classification follows the sources of truth in AGENTS.md. This skill supplies the commands, the isolation recipe, and the note shape.

1. Find the delta

1	git fetch origin
2	git show origin/main:TODO.md \| grep -m1 -A1 'Last release reviewed'
3	gh release list -R steipete/CodexBar --exclude-drafts --exclude-pre-releases --limit 50
4	gh pr list --state open --search 'parity in:title'

The list must reach the baseline tag; raise --limit until it does. Stop without a commit or notification when no stable release is newer than the baseline and no verification is pending. Reuse an open parity PR branch instead of opening a second one. For each release since the baseline:

1	gh release view vA.B.C -R steipete/CodexBar --json tagName,publishedAt,body
2	gh api repos/steipete/CodexBar/commits/vA.B.C --jq .sha

2. Compare

Check each Linux-relevant change, fix, and changed contract against the current Plasma code, config schema, tests, and guides. Recheck the carried blockers in TODO and the unresolved findings of the newest note under docs/research/.

3. Probe changed contracts in isolation

1	v=A.B.C
2	tmp=$(mktemp -d)
3	cd "$tmp"
4	gh release download "v$v" -R steipete/CodexBar \
5	-p "CodexBarCLI-v$v-linux-x86_64.tar.gz" \
6	-p "CodexBarCLI-v$v-linux-x86_64.tar.gz.sha256"
7	sha256sum -c "CodexBarCLI-v$v-linux-x86_64.tar.gz.sha256"
8	mkdir bin home config cache
9	tar -xzf "CodexBarCLI-v$v-linux-x86_64.tar.gz" -C bin
10	sandbox() {
11	bwrap --ro-bind / / --tmpfs /home --tmpfs /root --tmpfs /run --tmpfs /tmp \
12	--bind "$tmp" /tmp/probe --dev /dev --proc /proc --unshare-all \
13	--die-with-parent --clearenv --setenv PATH /usr/bin:/bin \
14	--setenv HOME /tmp/probe/home --setenv XDG_CONFIG_HOME /tmp/probe/config \
15	--setenv XDG_CACHE_HOME /tmp/probe/cache "$@"
16	}
17	sandbox /tmp/probe/bin/codexbar --version

Run every probe through sandbox. A temporary HOME alone is not isolation: cost discovery for Codex, Claude, Antigravity, and Muse still finds host history under env -i. The tmpfs mounts hide the real home directory, and --unshare-all removes network access and host IPC.
Without bwrap, do not probe. Record the affected contracts as unverified.
--unshare-all gives each call its own network namespace. Start a loopback fixture in the same call as the probe, for example sandbox sh -c 'python3 -m http.server 8765 --bind 127.0.0.1 & sleep 1; /tmp/probe/bin/codexbar ...'.
Never replace the installed codexbar. Use synthetic keys only.
Record every probe you could not run, with the reason.

4. Write the results

Add docs/research/YYYY-MM-DD-macos-parity-A.B.C.md with the sections of the newest note: header with Plasma commit and upstream tag, commit, and publish time; release coverage table; Linux CLI contract changes; carried-forward blockers rechecked; excluded from the Linux backlog; unverified; probe method. The probe method names the bwrap isolation.
Index the note in docs/README.md.
In TODO.md, update the review baseline, add gaps with evidence and a done condition, remove implemented ones, and revise resolved blockers.

5. Deliver

Use branch codex/parity-A.B.C and title docs(parity): review upstream release A.B.C. Run make check, complete the PR template with exact versions and evidence, and follow CI to its final result. A scheduled run stops at a green PR: no merge and no feature work.

Files