orchestra/DEBT-DESIGN.md

Debt ledger: design from what the tree already supports

Written 2026-08-29 against 3c7cf95. Read with BURNIN.md (the run ledger), PLAN-SPEC-DESIGN.md and AUDIT.md.

This is a design, not an implementation. Nothing here has been built.

The problem being solved

AI raises implementation throughput faster than it raises integration, cleanup, observability, consolidation and architectural understanding. The residue is fixes, compatibility paths, operational workarounds, duplicate config, adapter gaps and one-off patches. Some are justified. Some become permanent because nobody remembers why they were added or what they have cost since.

The target is a first-class debt ledger driven by evidence from real tasks, not a second TODO list.

Classes

Four, and no more. A fifth class invented at runtime makes the priority model meaningless.

Class	Meaning
correctness	Known behaviour is wrong or violates an invariant.
operational	The system works, but diagnosis, recovery, deployment, observability or operation repeatedly costs time.
structural	Duplication or architecture is demonstrably raising the cost of future changes.
polish	Cleanup or consistency work with no demonstrated cost yet.

Correctness and operational debt gain priority quickly. Structural debt needs evidence that it is causing repeated work. Polish never becomes work on its own.

1. What Orchestra already has

The event log is the durable spine, and it already carries most of what a debt ledger needs. Every row below is mechanically countable today, with no new instrumentation.

Evidence	Source	Carries
Failure shape	TaskFailed, TaskBlocked	12 typed block_reason values, 6 failure_class values
Retry cost	Task.Attempt, NextRetryAt, FailureClass	how many leases a task burned, durable in the projection
Review findings	ReviewRecorded	{ID, Severity, File, Line, Claim, Evidence}, bound to a ResultSHA
Out-of-scope discoveries	DeferredFindingRecorded	{Summary, Why}, already recorded outside agent context
Plan contradicted by code	PlanMismatchRecorded	{PlanRef, PhaseID, AtSHA, Observed, Contradicts, Evidence[]}
Verification history	PlanPhaseVerified	{Commands, ExitCodes, AtSHA, EvidenceRef} per phase
Rework rounds	TaskChangesRequested, TaskSubmitted	how many times a change went back
Provenance	TaskCreated	Source, ExternalID, Parent

Three existing patterns matter more than the data.

Global-subject events already work. QuotaReported and StandupAdvisory use TaskID: "system" and are whitelisted in internal/domain/domain.go:279. A debt item needs no new subject mechanism.

GenerateStandupAdvisory is the precedent for the shape. It is a persisted, read-only recommendation, and applying it is a separate approval-gated operation. A debt ledger is that pattern with better inputs.

CheckSubmission is the precedent for eligibility. It is a pure function of task, commit and gate run, returning {Eligible bool, Reasons []string}. Debt eligibility should have the same shape.

2. What evidence is missing

Worker observations are not durable. This is the largest gap. The F18 ring lives in worker memory and reaches the coordinator inside WorkerHealth on heartbeat. Registry.persistedState holds captures, commands and workers only, with no health. A coordinator restart erases every observation.

Operational debt is exactly what that ring holds. Repeated 409s, unrenewed leases, adapter gaps.

No operator-intervention record. Every manual repair in run 12 and run 13 left no trace in Orchestra. State-file edits, worker restarts, two manual transaction cleanups. "Required manual recovery" is the strongest priority signal available, and it is currently unrecorded.

No diagnosis-cost signal. Time spent diagnosing is not measured. The closest proxy is wall time in blocked or needs_attention.

No component dimension. Findings carry file paths. Tasks carry none. Breadth across components has to be derived from paths.

No link from a repair commit back to what it repaired. The Fxx-to-commit mapping exists only in BURNIN.md prose.

Deferred findings are too thin. {Summary, Why} has no class, no severity, no paths and no evidence refs.

3. Minimal durable data model

No new subsystem. Two event types on the existing spine, one projection beside Task.

// DebtObservation is one piece of counted evidence, always pointing at the
// event that produced it. Provenance is an event id, never prose.
type DebtObservation struct {
    // Exactly one of EventID and LegacyRef. See section 8.
    EventID   string    `json:"event_id,omitempty"`
    LegacyRef string    `json:"legacy_ref,omitempty"`
    TaskID    string    `json:"task_id,omitempty"`
    Kind      string    `json:"kind"`      // block_reason, failure_class, review_finding,
                                           // plan_mismatch, manual_intervention, deferred_finding
    Signature string    `json:"signature"` // the mechanical dedup key, see section 4
    Detail    string    `json:"detail"`
    Paths     []string  `json:"paths,omitempty"`
    At        time.Time `json:"at"`
}

