sprint-domain-router

sprint-domain-router

Consumes the annotated InternalTicket[] produced by sprint-ticket-ingestion and assigns each ticket to a domain coding agent using a four-signal weighted scoring model. Tickets that cannot be assigned with sufficient confidence are flagged for human review. Produces a routing result consumed by plan-generator.

Domain Agents

The five domain agents and their scopes are:

Agent	Scope
backend-coding-agent	API, services, business logic
frontend-coding-agent	UI, components, pages, Prismatic design system
db-coding-agent	Schema changes, migrations, queries
devops-coding-agent	Pipelines, Dockerfiles, infrastructure
security-coding-agent	Vulnerabilities, auth, CVEs

Governance Constraint

Only agents listed in governance.approvedDomainAgents (from the resolved config) are valid routing targets. If scoring would select an agent that is not in approvedDomainAgents, do not halt. Instead, record a governance warning in warnings and continue — the assignment is still recorded so that the plan file can surface it for human review.

Note: this differs from the spec's original 'suppress unapproved assignments' contract. Recording with a warning is preferred — it gives the human reviewer visibility into what would have been routed, rather than silently dropping tickets. plan-generator must display governance-warned tickets distinctly in the plan output.

Scoring Model

Compute a confidence score for each of the five domain agents independently. The final confidence for a domain is the sum of its four signal contributions.

Signal	Weight
Label match against labelMappings config	0.4
Component match	0.3
Issue type boost	0.2
Description keyword scan	0.1

Signal 1 — Label Match (weight 0.4)

For each domain agent:

1. Take the ticket's labels array.
2. Count how many labels appear in labelMappings[domain] for this domain.
3. Divide the hit count by the total number of labels on the ticket (minimum divisor of 1, to avoid division by zero).
4. Multiply by 0.4.

labelScore(domain) = (labelHits(domain) / max(len(ticket.labels), 1)) * 0.4

Signal 2 — Component Match (weight 0.3)

For each domain agent:

1. Take the ticket's components array.
2. Treat each component name as a label candidate and check whether it appears in any labelMappings[domain] value list for this domain.
3. Divide the hit count by the total number of components on the ticket (minimum divisor of 1).
4. Multiply by 0.3.

componentScore(domain) = (componentHits(domain) / max(len(ticket.components), 1)) * 0.3

Signal 3 — Issue Type Boost (weight 0.2)

Map the ticket's type field to a single domain agent using the table below. Apply the full 0.2 weight to the matched domain; all other domains receive 0.0 for this signal. Issue types that do not match any row receive no boost (Epic, Story, Task, and other generic types).

Issue Type	Boosted Agent
Infrastructure, DevOps, Deployment	devops-coding-agent
Security, Vulnerability	security-coding-agent
Database, Schema, Migration	db-coding-agent
Epic, Story, Task (generic)	No boost

Match is performed against each value individually (case-insensitive). Each cell lists multiple matching type names; any single one of them triggers the boost for that domain.

typeScore(domain) = 0.2 if issueType maps to domain, else 0.0

Signal 4 — Description Keyword Scan (weight 0.1)

For each domain agent:

1. Scan the ticket's plain-text description for any word that appears in labelMappings[domain] for this domain (case-insensitive whole-word match).
2. Each unique keyword hit increments that domain's raw keyword count.
3. After scanning all domains, normalise so that the maximum contribution across all domains from this signal is capped at 0.1.

Apply the cap per domain: if the raw keyword count for a domain exceeds what would produce 0.1, clamp to 0.1. Do not redistribute excess to other domains.

keywordScore(domain) = min(keywordHits(domain) * 0.1, 0.1)

Each unique keyword hit contributes 0.1 to that domain's score, capped at 0.1 total for this signal.

Total Confidence

confidence(domain) = labelScore + componentScore + typeScore + keywordScore

Maximum possible score is 1.0 (all four signals fully contribute to the same domain).

Assignment Rules

After computing confidence scores for all five domain agents for a ticket:

