sprint-dependency-mapper

sprint-dependency-mapper

Consumes InternalTicket[] from ticket-ingestion and the routing assignments map from domain-router. Produces a dependency graph with execution waves that plan-generator uses to sequence agent work.

Inputs

Input	Type	Source	Description
tickets	InternalTicket[]	sprint-ticket-ingestion	Normalised ticket objects including links[] ({ type, targetId }) for each ticket
assignments	{ [agentName]: string[] }	sprint-domain-router	Map of domain agent name → array of assigned ticket IDs; flagged tickets (those not in any agent's list) are excluded from dependency computation

InternalTicket Link Schema

Each entry in ticket.links is an object with two fields:

{ "type": "blocks" | "is blocked by" | "relates to", "targetId": "PROJ-124" }

Only tickets present in the current sprint (i.e., IDs appearing as keys in the flattened assignments map) are eligible for edges.

Explicit Links

Process each ticket's links array to derive directed edges. Apply the following interpretation for each link type:

Link type	Ordering constraint	Edge direction
blocks	Source ticket must complete before target ticket	source → target
is blocked by	Target ticket must complete before source ticket	target → source
relates to	No ordering constraint	Ignored — not added to DAG

In all edge objects in the output, from is the predecessor (must complete first) and to is the successor (depends on from).

Out-of-Sprint Filtering

Before adding any edge, verify both the source ticket ID and the targetId are present in the sprint's ticket set (flattened assignments map, including all five agent buckets).

• If targetId is not in the current sprint, do not add the edge. Add the targetId to the ignoredLinks output array.
• If both endpoints are in the sprint, add the edge and record "source": "explicit:<linkType>" on the edge object. is blocked by links use the slug "explicit:is-blocked-by" (hyphenated, matching the inferred-rule slug pattern).

Inferred Ordering Rules

After processing all explicit links, apply the four inferred rules below. Each rule fires only when no explicit edge already exists between the two candidate tickets (in either direction).

Rule	Condition	Edge added
DB before backend	A ticket is assigned to db-coding-agent AND another ticket is assigned to backend-coding-agent, with no existing explicit link between them	db-ticket → backend-ticket
Backend before frontend	A ticket is assigned to backend-coding-agent AND another ticket is assigned to frontend-coding-agent, with no existing explicit link between them	backend-ticket → frontend-ticket
DevOps setup first	A ticket is assigned to devops-coding-agent AND its title or description contains any of the keywords: setup, environment, infra, or provision (case-insensitive)	devops-setup-ticket → every-other-ticket (excluding other devops setup tickets)
Security — no inferred order	Tickets assigned to security-coding-agent receive no inferred ordering edges	No edge added

Inferred Rule Application Details

DB before backend and Backend before frontend apply pairwise across their respective agent buckets. For each (db-ticket, backend-ticket) pair, if no explicit edge exists between that specific pair, add one inferred edge. Repeat for each (backend-ticket, frontend-ticket) pair.

DevOps setup first applies to each qualifying devops ticket individually. A devops ticket qualifies if any of the four trigger keywords appear in its title or description (case-insensitive substring match). For each qualifying ticket, add one inferred edge from it to every other sprint ticket that is not itself a devops setup ticket. This rule intentionally bypasses the no-explicit-link guard — it is a global prerequisite and adds edges regardless of pre-existing explicit links between tickets.

No existing explicit link is evaluated as: does any edge in the current explicit edge set connect these two ticket IDs in either direction?

Record "source": "inferred:<rule-name>" on each edge added by inference, using the rule name slugs: db-before-backend, backend-before-frontend, devops-setup-first.

Cycle Detection and Breaking

After all edges (explicit + inferred) are added, run a depth-first topological sort over the full graph.

Cycle Detection

If the DFS finds a back edge, a cycle exists. Collect the cycle members (all ticket IDs involved in the cycle path).

Cycle Breaking

To break the cycle, identify removable edges within the cycle and remove the one with the lowest priority using the table below:

Priority	Edge source
Highest	inferred:devops-setup-first
Middle	inferred:db-before-backend
Lowest (among inferred)	inferred:backend-before-frontend

The table above ranks edges by their importance to preserve. Cycle breaking removes the entry with the lowest preservation priority first.

Remove the lowest-priority inferred edge found within the cycle. If multiple edges share the same lowest priority, remove the one added last (latest in insertion order).

If the cycle contains only explicit edges: remove the explicit edge added last and flag all involved tickets.

Add all ticket IDs in the cycle to cycleWarnings.

Iteration Limit

After breaking a cycle, re-run the topological sort. Repeat until no cycles remain or the iteration count reaches 10. If cycles remain after 10 iterations, halt and surface the remaining cycle members in cycleWarnings with the note: "unresolved after max iterations".

Wave Computation

Compute execution waves from the acyclic graph produced after cycle breaking:

• Wave 1: All tickets with no incoming edges (no dependencies).
• Wave N+1: All tickets whose every dependency (direct predecessors) is already placed in a wave ≤ N.

Tickets in the same wave have no ordering constraint between them and can be executed in parallel. Each ticket appears in exactly one wave.

Tickets that were flagged by domain-router (not present in any assignments bucket) are excluded from wave computation and do not appear in executionWaves.

If all tickets are excluded (all flagged by domain-router or sprint has no eligible assignments), executionWaves is an empty array.

Output

Emit the following structured data for consumption by plan-generator:

{
  "executionWaves": [["PROJ-126", "PROJ-128"], ["PROJ-123"], ["PROJ-125"]],
  "edges": [
    { "from": "PROJ-123", "to": "PROJ-125", "source": "inferred:backend-before-frontend" },
    { "from": "PROJ-126", "to": "PROJ-123", "source": "explicit:blocks" }
  ],
  "cycleWarnings": [],
  "ignoredLinks": ["PROJ-999"]
}

Field Reference

Field	Type	Description
executionWaves	string[][]	Ordered array of waves; each inner array holds ticket IDs that can run in parallel. Wave 1 is index 0.
edges	object[]	All edges in the final DAG after cycle breaking. Each edge has from, to, and source (e.g., "explicit:blocks", "inferred:db-before-backend").
cycleWarnings	string[]	Ticket IDs that were members of a detected cycle. Empty array if no cycles were found. Includes the string "unresolved after max iterations" appended to the last entry if the 10-iteration limit was reached.
ignoredLinks	string[]	targetId values from links that pointed to tickets outside the current sprint. These links were skipped without error.