type DebtItem struct {
    ID             string            `json:"id"`     // continues the Fxx namespace
    Class          DebtClass         `json:"class"`  // correctness, operational, structural, polish
    Status         DebtStatus        `json:"status"` // observed, eligible, scheduled, repaired, withdrawn
    Symptom        string            `json:"symptom"`
    Consequence    string            `json:"consequence"`
    Severity       Severity          `json:"severity"` // reuse review.Severity
    Paths          []string          `json:"paths,omitempty"`
    Signatures     []string          `json:"signatures"` // every key that attaches here
    Observations   []DebtObservation `json:"observations"`
    IntroducedIn   string            `json:"introduced_in,omitempty"` // task id or commit
    RepairBoundary string            `json:"repair_boundary,omitempty"`
    RepairTask     string            `json:"repair_task,omitempty"`
    RepairCommit   string            `json:"repair_commit,omitempty"`
}

Every counted field the priority model needs is derived, never stored:

recurrence            len(Observations)
blocked_tasks         distinct TaskID where Kind is block_reason
manual_interventions  count of Kind == manual_intervention
breadth               distinct components derived from Paths

A stored count invites drift from the log. A derived one cannot drift.

Two events carry it. DebtObserved appends one observation. DebtItemUpdated records class, status, severity or a merge. Both need adding to the allowed map and a validator, which is the work every existing event type already did.

4. Deduplication without corrupting provenance

A signature is computed from typed facts, never from prose.

operational   class + block_reason + harness + normalized component
correctness   class + failure_class + normalized component
structural    class + finding severity + normalized component

Exact signature match attaches automatically. That is the only automatic path.

Signatures are versioned, in the string itself.

v1:operational:lease_not_renewed:workpc-opencode:federation

Normalization rules will change. Without a version, changing them silently regroups every historical observation, and the recurrence counts that drive eligibility move underneath the items that already used them. A v2 signature never matches a v1 one, so old evidence keeps the grouping it was counted under.

A model may propose, never merge. Clustering emits DebtMergeSuggested carrying both item ids and its reasoning. The merge is an operator action or a policy threshold, recorded as DebtItemUpdated.

Merges are additive. The surviving item gains the other's signatures and observations. The absorbed item becomes withdrawn with a pointer, and its observations keep their original event ids. Nothing is rewritten, so a bad merge is reversible by reading the log.

Every observation names its event. A debt item's evidence is always checkable against the log that produced it. That rule is what stops a fuzzy proposal from becoming an unverifiable claim.

5. Eligibility policy

A pure function, mirroring CheckSubmission.

func CheckDebtEligibility(item DebtItem) DebtCheck // {Eligible bool, Reasons []string}

Class	Becomes eligible when
correctness	first confirmed observation, always
operational	recurrence >= 3 across >= 2 distinct tasks, or >= 1 manual intervention
structural	>= 3 review findings, or >= 2 tasks blocked or reworked in the same component
polish	never automatically, operator promotion only

Reasons lists what fired and what did not. "Not eligible" alone sends an operator reading code, which is the mistake SubmissionCheck already documents.

Eligible means a task may be created. It does not create one.

6. How maintenance and consolidation fit the existing lifecycle

A maintenance task is an ordinary task. Source debt, external id the debt item id, phases as usual.

research → plan → implement → verification → review → submission

Nothing in the lifecycle changes. One extension is needed: the task's brief must carry the debt item's evidence. That is the mechanism research and plan artifacts already use, a CAS ref on the task.

A consolidation task is the same thing with a research brief that asks:

• which temporary paths are still necessary?
• which fixes now duplicate each other?
• which compatibility branches are obsolete?
• which config or state is represented twice?
• which abstractions exist only because of defects that have since disappeared?
• what can now be deleted safely?

Its first output is a deletion plan, never an automatic refactor. Verification uses the project's existing policy. Review is the normal independent review.

The repair gets no discount. Classification as debt changes what gets scheduled, never what gets checked.

Success metrics for maintenance work

Lines of code are not a metric. Prefer evidence that can be checked:

• behaviour preserved
• tests preserved or strengthened
• branches removed
• obsolete types removed
• compatibility code removed
• duplicate config removed
• manual recovery paths eliminated

7. What must not be automated

• No autonomous cleanup agent, and no repo-wide sweep.
• No LLM score treated as authoritative. Counted facts decide, models propose.
• No automatic merge of debt items.
• No maintenance task from polish without an operator.
• No deletion without an independent review.
• No auto-closing an item because a commit touched the file. Closure needs a repair task or a stated run of clean evidence.
• No new classes invented at runtime.

8. Migration, so there is one track and not two

BURNIN.md holds 58 Fxx entries in the form | F52 | commit | prose |. AUDIT.md holds the older narrative.

One-time import, by hand, with a class assigned per row. Each becomes a DebtItem with Status: repaired, its commit as RepairCommit, and one observation citing the ledger.

Imported observations carry legacy provenance, never a fabricated event id. The Fxx history predates the capability that would have produced an event, and inventing one would break the provenance rule the ledger exists to enforce.

EventID   string `json:"event_id,omitempty"`
LegacyRef string `json:"legacy_ref,omitempty"` // "BURNIN.md:F18"

Exactly one is required. A reader can then tell a counted fact from an imported claim at a glance, and the counts that drive eligibility can exclude imported evidence if that turns out to matter.

Keep the namespace. New items continue at F62. Two numbering schemes would be the first structural debt the ledger itself creates.

