v4.0.0 — hand-off: planner/executor roles and a review gate

Goal Ledger was built for crash recovery. This release turns it into a hand-off framework: your strongest model writes a plan that a weaker model can actually carry out, and reviews the result before you accept it.

Model tiering is back, but as a runtime role split rather than the divergent per-harness content sets removed in v3 — every harness gets the same skills, and the tiering happens at execution time.

The hand-off model

• A planner — your strongest model — plans, prepares Git, hands out phases, reviews at Gate D, and accepts.
• An executor — a cheaper model, a subagent, or a separate CLI session — runs one assigned phase from its written instructions and stops.
• Execution mode: solo puts both roles in one session; the gates still apply.

The executor's standing instruction is escalate, do not improvise: when it meets a decision the phase file does not answer, it records needs-human — reason: <the exact question> and stops. A stopped phase is a clean hand-off; a phase finished by guessing is a mess the planner has to find.

Breaking changes

• Ledger format v2. GOAL.md requires an ## Execution section (mode, planner/executor tiers, full verification command), Next role in ## Handoff, and a ## Review section. Phase files require Owner, Pattern to follow, and ## Context, ## Scope (In/Out), ## Verify, ## Escalate when, and ## Evidence sections. An in-flight ledger written under v3 will fail validation — see Migration below.
• New skill goal-ledger-execute. Global installs are single-version per user: re-run the install before delegating, or a planner will hand an executor a skill it cannot load.
• The single-writer rule is gone, replaced by a write-scope table. Executors write their own phase file, their phase's mirror line, ## Handoff, and ## Log. Goal status, the phase list, Git fields, and ## Review are planner-only. goal-ledger-resume restores planner-owned fields from Git history and logs the violation if an executor overstepped.
• awaiting-acceptance now requires a recorded Gate D review.
• Phase and sub-task caps raised from 7 to 9, leaving room for remediation. Drafting guidance is still 2–7.

New

• Gate D — a planner-tier review gate and a new in-review goal status. Run the recorded Full verification, read git diff <baseline>..HEAD in full, check every changed path against some phase's scope, and re-check each phase's ## Evidence against its ## Verify. Executor summaries are claims until the planner re-runs the check. Findings become fix-up sub-tasks or a remediation phase, not caveats.
• Phases written for the reader. Exact paths in Scope: In, an explicit Out list, a Pattern to follow: path:line pointing at real code to imitate, single-action sub-tasks, a copy-pasteable ## Verify, and an ## Escalate when list naming how the phase goes wrong. goal-ledger §5 has a "Writing phases a weaker model can execute" section.
• A delegation prompt that deliberately carries no context — everything the executor needs is in the ledger.
• goal-ledger-status now reports owners, next role, review state, and whether the next phase is executor-ready.
• Pushing, opening a PR, and merging are explicitly never automatic. Goal Ledger prepares a reviewed branch and stops.

Validator

The bundled validate_goal_ledger.py now enforces the parts of the format that make delegation work, so an under-specified phase fails before an executor sees it. On a deliberately vague phase it reports six errors and two warnings, including sub-task 1 leaves a decision to the executor ('as needed').

• Errors: missing/placeholder Scope In/Out, placeholder Context or Pattern to follow, a ## Verify that is neither a runnable command block nor an explicit - manual: check, an ## Escalate when with no real condition, an invalid Owner, and awaiting-acceptance without a recorded review.
• Warnings: undecided wording ("as needed", "if necessary") in executor-owned sub-tasks, executor-owned phases verifiable only by eye, and phases marked done with nothing in ## Evidence.

Fixes

• Sub-task parsing is scoped to the ## Sub-tasks section — a numbered list in the new prose sections no longer trips the malformed-sub-task check.
• Committed Python bytecode that .gitignore already excluded is now untracked.

Migration

Finish or abandon any in-flight goal before upgrading. There is no automatic v3 → v4 ledger migration.

To migrate a live ledger by hand, add to GOAL.md an ## Execution section, Next role in ## Handoff, and a ## Review section with none values; then add Owner, Pattern to follow, and the ## Context, ## Scope, ## Verify, ## Escalate when, and ## Evidence sections to each phase file. Run scripts/validate_goal_ledger.py --root <project root> until it is clean. Completed and abandoned ledgers need no migration — they are historical records and are not re-validated.