@@ -629,6 +629,7 @@ GO_GENERATE_PACKAGES := \
 	./stovepipe/controller/... \
 	./stovepipe/core/requestlog/... \
 	./stovepipe/extension/buildrunner/... \
+	./stovepipe/extension/fixer/... \
 	./stovepipe/extension/projectstatus/... \
 	./stovepipe/extension/queueconfig/... \
 	./stovepipe/extension/sourcecontrol/... \
 
@@ -8,6 +8,8 @@ The pipeline is a queue-driven chain of small, single-purpose controllers, in th
 
 The planned `buildanalysis` step runs alongside that chain: it extracts details periodically while a build runs and performs a final pass after completion. The [workflow diagram](#workflow) shows the full intended flow through breakage tracking, repair decisions, execution, and recovery; [Build analysis](#build-analysis) describes the extraction step.
 
+The [repair workflow](#repair-workflow) branches from build observations: planned breakage tracking requests repairs for broken checks and supplies later recovery evidence. Queue messages and Go extension contracts are defined; the stage implementations, persistence, and wiring follow the repair RFC.
+
 There is no `analyze` controller and no `analyze` topic. A later project-analysis stage that would map a target graph onto another `build` pass is design only, described under [Designed, not built](#designed-not-built-project-analysis). `record` resolves project results inline on the same delivery that writes the repository fact.
 
 ## What Stovepipe is agnostic about
@@ -53,13 +55,18 @@ A Queue may have a **promotion ref**: a stable branch name (say `verified-main`
 
 The ref is a *cache* of the last-green URI, not a second record of greenness. It only ever moves where the bookmark already points, so it inherits the same forward-only rule, and a commit that a history rewrite has dropped from the branch is skipped rather than retried — the next green commit corrects the ref. Which ref a Queue promotes to, and whether it has one at all, is `SourceControl` configuration resolved from the Queue name alongside the repo and credentials; the pipeline names only the commit, never a branch.
 
+### Breakage and fix — failure episodes and shared repairs
+
+A [`Breakage`](../../../stovepipe/entity/fix.go) identifies one episode of a failing check by `(Queue, Key, Generation)` and references its build and failure observation. Planned breakage tracking owns health and generations. The repair design adds an evaluator that decides whether to start a fix, attach the episode to an existing fix, or wait for more evidence. A `Fix` can cover several episodes, with recovery recorded independently for each.
+
 ## Extensions
 
 | Extension | Responsibility |
 |---|---|
 | **SourceControl** | Resolve a Queue name to its current head URI; answer ancestry/comparison questions between two URIs (is the new head a fast-forward descendant of the last green, or was history rewritten?); enumerate commits in a range; advance the Queue's **promotion ref** to a commit. The sole owner of URI semantics, including which refs a Queue name resolves to. |
 | **build-runner** | Build a scope at a URI, optionally relative to a baseline URI. `Trigger` returns a build id; `Status` returns pass/fail and the caller-supplied metadata it echoed. It does not return a target graph. See [build-runner.md](../submitqueue/build-runner.md). |
 | **buildanalysis.Analyzer** (planned) | Extract available check results and evidence from a referenced Build. Resolve provider-specific artifacts through injected dependencies and report completeness and coverage. |
+| **fixer** (design) | `RepairEvaluator` recommends Start, Attach, or Defer before dispatch. [`RepairExecutor`](../../../stovepipe/extension/fixer/fixer.go) submits and observes the selected repair. Host wiring supplies both implementations. Evaluation and runtime coordination remain to be implemented; see [fixer.md](fixer.md#implementation). |
 | **Hooks** | Deliver Stovepipe's validation events to downstream systems. What is published today is repository-scoped: validation of this URI has begun, this URI is green or not green, and a cancelled validation ended without a fact. Fire-and-forget notification, decoupled so Stovepipe does not know or care who consumes the event. The shared cross-domain hook seam rather than a Stovepipe-specific extension. See [hook-framework.md](../hook-framework.md). |
 | **Storage** | Persist Queues (incl. last-green URI), Requests, build records, and per-URI / per-project greenness. Key/value-shaped per the extension-design rules in [AGENTS.md](../../../AGENTS.md). |
 
@@ -155,6 +162,18 @@ Add `stovepipe/controller/buildanalysis.Controller` implementing [`consumer.Cont
 
 The initial and completion handoffs follow the existing persist-then-publish retry pattern. Analysis holds only its own per-build partition. Versioned writes make repeated polls and completion signals converge while preserving final results against stale updates. Downstream breakage tracking determines failure episodes and recovery from this evidence.
 
+### Repair workflow
+
+The repair branch defines asynchronous work alongside validation. The queue contracts are present; the `fix` and `fixsignal` implementations and registration follow the [repair RFC](fixer.md#implementation). Both stages use [`consumer.Controller.Process`](../../../platform/consumer/controller.go). The planned [buildanalysis step](#build-analysis) persists observations during and after execution. Breakage tracking uses that evidence to maintain failure episodes and recovery; it is a planned responsibility, with its runtime integration defined separately. Validation capacity, result recording, hooks, and promotion remain independent of repair progress.
+
+1. **Persist and publish the episode.** Breakage tracking stores a pending `FixBinding` with the check key, generation, and failure evidence, then publishes [`FixRequest`](../../../stovepipe/core/messagequeue/proto/fix.proto) to `TopicKeyFix`. The message carries only the queue and episode identity. A failed shard can initiate this step while the build is running.
+2. **Evaluate existing work.** `fix.Controller.Process` reloads the episode and invokes [`fixer.RepairEvaluator`](../../../stovepipe/extension/fixer/fixer.go) for an unassigned failure. The evaluator compares the failure with compatible active repairs and dispatch reservations. It recommends Start, Attach with a fix ID, or Defer. Resolve detailed evidence through host-supplied dependencies.
+3. **Commit the decision.** Recheck the episode and selected repair, persist ownership and membership, then publish [`FixSignal`](../../../stovepipe/core/messagequeue/proto/fixsignal.proto) to `TopicKeyFixSignal`. A versioned active-work record guards new reservations; conflicting admissions reevaluate with the accepted reservation visible. Deferred requests use `delivery.Hold(...)` under a bounded waiting policy.
+4. **Execute and coordinate.** `fixsignal.Controller.Process` reloads the repair and episode bindings, submits accepted starts through `RepairExecutor`, and holds the delivery between observations. An attachment follows the existing repair. A worker that discovers overlap later records a reassociation intent and signals the affected episodes; the host protocol coordinates publication ownership.
+5. **Apply recovery.** Breakage tracking persists recovery evidence and publishes a new `FixRequest` intent. `fix` resolves an unassigned episode or signals its assigned repair; `fixsignal` reloads the bindings and updates resolution. With failure-only reports, absence establishes recovery after complete, comparable validation. Continue observing execution until it is settled or stopped.
+
+The [repair RFC](fixer.md) defines the decisions, concurrency rules, persistence, and integration requirements.
+
 ### Designed, not built: project analysis
 
 An `analyze` stage is not part of the pipeline. `stovepipe/core/messagequeue` has no analyze topic, and `stovepipe/controller` has no analyze package. The design, still only a design, is a stage that would take a build's target graph, map broken or at-risk targets to projects, and publish project-scoped builds back through `build` → `buildsignal` → `record`. That second pass, a per-project hook event, and intermediate greenness degrees are not what the controllers do. Open questions for that design stay at the bottom of this doc.
@@ -170,15 +189,18 @@ An `analyze` stage is not part of the pipeline. `stovepipe/core/messagequeue` ha
 | **buildanalysis** (planned) | BuildID after creation or completion; periodic redelivery | Persisted build observations | Extract check results and evidence while active and at completion; publish references for downstream analysis and breakage tracking |
 | **record** | RequestID | hook topic | Write whole-repo greenness; resolve project results inline; on green advance last-green URI and the promotion ref; publish the recorded or cancelled repository hook event |
 | **hook** | HookEvent | — | Invoke the hooks the resolver returns. The example server resolves every event to noop |
+| **fix** (planned) | `FixRequest`: queue, check key, generation | `FixSignal` or held delivery | Reload episode; apply Start/Attach/Defer or hand off recovery → [fixer.md](fixer.md) |
+| **fixsignal** (planned) | `FixSignal`: queue, fix ID | Persisted execution/resolution or held delivery | Submit accepted repairs, observe execution, and apply recorded episode recovery → [fixer.md](fixer.md) |
 
 ## Step RFCs
 
-Per-stage design detail lives under `steps/` so this doc stays a pipeline overview:
+Detailed workflow contracts and behavior:
 
 - [process.md](steps/process.md) — build-strategy decision, concurrency gate, backlog coalescing, [concurrency lifecycle](steps/process.md#concurrency-lifecycle), entity changes, [waiting for a slot](steps/process.md#waiting-for-a-slot)
 - [build.md](steps/build.md) — trigger-only stage: reads the decided scope off the Request, triggers the build-runner, hands off to buildsignal; the stovepipe `BuildRunner` contract and why it differs from SubmitQueue's
 - [buildsignal.md](steps/buildsignal.md) — the poll loop: hold-based re-poll cadence, per-build partitioning, and the fail-closed handoff to record
 - [record.md](steps/record.md) — turning a terminal build outcome into an immutable validation fact, monotonic last-green advancement and ref promotion, and the hook event announcing the outcome. Its Phase 2 / analyze handoff is the unbuilt design, not a topic `record` publishes
+- [fixer.md](fixer.md) — `fix` and `fixsignal` queue stages, Start/Attach/Defer evaluation, durable ownership, execution, and per-episode recovery
 
 ## Dedup, idempotency, and history rewrites
 
 
@@ -10,3 +10,12 @@ Payloads are defined in proto3 (`proto/`, generated into `protopb/`) and seriali
 - **build** (`TopicKeyBuild`, `BuildRequest`) — process publishes the request id here once its build scope (`BuildStrategy`/`BaseURI`) is decided; the build controller reloads the `Request`, triggers the build, and persists the resulting `Build`. Partitioned by request id.
 - **buildsignal** (`TopicKeyBuildSignal`, `BuildSignal`) — build publishes the build id here after triggering; buildsignal holds the delivery between polls until the build reaches a terminal status. Partitioned by build id, so each build's poll loop is an independent partition.
 - **record** (`TopicKeyRecord`, `Record`) — buildsignal publishes the request id after persisting the terminal outcome; record reloads the request and records its validation fact. Partitioned by request id.
+
+## Repair stage contracts
+
+The repair messages and topic keys are defined for the [repair design](../../../doc/rfc/stovepipe/fixer.md). Controller implementations and runtime registration follow in the implementation layers. Both stages use the existing `consumer.Controller` interface.
+
+- **fix** (`TopicKeyFix`, [`FixRequest`](proto/fix.proto)) — breakage tracking persists an episode's repair request or recovery evidence, then publishes its queue, check key, and generation. Processing reloads the episode, evaluates Start/Attach/Defer for an unassigned failure, or signals the existing repair. Partitioned by episode identity.
+- **fixsignal** (`TopicKeyFixSignal`, [`FixSignal`](proto/fixsignal.proto)) — fix processing publishes the repair ID after persisting a decision or observing an assigned episode's recovery. Processing reloads the repair and its episode bindings to submit, observe execution, and apply recovery. Partitioned by repair ID, with held deliveries between observations.
+
+Each durable episode update has a distinct publication intent; retries reuse that intent. A recovery update re-enters through `fix`, so processing can resolve either a pending request or an already assigned repair using the current stored ownership.
@@ -53,6 +53,12 @@ type (
 	// Record is the payload buildsignal publishes to the record stage once a
 	// build reaches a terminal status: the build id to record.
 	Record = protopb.Record
+
+	// FixRequest identifies a persisted failure episode whose assignment needs processing.
+	FixRequest = protopb.FixRequest
+
+	// FixSignal identifies a persisted repair whose execution and recovery need processing.
+	FixSignal = protopb.FixSignal
 )
 
 // marshalOpts keeps the JSON field names identical to the proto field names
 
@@ -66,6 +66,45 @@ func TestRecordRoundTrip(t *testing.T) {
 	assert.True(t, proto.Equal(rec, got), "round-tripped Record should equal the original")
 }
 
+func TestFixMessagesRoundTrip(t *testing.T) {
+	for _, tt := range []struct {
+		name    string
+		message proto.Message
+	}{
+		{
+			name: "episode request",
+			message: &FixRequest{
+				QueueName:  "repo/main",
+				Key:        "checks/package:compile",
+				Generation: 9007199254740993,
+			},
+		},
+		{
+			name:    "repair signal",
+			message: &FixSignal{QueueName: "repo/main", Id: "repair-42"},
+		},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			data, err := Marshal(tt.message)
+			require.NoError(t, err)
+			got := tt.message.ProtoReflect().New().Interface()
+			require.NoError(t, Unmarshal(data, got))
+			assert.True(t, proto.Equal(tt.message, got))
+		})
+	}
+}
+
+func TestFixRequestWireFormat(t *testing.T) {
+	message := &FixRequest{QueueName: "repo/main", Key: "check-a", Generation: 9007199254740993}
+	data, err := Marshal(message)
+	require.NoError(t, err)
+	assert.JSONEq(t, `{"queue_name":"repo/main","key":"check-a","generation":"9007199254740993"}`, string(data))
+
+	var got FixRequest
+	require.NoError(t, Unmarshal([]byte(`{"queue_name":"repo/main","key":"check-a","generation":"9007199254740993","future_field":true}`), &got))
+	assert.True(t, proto.Equal(message, &got))
+}
+
 // TestWireFormat locks the protojson encoding decision the contract relies on:
 // snake_case field names (UseProtoNames).
 func TestWireFormat(t *testing.T) {
@@ -80,7 +119,7 @@ func TestWireFormat(t *testing.T) {
 // no topic_keys option names an unknown key.
 func TestTopicKeysBindEveryTopicKey(t *testing.T) {
 	bound := map[string]int{}
-	for _, m := range []proto.Message{&ProcessRequest{}, &BuildRequest{}, &BuildSignal{}, &Record{}} {
+	for _, m := range []proto.Message{&ProcessRequest{}, &BuildRequest{}, &BuildSignal{}, &Record{}, &FixRequest{}, &FixSignal{}} {
 		keys := TopicKeys(m)
 		require.NotEmpty(t, keys, "message must declare a non-empty topic_keys option")
 		for _, key := range keys {
@@ -93,6 +132,8 @@ func TestTopicKeysBindEveryTopicKey(t *testing.T) {
 		TopicKeyBuild,
 		TopicKeyBuildSignal,
 		TopicKeyRecord,
+		TopicKeyFix,
+		TopicKeyFixSignal,
 	}
 
 	valid := map[string]bool{}
 
@@ -2,6 +2,8 @@ exports_files(
     [
         "build.proto",
         "buildsignal.proto",
+        "fix.proto",
+        "fixsignal.proto",
         "process.proto",
         "record.proto",
     ],
 
@@ -0,0 +1,37 @@
+// Copyright (c) 2026 Uber Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package uber.stovepipe.messagequeue;
+
+import "api/base/messagequeue/proto/messagequeue.proto";
+
+option go_package = "github.com/uber/submitqueue/stovepipe/core/messagequeue/protopb";
+option java_multiple_files = true;
+option java_outer_classname = "FixRequestProto";
+option java_package = "com.uber.submitqueue.stovepipe.messagequeue";
+
+// FixRequest references a durable episode request; evidence and assignment are loaded from storage.
+// Publishing requires the episode state to have been persisted first.
+message FixRequest {
+    option (uber.base.messagequeue.topic_keys) = "fix";
+
+    // queue_name identifies the validation queue containing the episode.
+    string queue_name = 1;
+    // key is the opaque check identity within the queue.
+    string key = 2;
+    // generation distinguishes a recurrence after recovery from the previous failure episode.
+    int64 generation = 3;
+}
@@ -0,0 +1,35 @@
+// Copyright (c) 2026 Uber Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package uber.stovepipe.messagequeue;
+
+import "api/base/messagequeue/proto/messagequeue.proto";
+
+option go_package = "github.com/uber/submitqueue/stovepipe/core/messagequeue/protopb";
+option java_multiple_files = true;
+option java_outer_classname = "FixSignalProto";
+option java_package = "com.uber.submitqueue.stovepipe.messagequeue";
+
+// FixSignal references a durable repair; execution and episode recovery are loaded from storage.
+// Publishing requires the repair and its episode associations to have been persisted first.
+message FixSignal {
+    option (uber.base.messagequeue.topic_keys) = "fixsignal";
+
+    // id is the queue-scoped repair identifier.
+    string id = 1;
+    // queue_name identifies the validation queue containing the repair.
+    string queue_name = 2;
+}
@@ -5,6 +5,8 @@ go_library(
     srcs = [
         "build.pb.go",
         "buildsignal.pb.go",
+        "fix.pb.go",
+        "fixsignal.pb.go",
         "process.pb.go",
         "record.pb.go",
     ],
Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,8 @@ exports_files(`
`2`	`2`	`[`
`3`	`3`	`"build.proto",`
`4`	`4`	`"buildsignal.proto",`
	`5`	`+ "fix.proto",`
	`6`	`+ "fixsignal.proto",`
`5`	`7`	`"process.proto",`
`6`	`8`	`"record.proto",`
`7`	`9`	`],`