fix(squads): a broken seam becomes a ticket somebody owns

Every squad green and the assembled application broken is the defect this whole
design exists to catch: both halves passed their own tests and the seam between
them is wrong. It arrived as the least useful ticket the harness can produce.

The failure was routed through the QA path with a synthetic verdict reading
`qa_gate command still failing` / `qa_gate red`, so the integration command, the
output that names the seam, the contract clauses at stake and the team that owes
them were all discarded. What landed was a generic `worker` task with no files,
owned by nobody, whose entire context was that a gate was red — on the one
failure mode where the harness knows more than anywhere else.

Now the provider owes the clause. A consumer built against text it was handed;
the provider is the one that either implemented that text or drifted from it.
The ticket carries the command, the output, the clauses and the implicated
files, and the files are kept to the owing team's lane — if the output named
nothing there, the ticket ships unscoped rather than pointing at the other
half's files, because scoping a fix to the wrong half is worse than not scoping
it. With several providers the failure text decides, by naming a team or a path
inside its lane; when it names neither, the ticket stays unassigned, since an
unassigned ticket with real evidence beats one parked on a guess.

A seam that fails again bumps the existing ticket rather than stacking a second,
and the QA path no longer re-enters the tester rewrite for an integration
failure: its reopen pass would reopen halves that are green by definition, which
is precisely what "every squad passed and the seam is wrong" means.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UiLDxnEu1Gf8Q5hWAFhaAd

Author: claude

docs/changelog.md

@@ -215,6 +215,30 @@ list, because that list is widened by the very task matches the check exists to
 catch: computing from it would let the contamination declare the defect a
 straddle and disable the check exactly when it is needed.
 
+### Fixed — an integration failure raised the worst ticket in the harness
+
+Every squad green and the assembled application broken is the defect the whole
+squads design exists to catch. It arrived as the *least* useful ticket the
+harness can produce: the failure was routed through the QA path with a synthetic
+verdict reading `qa_gate command still failing` / `qa_gate red`, so the
+integration command, the output that names the seam, the contract clauses at
+stake and the team that owes them were all discarded. What landed was a generic
+`worker` task with no files, owned by nobody, whose entire context was that a
+gate was red.
+
+It now raises a real correction ticket: the provider owes the clause (a consumer
+built against text it was handed), the evidence rides along, and the implicated
+files are kept to the owing team's lane — if the output named nothing there, the
+ticket ships unscoped rather than pointing at the other half's files. With
+several providers the failure text decides; when it names neither a team nor a
+path in one's lane, the ticket stays unassigned, because an unassigned ticket
+with real evidence beats one parked on the wrong team.
+
+A seam that fails again bumps the existing ticket instead of stacking a second,
+and the QA path no longer re-enters the tester rewrite for it — its reopen pass
+would have reopened halves that are green by definition, which is exactly what
+"every squad passed and the seam is wrong" means.
+
 ### Added — the run summary says what it repaired
 
 `Todo app: Go API + React SPA — 2/2 tasks done, 0 failed` read exactly the same

docs/squads.md

@@ -293,6 +293,34 @@ hands the team back to the run's default manager.
 
 ---
 
+## When the halves do not fit 🔗
+
+Every squad green and the assembled application broken is the defect this whole
+design exists to catch: both halves passed their own tests and the seam between
+them is wrong.
+
+The integration command runs as soon as every squad is complete, and a failure
+raises a **ticket somebody owns** rather than a warning at the end of a
+"successful" run:
+
+- the **provider owes the clause** — a consumer built against text it was
+  handed, so the team that either implemented that text or drifted from it is
+  the one that gets the ticket;
+- the ticket carries the integration command, the output that names the seam,
+  the contract clauses at stake and the implicated files;
+- files are kept to the owing team's lane. If the output named nothing there,
+  the ticket ships unscoped rather than pointing at the other half's files.
+
+With several providers, the failure text decides — by naming a team or a path
+inside its lane. When it names neither, the ticket stays unassigned: a guess is
+worse than nothing, because an unassigned ticket with real evidence beats one
+parked on the wrong team.
+
+A seam that fails again is the same defect: the existing ticket's attempt count
+goes up rather than a second ticket appearing.
+
+---
+
 ## Safety: disjoint ownership 🛡️
 
 **Two squads may never own the same path.** They write concurrently; an overlap

pkg/orchestrator/resume.go

