fix: enforce Codex 1024-char description limit + auto-heal stale installs (v0.11.9.0)

[garrytan]

Summary

• Build-time guard: gen-skill-docs.ts now throws if any Codex description exceeds 1024 chars — prevents shipping broken skills
• Always-regenerate setup: Removed fragile mtime-based staleness check, setup now always regenerates .agents/ (<2s, eliminates all stale-file scenarios)
• One-time migration: gstack-update-check deletes oversized Codex SKILL.md files on existing installs so next setup/upgrade regenerates them
• package.json version sync: Was 6 minor versions behind (0.9.8.0 vs 0.11.8.0), now synced with CI test to prevent drift
• Codex E2E stderr assertions: Captures stderr and asserts no "Skipped loading" / "invalid SKILL.md" errors — regression test for the exact bug
• README troubleshooting: Manual fix instructions for users who hit the loading error
• P1 TODO: Codex→Claude reverse buddy check skill (.agents/skills/gstack-claude/)

Prerequisites

• PR fix: add codex skill metadata for gstack discovery #339 (Codex agents/openai.yaml metadata by @malikrohail) — merged

Test Coverage

All 557 free tests pass (0 failures). New tests:

• Every Codex SKILL.md description ≤ 1024 chars
• package.json version matches VERSION file
• Codex E2E stderr contains no skill loading errors

Pre-Landing Review

No issues found. No SQL, no LLM trust boundaries, no frontend files.

Adversarial Review

Codex (medium tier, 82 lines) found 3 P1s:

• P1-1: Migration tried to run bun run gen:skill-docs from runtime root (no bun/scripts) → Fixed: now deletes oversized files instead of regenerating
• P1-2: Threshold checked frontmatter bytes (2000) not description chars (1024) → Fixed: now extracts description field and checks against 1024
• P1-3: Background regen race condition → Fixed: deletion is atomic, no background process
• P2: Always-regen adds network dependency → Accepted: stale descriptions are worse than transient setup failure

TODOS

• Added: Codex→Claude reverse buddy check skill (P1)

Test plan

• All 557 tests pass (gen-skill-docs + skill-validation)
• Adversarial review findings addressed (3 P1s fixed)
• Manual: verified bun run gen:skill-docs --host codex produces no errors
• Manual: all .agents/ descriptions under 1024 chars

🤖 Generated with Claude Code