v1.16.28

[1.16.28] — 2026-04-07

Fix two long-standing reliability bugs in scripts/qq-release.sh itself — motivated by the v1.16.27 release which live-demonstrated both of them. Bug A: the script previously read the version from local plugin.json and bumped without fetching origin/main first, so if another session / concurrent release had advanced the remote, it would bump to an already-taken version number. The push would fail, but only after the local release commit was already created — forcing a manual git reset --hard + rebase + full re-run (two complete test.sh passes, 5 minutes of wasted CI). v1.16.27 release hit this exactly once. Fix: inject a fetch + 'git merge-base --is-ancestor origin/main HEAD' check between arg parsing and version derivation. If local is behind, refuse with a clear list of missing commits and a 'git pull --rebase origin main' hint; version derivation now reads the freshly-synced plugin.json on retry. Bug B: the post-push CI watch used 'sleep 2 + gh run list --limit 1' to find the run to watch. GitHub registration is often slower than 2 seconds, so the script frequently grabbed the previous release's run and reported 'CI green' based on that — CLAUDE.md even documented 'always re-confirm with gh run list --limit 2 --branch main' as a live workaround, which is itself evidence the script was broken. v1.16.27 demonstrated this live: the script reported CI green citing run 24081253247 (which was v1.16.26's Validate run) while the real v1.16.27 Validate run 24086382464 was still in_progress. Fix: capture COMMIT_SHA_FULL (git rev-parse HEAD) right after the release commit, then poll 'gh run list --workflow Validate --json databaseId,headSha' with a headSha filter and exponential backoff (1+2+4+8+15 = 30s total patience). If no run is found, print a warning and hand off to manual verification instead of blindly watching the wrong run. Both paths hand-tested: happy path dry-run walks cleanly through the new sync check; sad path (clone + 'git reset --hard HEAD2' to simulate behind-remote) refuses with the expected message and exit; the Bug B jq filter returns the correct run 24086382464 for v1.16.27's HEAD SHA against real gh data. Script grows from 376 to 429 lines (+53), no existing functionality touched.

v1.16.27

[1.16.27] — 2026-04-07

Revert the bc146cb 'codex review subcommand' experiment and permanently route code-review.sh through codex exec. Two reasons: (1) codex-cli 0.118.x has a clap parser conflict where --base / --commit / --uncommitted are mutually exclusive with [PROMPT] despite --help listing both, so every Path A call with a custom prompt errored out with 'the argument --base cannot be used with [PROMPT]' — bc146cb's manual validation happened to use a prompt-less invocation so the regression slipped through. (2) codex review natively has no --files / --ext scope, and flexible-scope review (not just branch diff) is the primary use case. Fix is surgical: drop HAVE_REVIEW_SUBCMD detection, USE_REVIEW_SUBCMD flag, the Path A branch, the per-run 'Path A disabled' note, and the surrounding if/else scaffolding; dedent the codex exec body; rewrite the header comment to document both reasons. Script drops from 301 to 239 lines (-62 / -20%). End-to-end verified across --base / --commits / --files / --ext in a throwaway git repo with a codex stub. Also fixes two stale claims in skills/codex-code-review/SKILL.md about the script preferring codex review + requiring >= 0.118 for the subcommand — both now correctly describe codex exec with the Unity 18-rule checklist inlined in the prompt.

v1.16.26

[1.16.26] — 2026-04-07

Hot-fix v1.16.25 CI failure: skip clone_copy_tree hardlink fallback test on macOS. The macOS clonefile path (cp -cR) runs before hardlink is attempted, so allow_hardlink=True returns clonefile not copytree, making the fallback test premise unverifiable on that platform. Test 5 was already gated to macOS-skip; test 6 now matches. No production code change. v1.16.25 functionality is unchanged and verified on Linux/Windows where hardlink actually runs.

v1.16.25

[1.16.25] — 2026-04-07

