mav-block-propagation

name	mav-block-propagation
description	Idempotent, resumable propagation of a `blocked-by:#N` block from an ejected story to every transitive downstream story in the epic DAG. Triggered when agent-code-reviewer ejects a PR for human handling.
user-invocable	false
disable-model-invocation	true

Block Propagation

When an agent-code-reviewer ejects a PR for human handling, every downstream story that depended on it is transitively broken. Without propagation, downstream stories keep branching off and stacking on top of a broken base, producing PRs that cannot merge or merge into a broken tree. The blocked-by:#N label is the mechanism that stops every instance from trying.

Running a propagation

The entire marker-write-walk-clear protocol is one idempotent, resumable CLI command:

uv run maverick bprop run <repo> <epic> --ejected <story>

It writes the maverick-bprop marker on the epic, walks the DAG's transitive descendants of the ejected story, applies blocked-by:#<story> and posts a block comment on each (skipping any already labelled), mirrors each story to blocked in the epic state, and deletes the marker when the walk completes. Re-running after a crash resumes exactly where the walk stopped — never perform the walk by hand.

If cold-start hydration finds a maverick-bprop marker on the epic, a prior instance died mid-walk: re-run the command above with the marker's ejected story before any other epic work. A partially-applied block set invites downstream PRs to merge against a broken base.

Cancelling in-flight subagents

A block is useless if a subagent is already deep into a now-blocked story. After the walk:

1. Check .maverick/worktrees/ for any worktree whose branch refers to a now-blocked story.
2. For each: stop the subagent, release its claim (see mav-multi-instance-coordination), do not push its work.
3. Destroy the worktree. Do not attempt to salvage in-progress work — the base is broken; the work cannot be preserved usefully.

Block-on-entry checks

Three places must re-check block state at entry:

Location	Check	Behaviour on block
Cold-start target resolution	Target has blocked-by:#N?	Abort cleanly — report to user
Wave selection	Story has blocked-by:#N?	Exclude from wave
Per-story re-verify (just before coding)	Story gained blocked-by:#N since wave start?	Abort story; release claim

The per-story re-verify catches the race where a block lands after a wave started but before every subagent picked up its story.

Unblock semantics

Maverick never auto-unblocks — the ejection was explicitly delegated to a human, so unblocking is a human decision (remove the blocked-by:#N label). Wave selection re-reads labels each pass, so a removed label lets the story run on the next wave.

Rules

• Never silently ignore a block. If your target carries blocked-by:#N, abort and report — don't modify, push, or claim.
• Never remove a blocked-by:#N label from inside the workflow. Maverick only applies and reads.
• Always re-check at entry. Another instance may have applied or removed a label since your run started.