Orchestrata Ultimate › Gates › dispatch-brief

Gate: dispatch-brief

At a glance

The flow

What task_context_hook.py checks

Read with the AST toolkit (claude/hooks/task_context_hook.py; the plugin copy is byte-identical, and the deployed ~/.claude/hooks copy is identical after line 1, which deploy/install-claude-config.sh rewrites to the deployed interpreter).

• The five labels. REQUIRED_FIELDS = ("GOAL:", "FILES:", "CONSTRAINTS:", "DONE WHEN:", "VERIFY:"). The test is f not in prompt.upper(): each label must appear as that exact substring, case-insensitive. A qualifier between the word and the colon (FILES (read-only):) is a missing field. The comment above the tuple gives the reason: "briefs with 'minimal info' rebuilt the wrong thing, unstated done-criteria produced 'mostly done', and an unnamed verification command produced claims nobody had run."
• Categories. categorize() uses the one shared pattern table imported from workflow_context_inject.DOMAINS ("A second copy would drift").
• Module context. module_context_for takes .py paths from the FILES: field first (prose before FILES: once burned the six-path budget on files merely mentioned, 2026-08-19), resolves them against CLAUDE_PROJECT_DIR, the git root above cwd, then cwd, and runs tools/module_context.py: an existing file gets "AST, class diagram, Prolog dependency contracts, blast radius"; a new file gets the public API of the package it joins; a package resolving to $HOME is ignored. The output is the === MODULE CONTEXT … block seen at the end of every worker brief.
• Mandatory AST. For categories in AST_REQUIRED_CATEGORIES = {"development", "testing"} a brief with no resolvable .py path is denied.
• No redundancy. Each injected block is hashed into a per-session ledger under $XDG_RUNTIME_DIR/claude-inject-ledger, so the same module context never enters one session twice.
• On success it returns permissionDecision: allow with updatedInput (the rewritten prompt). "Never blocks: any failure returns the tool call unmodified" (module docstring) — the denials above are deliberate verdicts, not failures.
• The same hook also runs on Edit/Write/NotebookEdit (_inject_for_edit) with a 10 s cap (EDIT_TIMEOUT) instead of 30 s (MODULE_TIMEOUT); that path injects context and is not a brief gate.

What require-design-before-build.sh checks

Its decision table (header, mirrors plans/contracts/rul-022-design-gate.contract.json):

1. tool is not Agent → allow.
2. subagent_type not in {builder, wirer, refactorer} → allow. The comparison is an exact set membership, so a namespaced type such as orchestrata:builder is not in the set (read from the script, 2026-10-23; whether such dispatches occur was not measured).
3. a line matching ^DESIGN_WAIVER:[ \t]*(.*)$ with a non-empty reason → allow, reason echoed to stderr. A bare DESIGN_WAIVER: does not count, and a waiver embedded mid-sentence does not match (memory agent-brief-hook-fields, 2026-10-06).
4. an existing plans/contracts/… path in the prompt → allow.
5. --requirements, --spec-file and --artifact-file all named and scripts/factory_decision.py decide exits 0 → allow.
6. otherwise → BLOCKED (RUL-022): implementation dispatch with no ratified design, exit 2, with the remediation (dispatch analyst for a contract, run gen-skeleton, re-dispatch naming it, or add DESIGN_WAIVER: <reason>).

It runs through _dispatch.sh, which scopes plugin hooks to the orchestrata tree. PreToolUse(Agent) payloads carry no path, so the dispatcher uses a per-session memo of the repo the session last operated on; in a session that has not yet touched the repo through a path-bearing call, the guard does not fire (_dispatch.sh header: measured 2026-08-23, 14 of 25 project hooks were dark in $HOME sessions before the memo). task_context_hook.py is registered directly and fires in every session.

workflow-default-sonnet.sh (Workflow tool)

Blocks (exit 2) a Workflow script with an agent() call that names no model, unless it is a resumeFromRunId replay. Measured cause (header): on 2026-08-05 two scripts with no model ran 58 agents, all on Opus, 10.4M subagent tokens, for Sonnet-shaped work. "The rule is 'state the tier', not 'always Sonnet'."

Evidence of the gate biting

Typical failures and how to fix them

Related

• Gates index
• Workflow
• Briefs
• Commit-gate pre-check (SubagentStop)
• Session-hook family
• Process-level gates
• RUL-022 · RUL-026 · RUL-035