v1.16.25 closes the EnterWorktree completion gap discovered when an agent's Phase 0 dispatch failed with 'scripts/platform/ missing'. New 'seed-local-runtime' subcommand finishes what EnterWorktree starts: copies LOCAL_RUNTIME_PATHS (scripts/, .mcp.json, AGENTS.md, CLAUDE.md, qq.yaml), baseline state files, baseline run records, and writes .qq/state/worktree.json metadata so the new worktree behaves identically to a command_create-created one. Without it, every qq script in the new worktree exits 127 because scripts/platform/detect.sh is missing, and 5+ downstream consumers (commit-push Type B closeout, qq-codex-exec --add-dir injection, qq-project-state.py, qq-doctor.py, build_status flags) silently treat the worktree as unmanaged. Validation uses git common-dir matching plus 'git worktree list --porcelain' membership (NOT --show-toplevel, which differs by design between linked worktrees). clone_copy_tree gains an allow_hardlink parameter scoped strictly to Unity (Library is the only currently-supported engine cache that's safe to alias — Godot's uid_cache.bin and Unreal's UBT manifests are rewritten in place and would corrupt the source). Hardlink path uses a sibling staging directory with atomic rename: on partial failure (cross-device, unsupported FS), the staging dir is rmtreed and the function falls through to shutil.copytree on a clean target — preventing the catastrophic case where copytree's O_TRUNC on a partially-hardlinked file would write through the shared inode and corrupt the source's Library cache. On Windows (no rsync, no clonefile), this turns multi-GB Library seed from a 30-120 second real-byte copy into sub-second per-file os.link. /qq:execute and /qq:go SKILL.md updated to call seed-local-runtime then seed-runtime-cache (no --source, so metadata is authoritative). 6 new test.sh checks via TDD, full test.sh 384/384 green. Built test-first; followed two rounds of codex-plan-review (4 + 3 findings, all verified by parallel subagents, all incorporated).

v1.16.24

[1.16.24] — 2026-04-07

Comprehensive structural fix for the v1.16.22 README sync failure class. Four root causes are now mechanically enforced instead of relying on agent discipline: (a) NEW test.sh section 5f cross-language link discipline check — flags any docs//X.md link to ..//Y.md when docs//Y.md exists, with README.md ↔ README.md exempted as legitimate language switchers; (b) NEW qq-release.sh always-on pre-flight runs the README sync drift check (already in test.sh 5d) and the new cross-language link check at release time, BEFORE any commit, regardless of --skip-tests — closing the loophole where v1.16.22 was released because --skip-tests bypassed the entire section 5 pre-flight; (c) NEW HTML comment block above the Chinese half of root README explicitly warning agents that the section is auto-generated from docs/zh-CN/README.md, including the correct edit-then-sync workflow and noting that CI enforces it; (d) the existing test.sh 5d sync drift check is unchanged because it caught v1.16.22 at CI time, but B is its commit-time complement so the failure cannot reach remote in the first place. Together this means the v1.16.22 sequence (edit zh-CN README → forget to sync → use --skip-tests → push broken release → CI red → hot-fix release) is mechanically impossible going forward.

v1.16.23

[1.16.23] — 2026-04-07

