OthmanAdi/planning-with-files v2.42.0

v2.42.0: POSIX init-session portability + plugin-vs-skill install transparency + Topic Handoff docs

on GitHub

v2.42.0: POSIX init-session.sh portability + plugin-vs-skill install transparency + Topic Handoff docs

Merges two contributor PRs from @carterusedulm2-maker (2026-05-25) and adds v2.42 transparency documentation that surfaced from a deep audit of the v2.38.0 turn-loop integration on the same day.

What shipped

Fixed

• POSIX init-session.sh portability across the 8 mirrors (PR #169). The script's shebang is #!/usr/bin/env bash, but tests/test_init_session_slug.py:27 invokes it via sh, bypassing the shebang. On Ubuntu where /bin/sh is dash, the while [[ $# -gt 0 ]] bashism was a syntax error. v2.42 swaps to POSIX while [ $# -gt 0 ] so the slug-mode test suite runs portably under both bash and dash.

Added

• Install-scope transparency block in canonical SKILL.md (Turn-Loop Integration section). Documents that /plugin install ships the commands/ folder with /plan-goal and /plan-loop, but npx skills add (and ClawHub) install only skills/planning-with-files/ and do not register the wrapper slash commands. The PreCompact hook is in the SKILL.md frontmatter and works for both routes.
• Manual fallback procedure for /plan-goal and /plan-loop inline in the canonical SKILL.md. Lets the agent reproduce wrapper semantics by issuing Claude Code's native /goal and /loop primitives directly. Also covers the disable-model-invocation refusal pattern from anthropics/claude-code #26251 and #41417 where some sessions decline to fire the wrapper even when the user types it.

Docs

• Topic Handoff Pattern documentation in docs/quickstart.md and docs/workflow.md (PR #170). Optional convention for splitting unrelated topics across .planning/<slug>/ directories or a manual handoffs/<topic>.md detail layer alongside progress.md. Documentation only; no shipped script reads handoffs/.

Verification

• 130 pass, 2 skip (Windows exec-bit, pre-existing baseline), 0 fail.
• Security audit completed 2026-05-25: semgrep 0 findings on 23 critical scripts, no preinstall/postinstall in any package.json, no remote fetches in shipped runtime code, SLUG_RE path-traversal defense parity confirmed across the 14 SKILL.md variants, attestation + delimiter framing intact.
• Web research basis: Anthropic skill docs at code.claude.com/docs/en/skills confirm prompt-based slash commands are the blessed pattern (matches bundled /loop, /goal, /run, /verify, /debug).

Parity bump

Version bumped to 2.42.0 across 17 parity-locked files via scripts/bump-version.py. .continue, .gemini, .pi, .kiro lag intentionally per AGENTS.md release scope.

Thanks

@carterusedulm2-maker for PR #169 and PR #170, both filed on 2026-05-25, first contributions to the repo.