After import, BURNIN.md stops being the item ledger and remains the run narrative. The defect table becomes generated output from the projection.

The history that tests the model

These are not special cases. They are the check on whether the model can represent the history this project already has.

History	Expected class	Why
F18, the single last_error slot	operational	Repeatedly destroyed causal evidence before it was fixed.
F43 to F46, the submission path	correctness	Apparently implemented, actually unreachable.
F61, planner learns policy by refusal	operational	Costs a round trip per plan, and becomes model compatibility on weaker planners.
Duplicated quality_gate config	structural	Only if it keeps causing drift or operator mistakes.
Old blocked burn-in tasks	neither	Hygiene, unless one exposes a runtime defect.
The blocked release loop, F57 to F60	correctness and operational	Wrong behaviour, and it required manual cleanup twice.

9. Smallest slice to live-prove first

A read-only projection over the existing log. No new events, no writes, no schema commitment.

internal/domain/debt.go            DebtItem, DebtObservation, signature, classification
internal/store/debt_projection.go  the fold over s.Events(0), and the gap report
internal/operations/debt.go        CheckDebtEligibility, and later the actions
GET /v1/debt                       read-only, tui surface

The projected type stays out of operations. Baking a read model into the command layer in the first slice is the mistake that would be hardest to undo later. operations owns actions: CheckDebtEligibility now, and SuggestDebtMerge, PromoteDebtItem and ScheduleDebtRepair when they exist.

The proof is what the projection can and cannot recover from canonical history. Section 2 already says worker observations are not durable and operator interventions are unrecorded, so demanding their reconstruction would be asking the projection to invent evidence.

The first burn-in is therefore three requirements, not one:

1. Recover every debt signal that canonical history actually encodes.
2. Report, explicitly and per kind, where known debt cannot be reconstructed.
3. Never infer a missing observation from BURNIN.md.

Incompleteness is part of the result, not a failure. The 409 loop lived in the F18 worker ring rather than in an event, so the ledger should say it has no durable evidence for that shape. That statement is what makes slice two necessary, measurably rather than by assertion.

What the projection should recover from the log alone:

• repeated lease_expired and retry_limit on one harness, which is the opencode failure shape across four tasks
• the retry-idleness dynamic, attached to the tasks that expired
• review findings grouped by component, if any repeat

A model that cannot represent debt already known is wrong, and no schema has been committed to yet. That is the cheapest place to find out.

Slice two makes worker observations durable, because that is the input the projection will most visibly lack.

Slice three adds DebtObserved and manual-intervention recording.

Scope boundary

This design changes no part of the task lifecycle, phases, leases, review, submission, federation or the plan machinery. The only extensions it needs are two event types, one projection, one pure eligibility function and one read-only endpoint.

---

Slice one, run against real history

Built and deployed as a757cff. GET /v1/debt folded 881 events from the live log, wrote nothing, and produced 15 candidate items and 3 gaps.

What it recovered

v1:operational:lease_expired:workpc-opencode:lease      r=41  tasks=4
v1:operational:lease_expired:workpc-claude:lease        r=29  tasks=13
v1:operational:lease_failure:-:lease                    r=20  tasks=16
v1:operational:system_error:-:lease                     r=11  tasks=7
v1:correctness:handoff_validation:-:lease               r=5   tasks=5
v1:correctness:plan_mismatch:-:...                      r=1   tasks=1
v1:structural:minor:-:scripts/orchestra_e2e_healthcheck.sh  r=1  tasks=1

The opencode failure shape is the top item, found mechanically. Run 14 diagnosed the same thing by hand from a pane capture. The retry-idleness dynamic is the second item, and it is now a number: 29 expiries across 13 tasks on one harness.

Seven items are eligible under the stated policy. Polish and the single structural finding correctly are not.

What it reported that it could not see

durable=false  manual_intervention  no event type records an operator repair
durable=false  worker_observation   worker health is not persisted
durable=true   deferred_finding     carried by the log, this history has none

The 409 release loop does not appear, and it should not. That evidence lived in the F18 worker ring, which no event carries. The ledger says so rather than inferring it, which is the result slice two exists to change.

Four defects the first run exposed

The component part is too coarse for lease evidence. Everything lease-related normalizes to lease, so lease_expired:workpc-claude is one bucket holding idle agents, rig interference and real failures. Recurrence 29 is true and the item is not a defect.

harness is often empty on block reasons. TaskBlocked payloads do not always carry harness_id, so lease_failure:- mixes harnesses that should be separate items.

Path normalization mangled a mismatch reference. scripts/orchestra_e2e_healthcheck.sh:12 became scripts/orchestra_e2e_healthcheck.sh_12, because the signature sanitizer replaces : and the mismatch evidence field holds prose, not clean paths.

Recurrence alone is the wrong sort. 41 occurrences on 4 tasks currently outranks 29 on 13 tasks. Breadth is in the design and not yet in the ordering, which is the priority function slice one deliberately omitted.

None of these required a schema commitment to discover. That was the point of making the first slice read-only.