Hot-fix v1.16.22 readme rollout: (a) three links in docs/zh-CN/README.md were pointing to docs/en/* instead of the existing zh-CN siblings (tykit-mcp.md, tykit-api.md, worktrees.md), (b) the root README.md is a bilingual file whose Chinese half is generated from docs/zh-CN/README.md by scripts/qq-sync-readme-zh.py — v1.16.22 updated the English half and docs/zh-CN/README.md but never ran the sync, leaving the root README's Chinese half stuck on the old 12-line Quick Start and tripping the CI structural check 'root README Chinese half drifts from docs/zh-CN/README.md'. v1.16.23 fixes the three zh-CN links and runs the sync script, so the bilingual root README is now consistent across both halves and CI passes. Behavior unchanged — pure docs sync.

v1.16.22

[1.16.22] — 2026-04-07

Rewrite README Quick Start as an ROI-focused 5-step onboarding guide (en + zh-CN). The previous Quick Start was 12 lines — a flat code block + one sentence — which left new users with no guidance on which of the 26 commands actually matter, when to escalate work_mode, what to skip in week one, or how to avoid the most common ceremony pitfalls. The new version follows the 80/20 principle: (1) work_mode selection table with the explicit warning that the most common new-user mistake is leaving the project on hardening by default, (2) the 4-command happy path /qq:go → /qq:execute → /qq:test → /qq:best-practice covering 90% of work, (3) three concrete templates for feature dev / bug fix / pre-merge gate, (4) a 'do not touch in week one' list (bootstrap, heavy doc ceremony, cross-model review on every change, --auto, custom profiles), (5) CLAUDE.md customization with 6 example Unity-project hard rules positioned as the highest-ROI customization. Adds two explicit anti-patterns (do not read raw .qq/runs/*.json in prompts, do not run cross-model review after every small edit) and four week-one self-check questions for diagnosing whether the workflow is actually saving time vs just adding ceremony noise. ja/ko READMEs not yet updated and remain on the old thin Quick Start until the next i18n batch.

v1.16.21

[1.16.21] — 2026-04-07

Fix two related worktree bugs in /qq:execute and /qq:go that surfaced when an agent (a) silently invented a '--no-worktree semantics' to bypass the worktree guard on encountering an untracked plan file, polluting main with a 24-step plan execution; and (b) called EnterWorktree which silently branched the new worktree from develop instead of the current feature branch (u/tyk/DPP-961-...), losing a freshly-committed plan commit and forcing a cherry-pick recovery. The Worktree Guard section is now strict — only three skip conditions are allowed (already in a worktree, literal --no-worktree token, or trivially small plan), agent-invented bypasses are explicitly forbidden, common obstacles like 'plan is untracked' get a corrective fix table ('git commit the plan first, then enter worktree'), and silent skips are banned. After EnterWorktree runs, the skill now mandatorily captures the source HEAD beforehand and verifies via git merge-base --is-ancestor that the new worktree's HEAD includes the source HEAD; if EnterWorktree branched from the wrong ref, the skill auto-recovers via git reset --hard SOURCE_HEAD (because the new worktree branch has no commits of its own yet). Cherry-pick is documented as NOT sufficient — it brings commits over but leaves the merge-base wrong, which corrupts later git diff source...HEAD scoping. Same fixes mirrored to /qq:go's Worktree Isolation section.

v1.16.20

[1.16.20] — 2026-04-07

Unify the Chinese README via a generator + drift check, complementing v1.16.19 (review script bin/ path fix from a parallel session). The Chinese content used to live in two parallel files (root README's Chinese half and docs/zh-CN/README.md), translated independently in different sessions and gradually drifting apart — different section titles, different phrasing, different table cells in some places translated and others left in English. This release collapses both onto a single canonical source. New scripts/qq-sync-readme-zh.py reads docs/zh-CN/README.md (the canonical), strips the title + lang nav, rewrites relative paths to be repo-rooted (../../X → X, ../X → docs/X, bare → docs/zh-CN/X), and replaces the block between the Chinese h2 and the project footer in root README. Modes: --check (default, exit 1 on drift), --write (rewrite root in place), --print (debugging). test.sh section 4 enforces the contract by running --check after the tykit coverage ratchet, failing CI with a clear DRIFT message if anyone forgets to run --write. The lang nav 中文 link in the root README now points to the in-page anchor (#中文) instead of navigating to docs/zh-CN/README.md, so Chinese readers see the content directly on the GitHub project page. docs/zh-CN/README.md still exists as the canonical editing target and a fallback for direct navigation. CLAUDE.md Conventions documents the contract: edit the canonical, run --write, commit both, and let test.sh catch forgotten syncs.

v1.16.19

[1.16.19] — 2026-04-07

Fix 4 review skills (codex-plan-review, codex-code-review, claude-plan-review, claude-code-review) that told agents to invoke scripts as bare commands like 'plan-review.sh '. The qq plugin never puts its scripts on PATH, and install.sh's permission allowlist only covers relative-path variants ('./scripts/X', 'scripts/X'), so bare invocation was unreliable from day one — it only 'worked' when agents happened to use relative paths or jumped straight to the fallback. Today a real agent hit exit 127 on 'plan-review.sh' and had to manually switch to the ${CLAUDE_PLUGIN_ROOT}/bin/ fallback mid-run. All four SKILL.md files now use ${CLAUDE_PLUGIN_ROOT}/bin/<script>.sh as the canonical invocation (absolute path, cwd-independent, env var injected by Claude Code for every plugin context), and the top-of-skill callout was reworded from 'bare command with fallback' to 'use ${CLAUDE_PLUGIN_ROOT}/bin/, bare is NOT reliable'. Non-review scripts like unity-test.sh are untouched — they continue to work through install.sh's relative-path allowlist.