feat(execution-playbooks): add plan-execute@1 with a pre-dispatch plan gate

[90sRehem]

Intent

Add a "ready plan -> execution" dispatch contract to Squad: a versioned execution playbook plan-execute@1, a deterministic pre-dispatch structural gate over the brief's execution plan, and the requirement that an executing model receives a materialized plan instead of being left to design.

Context: today a brief points the worker at sources (data//tasks/T0x.md, technical contract) and lets it decide. Lower-context execution lanes (luna/haiku/deepseek) must not decide design; the planner (opus/sol, with the commander) owns it. Commander decision 2026-10-08: D3=O1 - playbook plus a deterministic pre-dispatch validator, with the plan materialized from the planning artifact, and no recon. The TLC methodology owns planning (tlc-discover/tlc-plan) and execution (tlc-implement, checklist under data//artifacts/); Squad already validates that post-work checklist with bin/sq-playbook-validate.sh.

Implementation delivered:

• .agents/skills/execution-playbooks/references/plan-execute-v1.md (new): the plan-execute@1 contract. It applies when the resolved worker lane is an execution-class model; defines the required ## Execution plan fields; states the plan is materialized from the planning artifact (the TLC tasks/T0X.md when one exists); requires the worker to not redesign and to stop with blocked: on an incomplete or contradictory plan; requires following tlc-implement and writing the checklist under data/<id>/artifacts/; and lists stop conditions.
• bin/sq-brief.sh: registers plan-execute@1 with EXPECTED_KIND=strike.
• bin/sq-plan-validate.sh (new): deterministic structural validator. Reads data/<id>/brief.md, bounds the ## Execution plan section, and fails with a named message when any required field is absent or structurally empty - exact file paths (at least one path-like entry), ordered/numbered steps, acceptance criteria, a verification command, and an out-of-scope statement. It never judges plan quality.
• bin/sq-playbook-validate.sh: additively registers plan-execute@1 with a small post-work criteria set (plan fields realized: files touched as planned, steps executed, acceptance met, verification run); every existing playbook's criteria are unchanged.
• bin/sq-spawn.sh: when the brief declares playbook=plan-execute@1, runs the structural validator before creating any endpoint and refuses on failure, mirroring the existing playbook identity refusal.
• AGENTS.md: selects plan-execute@1 for execution-class lanes and requires the validator before dispatch.
• Colocated tests: tests/sq-plan-validate.test.sh (new) plus additive extensions to tests/sq-brief.test.sh and tests/sq-playbook-validator.test.sh.

Acceptance criteria:

• bin/sq-brief.sh <id> <repo> --mode drill --playbook plan-execute@1 scaffolds and the brief carries the plan-execute@1 section.
• bin/sq-plan-validate.sh <id> exits 0 for a complete plan, and exits non-zero naming each missing field otherwise.
• bin/sq-spawn.sh refuses to create an endpoint for a plan-execute@1 brief whose plan is incomplete.
• Every existing playbook and the current post-work sq-playbook-validate.sh behavior are unchanged (no regression).

Verification: shellcheck (bin/sq-lint.sh, pinned 0.11.0) over every changed bin script; the new validator's colocated tests plus the existing sq-brief and sq-playbook-validator tests.

Out of scope: no change to how planning is performed and no vendoring of TLC skills into Squad's tracked surface; no new model-routing code (config/crew-dispatch.json already carries the lanes); no change to existing playbook criteria and no change to drill itself; no generator that writes plans automatically - materializing the plan into the brief stays a dispatcher responsibility for now.

Constraints: this repository requires the drill signature on every PR to main, so delivery is by the pipeline. Follow squad-coding-guidelines (one sentence per line, plain dash, no agent co-author, shellcheck-clean bin scripts, colocated tests).

What Changed

• Added the versioned plan-execute@1 execution playbook (references/plan-execute-v1.md), which requires a complete materialized ## Execution plan and forbids the executing worker from redesigning or re-scoping.
• Added bin/sq-plan-validate.sh, a deterministic structural gate that bounds the brief's ## Execution plan section and names each missing, empty, or structurally invalid field (path-like files, numbered steps, acceptance criteria, verification command, out of scope).
• Registered plan-execute@1 as strike-only in bin/sq-brief.sh and added its post-work criteria in bin/sq-playbook-validate.sh, wired the pre-dispatch validator into bin/sq-spawn.sh so it refuses before creating an endpoint, and updated the colocated tests and docs.

Risk Assessment

✅ Low: The change is additive and well-bounded; the prior contract-label mismatch is now explicitly aligned with the validator's accepted labels, and the new gate fails closed with named errors without altering existing playbook behavior.

Testing

Ran the new tests/sq-plan-validate.test.sh plus the existing tests/sq-brief.test.sh and tests/sq-playbook-validator.test.sh, and bin/sq-lint.sh (ShellCheck 0.11.0) - all passed. Additionally executed a manual end-user CLI transcript showing the strike brief scaffolding with the plan-execute@1 section, the structural gate rejecting a scaffold with no plan, passing a complete plan, naming a missing acceptance criteria field, and sq-spawn.sh refusing dispatch with no endpoint metadata created; a control confirmed the validator passes once the plan is complete. Evidence is a CLI transcript at /tmp/drill-evidence/01M4EWP9YQC1ZTFSNFXCES2E9S/plan-execute-e2e.txt; the worktree was left clean of transient artifacts.

Evidence: plan-execute@1 end-to-end CLI transcript (scaffold, gate pass/fail, dispatcher refusal, no endpoint)

=== 2. Pre-dispatch gate refuses the scaffold before the plan is materialized === missing: execution plan section (## Execution plan) exit=1 === 4. Complete plan passes the structural gate === execution plan structurally valid: demo-pe exit=0 === 6. Dispatcher refuses to create an endpoint for the incomplete plan === missing: execution plan field "acceptance criteria" error: demo-pe brief execution plan failed structural validation; materialize a complete plan before dispatch exit=1 (no endpoint metadata: refused before any endpoint)

=== 1. Scaffold a plan-execute@1 strike brief (end-user command) ===
scaffolded: /tmp/sq-pe-e2e3.a24EsQ/data/demo-pe/brief.md (strike, mode=drill; replace {TASK})
brief materialized:
11:Execution playbook: id=plan-execute version=1

=== 2. Pre-dispatch gate refuses the scaffold before the plan is materialized ===
missing: execution plan section (## Execution plan)
exit=1

=== 3. Dispatcher materializes a complete ## Execution plan into the brief ===
(complete plan appended)

=== 4. Complete plan passes the structural gate ===
execution plan structurally valid: demo-pe
exit=0

=== 5. A missing required field is refused and named (remove Acceptance criteria) ===
missing: execution plan field "acceptance criteria"
exit=1

=== 6. Dispatcher refuses to create an endpoint for the incomplete plan ===
missing: execution plan field "acceptance criteria"
error: demo-pe brief execution plan failed structural validation; materialize a complete plan before dispatch
exit=1
endpoint metadata created? (expect: absent)
ls: cannot access '/tmp/sq-pe-e2e3.a24EsQ/state/demo-pe.meta': No such file or directory
  (no endpoint metadata: refused before any endpoint)

=== 7. Control: with the plan restored complete, the gate no longer refuses on the plan ===
execution plan structurally valid: demo-pe
validator exit=0
HOME_T=/tmp/sq-pe-e2e3.a24EsQ

Pipeline

Updates from git push drill

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 2 issues found → auto-fixed ✅

• ⚠️ .agents/skills/execution-playbooks/references/plan-execute-v1.md:11 - The plan-execute@1 contract describes the first required field only as "exact file paths"/"ordered steps", but bin/sq-plan-validate.sh requires a label starting with the literal "Files to touch" (line 35). A dispatcher materializing the plan as "Exact file paths:" - the exact phrase in this contract - is refused with missing: execution plan field "files to touch (exact paths)", even when every required field is present (verified manually). The contract the worker reads should name the exact accepted labels, or the validator should accept the contract phrasing, so a contract-conformant plan cannot be refused before dispatch.
• ℹ️ bin/sq-plan-validate.sh:35 - The structural gate fails closed on some legitimate plan shapes: a required field counts as "empty" unless it has a list bullet/numbered entry, so a verification command written as a fenced code block is reported empty: ... verification command; and the path-like regex requires a / or a dotted filename, so a files list containing only extensionless top-level names (Makefile, Dockerfile, LICENSE) is reported invalid: ... no path-like entry. Both are named, fail-closed refusals rather than silent passes, so this is a bounded tradeoff; noting it in case the author wants to widen the two heuristics.

🔧 Fix: Align plan-execute@1 contract field labels with validator
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• bash tests/sq-plan-validate.test.sh - new structural gate behavior: complete plan exit 0, each of the five missing fields named individually without false positives, empty fields named as empty, non-path files and non-numbered steps rejected, missing section named, later-heading fields not counted
• bash tests/sq-brief.test.sh - plan-execute@1 strike scaffold carries the materialized plan-execute@1 contract, recon is refused with no partial brief, and every existing playbook brief still materializes
• bash tests/sq-playbook-validator.test.sh - all existing playbook checklists (wave-one, wave-two, multi-phase-plan, eval) still validate/refuse as before, plus the new plan-execute@1 post-work criteria set
• bash bin/sq-lint.sh - ShellCheck 0.11.0 clean over every changed bin script
• Manual E2E: bin/sq-brief.sh demo-pe projects/alpha --mode drill --playbook plan-execute@1, bin/sq-plan-validate.sh demo-pe, and bin/sq-spawn.sh demo-pe projects/alpha --mode drill --yolo off with complete and incomplete plans

⚠️ **Document** - 1 info

• ℹ️ docs/pt-BR/scripts.md:130 - The sq-playbook-validate.sh row enumerates every playbook identity, but its English owner docs/scripts.md no longer carries that row (it was trimmed in 3a2e058), so this change extended an orphaned translation duplicate instead of pointing at the registry owner. The whole pt-BR toolbelt list has drifted from the English original, so a full re-sync (drop the row or reduce it to a pointer) is a follow-up beyond this change's scope.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[90sRehem]

Coding agent usage on this pull request

Contributor	Agent	Sessions	Total tokens	Estimated cost
Squad task squad-plan-execute-dispatch-contract	Pi	1	14.6 million	not applicable

Token and model breakdown

Model	Input	Output	Cache read	Cache write	Total tokens	Estimated cost
deepseek-v4.1-flash	471.5 thousand	63.5 thousand	14 million	0	14.6 million	flat-rate subscription: not applicable

Source: Pi session JSONL usage records, covering the task lifetime from 2026-10-08T23:01:17.849Z through report generation. Costs are provider-recorded where available, otherwise list-price estimates; subscription usage is not represented as spend.