validate-queue

validate-queue []

Schema-check a goal-queue file. Read-only. Surfaces structural problems before they bite mid-execute.

When to invoke

• The user explicitly typed /goal-flight validate-queue [<path>].
• After hand-editing a goal-queue and before running /goal-flight execute.
• Pre-flight inside commands/execute.md step 1 (called automatically; bail with a clear error if validation fails).

What the user provides

• No args → validate the most recent docs-private/goal-queue-*.md (new naming as of 0.3.0); fall back to legacy docs-private/<topic>-goal-queue-*.md if no new-form file exists.
• One arg <queue-file> → validate that specific path.

Steps

1. Resolve the queue file (most recent by date suffix if no arg).

2. Parse the queue. Each chunk is a ## #N <slug> heading followed by four mandatory subsections (per the goal-queue shape in commands/decompose-plan.md):

   • ### SCOPE — one paragraph.
   • ### CHECKLIST — bulleted list.
   • ### ACCEPTANCE — testable criteria, bulleted.
   • ### FORBIDDEN — explicit anti-scope, bulleted.

3. Run these checks. Each failure is a P0/P1/P2:

   Structural (P0 — blocks execute):

   • Every chunk heading matches ^## #(\d+) (.+)$ — extract chunk number + slug.
   • Numbering is sequential starting from 1. No gaps. No duplicates.
   • Each chunk has all four mandatory subsections (SCOPE, CHECKLIST, ACCEPTANCE, FORBIDDEN). None are empty.
   • Slugs are unique across the queue.
   • Slugs are lowercase + hyphens only (no spaces, no underscores, no caps).

   Tags (P1 — execute can proceed but flag):

   • [parallel-safe:<group>] tags reference groups that have ≥ 2 members. A lone [parallel-safe:foo] chunk is parallelism-broken and should be untagged or grouped.
   • [milestone] tags should appear roughly every 5 chunks for projects ≥ 15 chunks; warn if absent.
   • [controller-direct] is a candidate tag, not permission. SCOPE must show held session context and a fully stateable edit with no exploration or special review-independence need. Warn on unread call sites, cross-module discovery, or a non-mechanical trust surface — not delta size or file count. Recheck free-slot serialization under Axis 2 at execution.
   • [acp] and [bash-tail] are mutually exclusive — co-occurrence on the same chunk → P1 conflict warn (orchestrator would otherwise have to pick arbitrarily). [acp] should only appear when docs-private/env-caveats.md shows the target adapter installed (otherwise the dispatch will fall through to [bash-tail] at runtime; warn if env-caveats is missing OR shows the adapter unavailable — execute can still proceed via fallback).
   • [goal-mode] + [bash-tail] co-occurrence is codex-only — only codex /goal emits the Final-response marker the watcher needs to detect end-of-goal in a flat tail. This rule is P0 (escalated from the surrounding P1 block): if a chunk has [goal-mode] + [bash-tail] AND the target worker is not codex (or worker isn't specified and would default to non-codex per env), the dispatch will hang waiting for a marker that never comes. See protocols/dispatch-routing.md composition table for the rule.