@@ -679,11 +679,21 @@ func (o *Orchestrator) runQualityGates(ctx context.Context, query string, board
 	integrationFailed := o.runSquadIntegration(ctx, out.Board)
 
 	out.QACmd = o.qaCommand()
-	out.QAFailed = o.runQAGate(ctx, query, out.Board) || integrationFailed
+	qaFailed := o.runQAGate(ctx, query, out.Board)
+	out.QAFailed = qaFailed || integrationFailed
 	if out.QAFailed {
 		out.TesterRejected = true
-		fake := `{"passed":false,"summary":"qa_gate command still failing","failures":["qa_gate red"]}`
-		_ = o.applyTesterFeedback(ctx, query, out.Board, fake)
+		// An integration failure has already raised its own ticket, carrying
+		// the command, the output that names the seam, the contract clauses at
+		// stake and the team that owes them. Re-entering the tester path with
+		// a synthetic `qa_gate red` verdict would throw all of that away and
+		// stack a second, generic ticket on top of the specific one — and its
+		// reopen pass would reopen halves that are green by definition, which
+		// is what "every squad passed and the seam is wrong" means.
+		if qaFailed {
+			fake := `{"passed":false,"summary":"qa_gate command still failing","failures":["qa_gate red"]}`
+			_ = o.applyTesterFeedback(ctx, query, out.Board, fake)
+		}
 		snap := o.boardStore.Snapshot()
 		out.Board = &snap
 		return out

pkg/orchestrator/squads.go

@@ -226,9 +226,89 @@ func (o *Orchestrator) runSquadIntegration(ctx context.Context, board *plan.Boar
 	o.emitWarn("integrate", "INTEGRATION FAILED — every squad is green but the assembled "+
 		"application is not. The seam is wrong: "+res.Summary, res.Output)
 	o.recordGate("integration", false, res.Summary)
+	o.raiseIntegrationTicket(board, gate.Command, res.Summary, res.Output)
 	return true
 }
 
+// raiseIntegrationTicket turns a failed join into a ticket somebody owns.
+//
+// This is the defect the whole squads design exists to catch — every half green
+// and the assembled application broken — and it used to arrive as the least
+// useful ticket the harness can produce. The QA path raised it with a synthetic
+// verdict reading `qa_gate command still failing` / `qa_gate red`, so the
+// command that failed, the output naming the seam, the interfaces at stake and
+// the team that owes them were all discarded. What landed was a generic
+// `worker` task with no files, owned by nobody, whose entire context was that a
+// gate was red.
+//
+// The contract knows who owes each clause, so the ticket goes to that team with
+// the evidence attached.
+func (o *Orchestrator) raiseIntegrationTicket(board *plan.Board, cmd, summary, output string) {
+	if o == nil || board == nil {
+		return
+	}
+	squad, clauses := squads.SeamOwner(o.squadPlan, output)
+	failures := []string{"the halves do not fit together: " + firstSentence(summary)}
+	for _, c := range clauses {
+		failures = append(failures, "contract clause at stake: "+c)
+	}
+
+	in := plan.CorrectionInput{
+		Source:   plan.SourceIntegration,
+		Failures: failures,
+		Summary:  summary,
+		Command:  cmd,
+		Output:   output,
+		// Files the integration output actually named, kept to the owing team's
+		// lane: a bundler error listing half the tree would otherwise scope the
+		// ticket to everything.
+		Files: o.seamFiles(output, squad),
+		Squad: squad,
+	}
+	key := plan.CorrectionKey(in)
+	in.Attempt = board.CorrectionAttempts(key)
+	if board.NoteRepeatedRejection(key) > 0 {
+		o.persistBoard(board)
+		return
+	}
+	var hasRole func(string) bool
+	if o.factory != nil {
+		hasRole = o.factory.HasRole
+	}
+	ticket := plan.NewCorrectionTicket(in, hasRole)
+	plan.StampCorrectionKey(&ticket, key)
+	plan.StampCorrectionAttempt(&ticket, in.Attempt+1)
+	board.AddTask(ticket)
+	o.persistBoard(board)
+
+	where := "unassigned"
+	if squad != "" {
+		where = squad
+	}
+	o.emit("integrate", fmt.Sprintf("raised an integration ticket for %s → %s", where, ticket.Role), ticket.ID)
+}
+
+// seamFiles is the paths the integration output named, narrowed to one team's
+// lane when a team owes the seam.
+func (o *Orchestrator) seamFiles(output, squad string) []string {
+	named := squads.PathsIn(output)
+	if squad == "" || o.squadPlan == nil {
+		return limitList(named, 8)
+	}
+	var mine []string
+	for _, f := range named {
+		if owner, ok := o.squadPlan.Owner(f); ok && owner == squad {
+			mine = append(mine, f)
+		}
+	}
+	if len(mine) == 0 {
+		// The output named nothing in this team's lane. Better an unscoped
+		// ticket with the evidence than one scoped to the other half's files.
+		return nil
+	}
+	return limitList(mine, 8)
+}
+
 // routeBoardToSpecialists assigns every task the specialist its own files call
 // for, after squads have been assigned.
 //

pkg/orchestrator/squads_test.go

@@ -1099,3 +1099,111 @@ func TestATicketIsReStaffedAtMostOnce(t *testing.T) {
 		t.Errorf("asked %q for a second verdict on a ticket that already changed hands", exec.askedAgent)
 	}
 }
+
+// ── An integration failure is a ticket, not a warning ────────────────────
+//
+// Every squad green and the assembled application broken is the defect the
+// whole design exists to catch. It used to arrive as the least useful ticket
+// the harness can produce: the QA path raised it with a synthetic
+// `qa_gate command still failing` verdict, so the command, the output naming
+// the seam, the contract clauses and the team that owes them were all
+// discarded — leaving a generic `worker` task with no files, owned by nobody.
+
+func seamOrchestrator(t *testing.T) *Orchestrator {
+	t.Helper()
+	p := &squads.Plan{
+		Squads: []squads.Squad{
+			{ID: "backend", Owns: []string{"cmd/**", "internal/**"}, Acceptance: "go test ./...", Worker: "go-worker"},
+			{ID: "frontend", Owns: []string{"web/**"}, Acceptance: "npm run build", Worker: "react-worker"},
+		},
+		Contract: squads.Contract{Interfaces: []squads.Interface{
+			{ID: "GET /api/todos", Provider: "backend", Consumers: []string{"frontend"},
+				Spec: "200 -> [{id,title,done}]"},
+		}},
+	}
+	p.Normalize()
+	o, _ := routingOrchestrator(t, p)
+	return o
+}
+
+func TestAnIntegrationFailureRaisesATicketWithTheEvidence(t *testing.T) {
+	o := seamOrchestrator(t)
+	board := &plan.Board{Tasks: []plan.Task{
+		{ID: "T1", Role: "go-worker", Squad: "backend", Column: plan.ColDone, Files: []string{"cmd/server/main.go"}},
+		{ID: "T2", Role: "react-worker", Squad: "frontend", Column: plan.ColDone, Files: []string{"web/src/App.tsx"}},
+	}}
+	const output = "cmd/server/main.go:41: returned {items:[]}, the contract says a bare array"
+
+	o.raiseIntegrationTicket(board, "go test ./... && npm run build", "the halves do not agree on the response shape", output)
+
+	var ticket *plan.Task
+	for i := range board.Tasks {
+		if plan.CorrectionKeyOf(board.Tasks[i]) != "" {
+			ticket = &board.Tasks[i]
+		}
+	}
+	if ticket == nil {
+		t.Fatal("an integration failure must produce a ticket somebody owns")
+	}
+	// The provider owes the clause: the consumer built against text it was handed.
+	if ticket.Squad != "backend" {
+		t.Errorf("Squad = %q, want the team that provides the broken interface", ticket.Squad)
+	}
+	// A .go file means the Go specialist, not the generic worker.
+	if !strings.HasPrefix(ticket.Role, "go-") {
+		t.Errorf("Role = %q, want the specialist the implicated file calls for", ticket.Role)
+	}
+	// The evidence that used to be thrown away.
+	for _, want := range []string{
+		"go test ./... && npm run build", // how to reproduce it
+		"{items:[]}",                     // what it printed
+		"GET /api/todos",                 // which clause is at stake
+		"cmd/server/main.go",             // where
+	} {
+		if !strings.Contains(ticket.Description, want) {
+			t.Errorf("the ticket is missing %q:\n%s", want, ticket.Description)
+		}
+	}
+	if len(ticket.Files) == 0 {
+		t.Error("the ticket has no files, so nothing scopes the fix")
+	}
+}
+
+// The same broken seam on the next round is the same defect. Stacking a ticket
+// per integration run is how a board loses the plot.
+func TestARepeatedSeamFailureBumpsTheTicketRatherThanStackingOne(t *testing.T) {
+	o := seamOrchestrator(t)
+	board := &plan.Board{}
+	const output = "cmd/server/main.go:41: returned {items:[]}"
+
+	o.raiseIntegrationTicket(board, "make check", "shape mismatch", output)
+	o.raiseIntegrationTicket(board, "make check", "shape mismatch", output)
+
+	tickets := 0
+	for _, task := range board.Tasks {
+		if plan.CorrectionKeyOf(task) != "" {
+			tickets++
+			if got := plan.CorrectionAttemptOf(task); got != 2 {
+				t.Errorf("attempt = %d, want the repeat recorded on the one ticket", got)
+			}
+		}
+	}
+	if tickets != 1 {
+		t.Errorf("%d tickets on the board, want 1", tickets)
+	}
+}
+
+// Scoping a ticket to the OTHER half's files is worse than not scoping it.
+func TestASeamTicketNeverScopesToTheOtherTeamsFiles(t *testing.T) {
+	o := seamOrchestrator(t)
+	if got := o.seamFiles("web/src/App.tsx:12: boom", "backend"); len(got) != 0 {
+		t.Errorf("seamFiles = %v, want nothing rather than the frontend's files", got)
+	}
+	if got := o.seamFiles("cmd/server/main.go:41: boom", "backend"); len(got) != 1 || got[0] != "cmd/server/main.go" {
+		t.Errorf("seamFiles = %v, want the owning team's file", got)
+	}
+	// With nobody owing the seam, everything named is still useful context.
+	if got := o.seamFiles("web/src/App.tsx:12: boom", ""); len(got) != 1 {
+		t.Errorf("seamFiles(unowned) = %v, want the named path kept", got)
+	}
+}