Collision Map

The collision map is the visibility layer on top of the sequencing engine. When a parent task fans out into sibling subtasks, each sibling declares the file globs, migration chains, and shared surfaces it intends to touch. The collision map compares those declarations and highlights where siblings might step on each other — both at delegation time and again when a PR is actually under review.

This page is about the concept. For the panel UI, see Tasks & Kanban; for how collision feeds release ordering, see MegaTask.

What the map shows

For any task that has siblings (i.e., it has a parent and is not standalone), the Collision tab on the task detail page shows:

Element	Meaning
Own declared surface	This task's file globs, migration flag, and shared-surface flag.
Overlapping siblings	Every same-parent sibling whose declared surface intersects this task's.
Status / branch / PR	Where each sibling currently lives in the lifecycle.
Sequence badges	The PM-assigned `sequence` order, if any — lower runs first.
Highlighted globs	The exact globs that overlap between two siblings.
Drift callout	A sibling that touched files it never declared.

Root tasks and standalone tasks render an explicit "no collision map" state, because they have no siblings to collide with.

Where the data comes from

The declarations are captured when a task is delegated — the PM attaches them directly, or they arrive already declared on an intake/MegaTask draft. Once declared, they are stored on the task record and used by SequencingService to order work.

Mermaid diagram source: flowchart TD A[Parent fans out to sibling subtasks] --> B[Each sibling declares surface] B --> C{Surfaces overlap?} C -->|no| D[Run in parallel] C -->|yes| E[Collision map highlights overlap] E --> F{PM assigned sequence?} F -->|yes| G[Lower sequence must finish first] F -->|no| H[Review collision before claiming] E --> I[PR reviewer sees drift if actual files differ from declared]

Sequence badges

A PM can stamp sibling subtasks with a sequence number — lower runs first, ties run in parallel. The collision map shows those sequence badges so a reviewer can read the intended order at a glance. A lower-sequence sibling must reach a terminal state before a higher-sequence one can be claimed; an attempted claim fails with the name of the sibling that is holding it.

This is the same mechanism MegaTask uses to pace its collision-derived waves, applied generally to any parent's subtasks.

Drift detection

Declarations are a plan, not a promise. When an assembled PR reaches the in-path gate, the reviewer's evidence includes a drift check: which files did the PR actually touch versus what was declared at delegation time? A sibling that touched files it never declared shows a drift callout on the collision map, so the reviewer can decide whether the overlap is harmless expansion or a real integration risk.

Why it matters

Without the collision map, sequencing decisions disappear after planning. With it, the reasoning stays visible: the task detail page shows the declared surface, the board shows sequence badges, and the gate reviewer sees drift. It turns "I think these two tasks conflict" into a checkable fact.

The map is advisory, not a gate

Collision detection never auto-blocks a task or a merge. It surfaces information for the PM, the developer, and the gate reviewer to act on. The actual ordering is enforced by the sequence field and the normal lifecycle — the map just makes the reasoning readable.

→ Tasks & Kanban for the panel view · Review & Quality for how findings and the gate reviewer use the map · MegaTask for collision-driven batch sequencing.

llms.txt