1. Select the domain agent with the highest confidence score.
2. If confidence ≥ 0.6 → assign the ticket to that agent (status: "assigned").
3. If confidence < 0.6 → flag the ticket for human review (status: "flagged"). Do not assign.
4. If two or more agents share the top score (tie) → flag the ticket regardless of whether the score meets the threshold. Include all tied candidates in flagged[].candidates.

Confidence Threshold Override

The default confidence threshold is 0.6. This value may be overridden by a ## Confidence Threshold section in the merged guidelines (from sprint-guidelines-ingestion). If that section is present, parse the numeric value it contains and use it in place of 0.6 for all assignment decisions in the current session.

Installed Agent Check

After completing all routing assignments, verify which approved domain agents are actually installed in the workspace. For each domain agent that has one or more tickets assigned to it, check for the presence of its config file in the workspace root:

Agent	Config File
backend-coding-agent	.backend-agent.json
frontend-coding-agent	.frontend-agent.json
db-coding-agent	.db-agent.json
devops-coding-agent	.devops-agent.json
security-coding-agent	.security-agent.json

If a config file is not present for an agent that has assigned tickets, add a warning to warnings:

WARNING: {agentName} has {n} ticket(s) assigned but does not appear to be installed
(expected config file: {configFile}).
The plan file will include an installation note.

This check does not change assignments. The routing result is unchanged; plan-generator is responsible for adding installation instructions to the plan output.

Output

Emit the following structured data after routing all tickets:

{
  "assignments": {
    "backend-coding-agent": ["PROJ-101", "PROJ-105"],
    "frontend-coding-agent": ["PROJ-102"],
    "db-coding-agent": [],
    "devops-coding-agent": ["PROJ-103"],
    "security-coding-agent": []
  },
  "flagged": [
    {
      "ticketId": "PROJ-104",
      "reason": "low-confidence",
      "topScore": 0.42,
      "topAgent": "backend-coding-agent",
      "candidates": ["backend-coding-agent"]
    },
    {
      "ticketId": "PROJ-106",
      "reason": "tie",
      "topScore": 0.65,
      "topAgent": null,
      "candidates": ["frontend-coding-agent", "backend-coding-agent"]
    }
  ],
  "routingDetails": [
    {
      "ticketId": "PROJ-101",
      "status": "assigned",
      "assignedAgent": "backend-coding-agent",
      "confidence": 0.82,
      "scores": {
        "backend-coding-agent": 0.82,
        "frontend-coding-agent": 0.10,
        "db-coding-agent": 0.00,
        "devops-coding-agent": 0.00,
        "security-coding-agent": 0.08
      }
    },
    {
      "ticketId": "PROJ-104",
      "status": "flagged",
      "assignedAgent": null,
      "confidence": 0.42,
      "scores": {
        "backend-coding-agent": 0.42,
        "frontend-coding-agent": 0.21,
        "db-coding-agent": 0.00,
        "devops-coding-agent": 0.00,
        "security-coding-agent": 0.05
      }
    }
  ],
  "warnings": [
    "GOVERNANCE: ticket PROJ-103 routed to devops-coding-agent which is not in approvedDomainAgents. Human review recommended.",
    "WARNING: devops-coding-agent has 1 ticket(s) assigned but does not appear to be installed (expected config file: .devops-agent.json). The plan file will include an installation note."
  ]
}

Field Reference

Field	Description
assignments	Map of agent name → array of assigned ticket IDs. All five agents are always present; empty array if no tickets assigned.
flagged	Array of ticket objects that could not be confidently assigned. Each entry includes ticketId, reason ("low-confidence" or "tie"), topScore, topAgent (null for ties), and candidates array.
routingDetails	Per-ticket breakdown including ticketId, status ("assigned" or "flagged"), assignedAgent (null if flagged), confidence (winning score), and scores map with the computed confidence for every domain agent. One entry is produced per input ticket, regardless of status. The complete list can be used to audit all routing decisions.
warnings	Ordered list of governance warnings (unapproved agents) and installation warnings (missing config files).