Dispatch Gating via File Markers

[dean0x]

Summary

Add file-based status markers (<!-- status: writing --> / <!-- status: complete -->) to workflow artifacts, with PreToolUse hook enforcement that prevents downstream agents from acting on incomplete inputs.

Motivation (from Kiln Analysis)

Kiln uses HTML comment markers on line 1 of artifact files to signal completion status, checked by PreToolUse hooks before allowing downstream dispatch.

The Marker Format

<!-- status: writing -->   (placed on line 1 when agent begins writing)
<!-- status: complete -->   (replaced on line 1 when agent finishes)

The Status Check Helper

_status_ok() {
  [[ -f "$1" ]] && head -1 "$1" | grep -q '<!-- status: complete -->'
}

Checks line 1 ONLY — deliberately fast, no full-file scan.

Which Hooks Check Which Markers

Hook 4 (krs-one → codex/sphinx dispatch):

# Both must be complete before dispatching implementers
_status_ok ".kiln/docs/architecture.md"  # Architect must finish
_status_ok ".kiln/docs/patterns.md"      # Sentinel must finish

Hook 5 (aristotle → planners dispatch):

# Planners cannot start until architecture is complete (they READ it)
_status_ok ".kiln/docs/architecture.md"

Hook 6 (codex exec backup gate):

# Safety net — same checks as Hook 4, in case it was bypassed
_status_ok ".kiln/docs/architecture.md"
_status_ok ".kiln/docs/patterns.md"

Full Dispatch Gating Flow Example

1. Architect starts writing architecture.md
   → Places "<!-- status: writing -->" on line 1

2. Aristotle tries to dispatch planners (confucius, sun-tzu)
   → Hook 5 checks: _status_ok ".kiln/docs/architecture.md"
   → File has "<!-- status: writing -->" on line 1
   → _status_ok returns false → BLOCKED

3. Architect finishes, marks "<!-- status: complete -->"

4. Aristotle retries SendMessage to confucius
   → Hook 5 checks: _status_ok ".kiln/docs/architecture.md"
   → "<!-- status: complete -->" found → ALLOWED

5. Confucius and sun-tzu start planning with complete architecture context

Self-Signaling Pattern

Each agent marks their own file — no external coordination needed:

• Architect places markers on architecture.md
• Sentinel places markers on patterns.md
• Status transitions are atomic (single line replacement)

Fail-Open Behavior

If .kiln/ directory doesn't exist, all sequencing hooks fail open — not in a pipeline context, so no gates apply.

Current State in DevFlow

• Workflow phases are sequential by command structure (commands explicitly spawn agents in order)
• Within Agent Teams (debate mode), there's no mechanism to prevent teams from acting on incomplete synthesis
• /code-review: Resolver agents could theoretically start before Synthesizer completes
• /implement: Coder could start before Plan is fully written
• No file-based signaling between agents

Technical Approach

1. Marker-Aware Artifact Writing

Agents that produce artifacts add markers:

<!-- status: writing -->
# Implementation Plan
...

On completion:

<!-- status: complete -->
# Implementation Plan
...

2. DevFlow Dispatch Gates

Gate	Upstream Agent	Downstream Agent	File Checked
Plan → Build	Plan agent	Coder agent	.docs/design/plan.md
Review → Resolve	Synthesizer	Resolver agents	.docs/reviews/{branch}/summary.md
Explore → Plan	Skimmer/Explore	Plan agent	Explore output artifact
Debate → Synthesis	Debaters	Synthesizer	Debate artifacts

3. PreToolUse Hook Integration

Add dispatch gating checks to the enforcement hook (ties to #98 — PreToolUse Hook Enforcement System):

# In enforce-tools.sh
# Gate: Coder cannot start until plan is complete
if [[ "$AGENT" == "coder" ]] && [[ "$TOOL" =~ ^(Write|Edit|Bash)$ ]]; then
  PLAN_FILE=$(find .docs/design/ -name "*.md" -newer .claude/ 2>/dev/null | head -1)
  if [[ -n "$PLAN_FILE" ]] && ! _status_ok "$PLAN_FILE"; then
    echo "BLOCKED: Plan is still being written. Wait for plan completion." >&2
    exit 2
  fi
fi

4. Agent Teams Application

For Teams variant (-teams.md commands):

• Each team member marks their output with status markers
• Synthesizer is gated on ALL team members reaching complete
• Prevents premature synthesis of incomplete outputs

5. Minimal Implementation (Without PreToolUse)

Even without the full enforcement hook, markers can be used as a convention checked by command orchestration:

# In command orchestration, before dispatching coder:
while ! grep -q '<!-- status: complete -->' ".docs/design/plan.md" 2>/dev/null; do
  sleep 2
done
# Now dispatch coder

Acceptance Criteria

• Status marker format defined (<!-- status: writing|complete --> on line 1)
• _status_ok() helper available in hook scripts
• Plan agent writes markers when producing plan artifacts
• Synthesizer writes markers when producing review summaries
• Downstream agents gated on upstream artifact completion
• Fail-open behavior when not in a pipeline context
• Integration with PreToolUse enforcement hook (PreToolUse Hook Enforcement System #98)
• Agent Teams: synthesis gated on all team member completion

References

• Kiln repo: enforce-pipeline.sh hooks 4-6 (sequencing category)
• Kiln's _status_ok() helper function
• DevFlow PreToolUse Hook Enforcement: PreToolUse Hook Enforcement System #98
• DevFlow workflow phases: /implement, /code-review, Agent Teams
• Priority: Medium impact, Low effort — "Quick win" (ties to PreToolUse Hook Enforcement System #98)