Improvement plan + v4.0.1–v4.1.1: correctness, contracts, maintenance, doctrine polish

[BrodieL3]

Summary

The first commit adds IMPROVEMENT_PLAN.md — a full audit of the plugin at ad2bdc3 with a problem / change / acceptance-criterion structure per item. The three commits after it execute the plan as three reviewed releases. Notably, the work was done with the plugin's own doctrine — codex/Luna lanes for routine typing, fable-implementer escalations, and a fable-advisor end-of-deliverable review gating every release — so several fixes were discovered live by the mechanism they fix.

v4.0.1 — correctness

• Codex invocation merged into a single Bash-call fenced block: shell state does not persist across Claude Code tool calls, so the old split step-1/step-2 blocks failed on every literal run; the final message is now printed in-call
• Preflight auth probe (codex login status) so a dead login is caught before exec
• Git repo requirement stated; the "works outside git repos" claim removed (the empty-diff refusal detector is git diff, which dies outside a repo)
• Diff-path handoff so the read-only fable-advisor (no Bash) can actually obtain the diffs it is told to review
• Lane racing now requires per-racer git worktrees instead of two agents writing one tree
• CHANGELOG backfilled from history (all seven releases), version bump

v4.1.0 — contracts and maintenance

• Shared six-status lane vocabulary (complete | partial | refused | timeout | unavailable | blocked) with an explicit architect action per status — previously only unavailable/timeout had routing
• REASON: line added to the codex report schema; out-of-scope working-tree changes reported as unattributed (concurrent lanes/architect edits were being misattributed to codex)
• Timeout detection via exit 124; temp-file cleanup trap + GNU/BSD-portable mktemp
• FABLE_ADVISOR_CODEX_MODEL env override; agents/codex-implementer.md becomes the only normative site for the model slug (it was named in ~13 places across 5 files, and repinned three times in four weeks)
• Liberal-dispatch posture stated in the doctrine (Luna default slot, Terra overflow, effort dial governs cost)
• Manifests: one canonical description reused verbatim in all three sites; marketplace entry gains license/keywords/category; per-entry version deliberately omitted (docs: plugin.json silently wins, so duplicating invites drift)

v4.1.1 — doctrine polish

• "Never type code" vs "keep it with the architect" resolved with one testable rule, stated identically in the README snippet and the skill: type only when the spec would be longer than the diff, and say so
• Verification duty reconciled with cost discipline (who reads full diffs, when)
• README accuracy: the fable→opus downgrade names its two exact files; the CLAUDE_CODE_SUBAGENT_MODEL global-override consequence is stated; the codex wrapper's Sonnet cost is acknowledged
• Perishable dated facts removed from agent prompt text or relocated to README requirements
• Reasoning effort now caller-routable (FABLE_ADVISOR_CODEX_EFFORT, default max), with Model/Effort documented as spec-level routing parameters

Two plan items are deliberately deferred, with status notes in IMPROVEMENT_PLAN.md: item 11 (CI validation workflow — fully specified, mechanical) and item 17 (broadening the anti-refusal preamble to cover approval-gate skills). Release tags (v3.1 retro, v4.0.1, v4.1.0, v4.1.1) exist on the fork; tags don't travel with PRs. Happy to drop IMPROVEMENT_PLAN.md from the PR or split it per-release if you'd rather take the changes piecemeal.

Test plan

• Repo-consistency battery at HEAD: JSON validity of both manifests, plugin.json version == first CHANGELOG heading, model slug confined to its normative site, no fenced block defines SPEC=/FINAL= without codex exec — all PASS
• codex login status exit behavior validated live on codex-cli 0.146.1
• Merged invocation pattern exercised live (four codex-lane dispatches during the work itself)
• Maintainer smoke test of the merged block on macOS (BSD mktemp/gtimeout path)

🤖 Generated with Claude Code

https://claude.ai/code/session_0169izNJMaQTxNrLMqGnsRsj