kandev/docs/specs/task-delivery-ledger/spec.md

status, created, updated, revision, owner, decisions

status	created	updated	revision	owner	decisions
draft	2026-08-12	2026-08-13	5	nova28	../../decisions/0027-replayable-schema-migrations.md ../../decisions/2026-08-02-class-aware-git-subprocess-admission.md

Task delivery ledger

Why

A task that never opened a pull request is currently indistinguishable from a task that produced nothing. In the reference store that is the majority of the board: of 75 observed (task, repository) pairs, only 16 carry a merged pull or merge request. The remaining 59 are one undifferentiated bucket mixing research cards, chores, work delivered by committing straight to the default branch, and genuine failure.

Kandev already holds enough to split most of that bucket. It does not, and cannot today, answer the one question that would close it: did this card's work ever reach the repository's default branch? No merge-into-default detection exists anywhere. patRepository.DefaultBranch (apps/backend/internal/github/pat_client.go:1017) is parsed for clone metadata and, at :1160, copied onto pr.BaseDefaultBranch; neither use infers a merge. The push webhook — processPush in apps/backend/internal/github/webhook_service.go — publishes branch and SHA but is consumed only by the automation engine (apps/backend/internal/automation/github_webhook_subscriber.go, its GitHubPushReceived subscription), never for merge inference.

Separately, Kandev's own success metric is wrong in a way that lands in the same analysis. FinishRun writes status='finished' on six terminal call sites, four of which did no work, and agent_summary.go counts every finished row as a success. Only two of the six — the agent-completed subscribers — follow an agent actually running. The four scheduler guards record the reason that work did not run, as spelled out under Office run outcome.

This spec defines a delivery ledger that records how, and whether, each (task, repository) pair delivered; and a run outcome that stops Office from reporting non-work as success.

Citation convention

Every path:line in this document is a convenience pointer, not the contract. Where a line number is paired with a symbol name, a function name, or a semantic label, the label is authoritative and the line number is not. If the two disagree at build time, follow the label and correct the line. This matters most for the FinishRun call-site table under Office run outcome, where each site carries the outcome it must record: a drifted line number must never be allowed to mis-map an outcome.

Evidence the classification already works

Every number below was measured against the reference store (~/.kandev/data/kandev.db, snapshotted 2026-08-12) before any schema was proposed, as the card required. They are the input inventory, not estimates.

Observation	Value
task_session_git_snapshots rows	1,655
... with ahead > 0	1,390
... with empty head_commit	0
Sessions with ahead = 0 and one distinct head_commit (produced nothing)	31
Sessions with ahead > 0 and a moving head_commit (authored commits)	48
Sessions with ahead > 0 and a static head_commit (inherited a branch)	8
Sessions with ahead = 0 and a moving head_commit	0
Sessions working directly on their repository's default branch	1 (3 distinct heads, ahead 2)

Applying the precedence in Classification to that store, with no Kandev change, classifies 38 of 75 (task, repository) pairs:

Outcome	Pairs
pr_merge	16
direct_commit	1
no_delivery_observed	21
unknown	37

Three findings from that pass change the design and are therefore normative context, not commentary:

1. ahead is base-branch-relative, not upstream-relative (apps/backend/internal/agent/runtime/lifecycle/event_types.go, the Ahead field). It counts commits the branch has that its base does not, and it does not fall to zero when the branch is pushed. It is therefore a valid "this branch carries work" signal and an invalid "this session authored work" signal — the 8 sessions above with ahead > 0 and a static head inherited someone else's branch. This is why the ancestry precondition in Default-branch observation keys off a moving head_commit and not off ahead. Note the grain: every row in the table above counts sessions, not pairs. Head movement is only evidence of authorship within one session, so every predicate derived from this finding is evaluated per session and never by pooling a pair's sessions together — see Classification, "Head movement is a per-session fact".
2. Merge cannot be detected by commit ancestry in this repository. Kandev squash-merges by policy, so a merged branch head never becomes an ancestor of the default branch. Receipt: PR #2514's branch head 4dfa4d545 "fix(web): key mobile theme toggle off resolvedTheme" is present in the object store and is not an ancestor of origin/main; the commit that actually landed is the squash 15524de62 "fix(web): show dark mode toggle in mobile menu (#2514)". Ancestry is a valid positive signal and an invalid negative one.
3. Pull requests are not a GitHub-only concept here. Three provider tables exist — github_task_prs, gitlab_task_mrs, azure_devops_task_prs — and the reference store's GitLab table holds 4 merged merge requests on a repository with no GitHub provider at all. A GitHub-only reading of pr_merge undercounts by those 4. The three tables do not share a schema, which the Provider predicates table below resolves column by column: azure_devops_task_prs has no merged_at and no detached_at; gitlab_task_mrs has merged_at but no detached_at.

A fourth finding corrects the card's premise about the Office metric: only three of the FinishRun paths in scheduler_integration.go write an office_activity_log row — run_idle_skipped, run_budget_blocked and run_processed. The agent-inactive, task-tree-hold, checkout-error and checkout-unavailable paths log nothing, and the two event_subscribers.go completion paths log a run event rather than an activity row. The activity log therefore cannot carry this on its own.

What

• Kandev maintains a delivery ledger: at most one row per (task, repository), recording a delivery outcome, the evidence that produced it, and — separately — whether the pair's work was ever observed reaching the repository's default branch.
• The ledger is a new table. It is not a pull-request state and does not extend github_task_prs, gitlab_task_mrs, or azure_devops_task_prs.
• delivery_outcome takes exactly one of pr_merge | direct_commit | no_delivery_observed | unknown, or NULL when the pair has never been evaluated.
• Reaching the default branch is recorded as its own observation, because the route by which work reached the default branch is frequently unknowable while the fact that it arrived is not.
• An Office run records a structured outcome alongside its terminal status, so a budget-blocked, idle-skipped, agent-inactive, tree-held, checkout-blocked or never-launched run is no longer counted as a success.
• Every column added by this feature is nullable, legacy rows are NULL and never 0 or '', and the instant each mechanism became authoritative is published in the database so a point-in-time extract can tell "not observed" from "observed as nothing".

Delivery slices

This spec defines two contracts that share no build-order dependency. They are specified together because they are the same defect at two grains, and they are built in this order, each closing on its own:

• Slice A — Office run outcome. One nullable column, six call sites, one new field on models.Run, one reshaped repository query and the two dashboard response shapes it feeds. Depends on nothing in Slice B.

  models.Run is not optional. Ten production queries read SELECT * FROM runs and StructScan into office/models.Run (eight in internal/runs/repository/sqlite/runs.go, plus office/repository/sqlite/failure.go and run_routing.go), and no sqlx handle in this backend is Unsafe(). A column that exists in the table with no matching db: tag on the struct makes every one of those queries fail at runtime, which would take out the whole Office run pipeline. models.Run therefore gains Outcome *string with json:"outcome,omitempty" and db:"outcome", pointer-typed for the same reason the provider-routing columns on that struct are pointer-typed — so StructScan reads the NULL that every pre-activation row carries.

  Adding that field does not, by itself, change any response body. models.Run is never serialized to a client: every run surface flattens it through an explicit DTO with its own field list. No run-grain DTO gains a field in this card — specifically RunListItem (via runToListItem), AgentRunSummaryDTO (via buildRunSummaryDTO) and RunRuntimeDTO (via buildRuntimeDTO), all in office/dashboard/, are all unchanged. So no per-run response body changes and the "Any user-visible surface" exclusion in ## Out of scope stands as written.

  Two day-grain dashboard shapes DO gain fields, and that is in scope. AgentRunActivityDay gains skipped and unclassified, and AgentSuccessRateDay gains unclassified; the contract is specified under ## Office run outcome § Response shapes and summarized in ## API surface. All three are additive JSON fields that no frontend renders yet. The distinction is run-grain versus day-grain, not "nothing changes" — an earlier revision of this document said flatly "no DTO gains a field", which contradicted the Response shapes section and could have been read as licence to ship the reshaped query with no wire fields at all.

  Additive on the wire is not the same as unchanged on screen. Both shapes already feed rendered charts on the agent dashboard, and this card changes the values they carry: the Success Rate chart in particular reports 0% for every pre-activation day once succeeded narrows to outcome = 'processed'. No apps/web/ file changes and no new copy is introduced, so the E2E path allowlist is unaffected — but nobody should read "no DTO field is removed" as "no operator sees a difference". The new unclassified field is what makes that difference explainable in-band; see § Response shapes.

• Slice B — the delivery ledger. New table, evaluator, sweep, upsert guard, metrics, ancestry, two-dialect migrations.

Sequencing is a plan-level decision recorded here so it survives context resets; it changes no acceptance criterion. Both slices are in scope for this card.

Data model

task_delivery_ledger (new)

One row per (task_id, repository_id). Every column that carries evidence — the classification triple, the default-branch observation triple, observed_branch_commits and first_classified_at — is nullable, so "not observed" is always representable and is never spelled as 0 or ''. The columns that are NOT NULL are exactly: the identity columns (id, task_id, repository_id), the denormalized scope column workspace_id, the bookkeeping columns (last_evaluated_at, evaluation_seq, created_at, updated_at), and evidence_rank, whose non-nullability is a correctness requirement argued in its own row below. The table is authoritative; this sentence enumerates rather than generalizes, because an earlier revision said "all columns other than the identity, sequence and timestamp columns are nullable" and its own table contradicted it two rows later.

Column	Type	Meaning
id	TEXT PK	Row identity.
task_id	TEXT NOT NULL	FK to tasks(id) ON DELETE CASCADE.
repository_id	TEXT NOT NULL	FK to repositories(id) ON DELETE CASCADE. Never empty. The ON DELETE clause is stated rather than left to the implementation, for the same reason it is stated on task_id: repositories itself declares FOREIGN KEY (workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE and DELETE FROM workspaces is a live production path, so repository rows are removed in ordinary operation even though nothing hard-deletes them directly. A bare FK (dialect default NO ACTION) would make workspace deletion begin failing the moment any ledger row referenced one of that workspace's repositories, which is a regression this feature would introduce into an existing user-facing operation.
workspace_id	TEXT NOT NULL	Denormalized from the task, for extract scoping. Refreshed on every persisted evaluation — it is not write-once and not rank-guarded, because it is an identity attribute of the task rather than evidence about delivery. A task moved between workspaces is picked up because tasks.updated_at is a due source (see Sweep selection predicate).
delivery_outcome	TEXT NULL	pr_merge | direct_commit | no_delivery_observed | unknown. NULL means never evaluated.
delivery_basis	TEXT NULL	The evidence class that produced the outcome. See Basis vocabulary.
delivery_ref	TEXT NULL	The identifying evidence: a provider pull/merge request URL, or a commit SHA.
evidence_rank	INTEGER NOT NULL DEFAULT 0	The rank of the (outcome, basis) pair that produced this row. See Evidence rank. Persisted so the upsert guard needs no lookup table at write time. NOT NULL by design — the upsert guard compares this column in SQL, and x >= NULL is NULL (falsy) on both dialects, so a nullable rank would silently suppress the first real write. This table is new, so it has no legacy rows and the "legacy rows get NULL" rule does not apply to it; that rule governs columns added to existing tables, i.e. runs.outcome.
reached_default_at	TIMESTAMP NULL	When work for this pair was first observed reaching the repository's default branch. Write-once.
reached_default_basis	TEXT NULL	How that observation was made. See Basis vocabulary.
reached_default_ref	TEXT NULL	The commit SHA or pull/merge request URL that carried the observation.
observed_branch_commits	INTEGER NULL	Monotonic high-water mark of ahead. See Ordering, idempotency, concurrency.
first_classified_at	TIMESTAMP NULL	When a non-NULL delivery_outcome was first written. Write-once. Its instant is the one the evaluation began reading its inputs at, the same source as last_evaluated_at, and it is fixed here for the same comparability reason this document gives for reached_default_at: a timestamp column whose source varies between implementations cannot be compared across rows.
last_evaluated_at	TIMESTAMP NOT NULL	Advances on every persisted evaluation, including no-change evaluations. Its value is the instant the evaluation began reading its inputs, never the instant the upsert committed — see Sweep selection predicate, "Which instant last_evaluated_at records".
evaluation_seq	INTEGER NOT NULL	Monotonic per row; incremented on every persisted evaluation.
created_at	TIMESTAMP NOT NULL
updated_at	TIMESTAMP NOT NULL	Advances only when a classification or observation column changes.

UNIQUE(task_id, repository_id). Index on (workspace_id, last_evaluated_at) for the extract and the stall check.

reached_default_at is deliberately not derivable from delivery_outcome and does not participate in it. A pair may reach the default branch while its outcome stays unknown (see Classification, rule 3).

Basis vocabulary

delivery_basis:

Value	Meaning
provider_pr_merged	A non-detached provider pull/merge request for this pair reports merged.
default_branch_commit	The head commit advanced on snapshots whose branch is the repository's default branch.
reached_default_unattributed	Work reached the default branch, but by no route Kandev observed.
branch_commits_unmerged	Commits exist on a non-default branch and no delivery evidence was found.
no_commits_observed	Snapshots exist for this pair and every one shows no commits.
provider_pr_unmerged	No snapshot exists, and no provider pull/merge request row for this pair reports merged-and-not-detached. This is deliberately weaker than "every row reports not-merged": a row that merged and was later detached satisfies this basis, because rule 1 excludes detached rows from counting as delivery. The wording matches rule 5's predicate exactly, so a consumer must not read this basis as "no merged request ever existed" — it asserts that no attributable merged request exists now.
no_observations	Neither a snapshot nor a provider pull/merge request row exists.
default_branch_unknown	The repository's default_branch is empty, so default-branch rules could not be evaluated. Supersedes the matched rule's own basis; see Degraded evaluation.

reached_default_basis:

Value	Meaning
provider_pr_merged	Derived from a merged, non-detached provider pull/merge request whose base branch equals the repository's default_branch. Non-detached matters and is not inherited by implication: rule 1 excludes detached rows, so without the word here a detached row could offer an observation whose ref-selection set is empty.
default_branch_commit	The pair's session committed on the default branch itself.
ancestor_of_default	The pair's selected head commit is an ancestor of the default branch in the local checkout.
push_webhook_default	A verified push webhook reported this pair's head commit on the default branch ref. Defined for a later card; nothing writes it here (see Out of scope).

Evidence rank

The upsert guard and the monotonicity rule are both defined over a single integer derived from the (delivery_outcome, delivery_basis) pair. Rank is a property of the evidence, not of the outcome enum — that is what makes unknown with observed commits stronger than no_delivery_observed, which the outcome enum alone cannot express.

Rank	delivery_outcome	delivery_basis
0	NULL	NULL (never evaluated)
1	any	default_branch_unknown
2	unknown	no_observations
3	unknown	provider_pr_unmerged
4	no_delivery_observed	no_commits_observed
5	unknown	branch_commits_unmerged
6	unknown	reached_default_unattributed
7	direct_commit	default_branch_commit
8	pr_merge	provider_pr_merged

The rank is injective over ranks 2–8, and deliberately not over ranks 0 and 1. State this precisely, because an earlier revision of this document claimed injectivity over the whole ladder and that claim was false:

Rank	Injective?	Why
0	n/a	The never-evaluated sentinel. It is not a classification and no evaluation ever computes it.
1	No, by design	Every degraded evaluation lands here regardless of which rule matched, so rank 1 admits (pr_merge, default_branch_unknown), (unknown, default_branch_unknown) and (no_delivery_observed, default_branch_unknown). See Degraded evaluation.
2–8	Yes	Each maps to exactly one (outcome, basis) pair and each reachable non-degraded pair maps to exactly one rank.

Rank 1 is non-injective on purpose and the alternative was considered and rejected: giving each degraded (outcome, default_branch_unknown) pair its own rank would destroy the property that makes degraded rows safe — that a degraded row is the weakest evidence and is therefore superseded by any real evaluation once default_branch is populated. A degraded pr_merge at some higher rank would block a later, sighted unknown / no_observations at rank 2, which is exactly backwards: the degraded row was computed blind to the default branch and must never outrank a row that was not.

What injectivity over 2–8 buys is narrow and is the only thing that rests on it: at ranks 2–8, equal rank implies the same (outcome, basis), which is what makes the equal-rank rule under Monotonic evidence a no-op in outcome and basis. It does not imply the delivery_ref is unchanged — see that section. Rank 1 has its own equal-rank rule, stated under Degraded evaluation.

Do not add a value to ranks 2–8 without giving it its own rank.

The rank order is the order in which evidence accumulates in practice: a pair begins unobserved, may acquire an unmerged pull request, then snapshots showing nothing, then commits, then a default-branch observation, then a route. No transition in that sequence is a demotion, which is the property Monotonic evidence relies on.

runs.outcome (new column)

Nullable TEXT on the existing runs table: processed | budget_blocked | idle_skipped | agent_inactive | task_tree_held.

NULL for every row written before activation, for any run that never reaches a terminal status, and for every run that reaches status = 'failed' (see Office run outcome, the FailRun bullet). On the finished path the writer writes one of the five values above; it never writes ''. No database constraint is added — the reader is total over every possible value (see Office run outcome), so an unrecognised value degrades to skipped rather than breaking a query. runs.status semantics are unchanged: a blocked run still reaches finished, so every existing consumer of status keeps working.

Activation points

Each mechanism writes its activation instant into the existing kandev_meta key/value table, alongside the schema_initialized_at key already written by persistence.Provide:

• telemetry.delivery_ledger.activated_at
• telemetry.run_outcome.activated_at

Both are RFC3339 UTC and never overwritten on replay.

An activation instant is written only after its schema is verified present. This is the single most important rule in this section, because the migration runner (MigrateLogger.Apply) logs a failure at WARN and swallows it, so a migration that did not apply is invisible at boot. Writing the key "on first application" would therefore publish an activation instant for a table or column that does not exist — and a consumer reading that key would conclude the mechanism was live and treat every absent row as "observed as nothing", which is the exact inversion the activation point exists to prevent.

So each key is written only after a positive check, at the same boot, that its schema actually exists:

• telemetry.delivery_ledger.activated_at — only after a probe confirms task_delivery_ledger is present and queryable.
• telemetry.run_outcome.activated_at — only after a probe confirms runs.outcome is present.

If the probe fails the key is not written, nothing is logged as success, and the next boot retries both the migration and the probe. An absent activation key therefore means "this mechanism is not live", which is a true statement a consumer can act on; a present one means the schema was verified. The two are never ambiguous.

The activation key does not gate the writer. The sweep starts and runs on its normal cadence whether or not either key was written, and a failed probe never disables it. This is stated because the opposite is the tempting reading and it would be self-defeating: if a failed probe stopped the sweep, then a swallowed migration would produce no upsert attempts, so delivery_ledger_write_errors_total would stay at 0 and delivery_ledger.write_failed would never be logged — the migration-failure signals under Failure modes would all be silenced by the very condition they exist to detect. The key is a published fact for consumers, describing when the data became trustworthy. It is not a feature flag.

Reset parity. internal/system/database/reset.go drops every user table but deliberately preserves kandev_meta. Left alone, that would leave an activation instant pointing at a moment before data that no longer exists — inverting the guarantee the activation point exists to provide, because a post-reset task with no ledger row would read as "observed as nothing" rather than "not observed". The reset path therefore deletes both telemetry.*.activated_at keys along with the user tables it drops, so the next boot re-establishes an activation point that matches the data actually present. This is the only change this spec makes to the reset path.

Ordering is fixed, because the reset drops tables one at a time and is not transactional. The keys are deleted first, before any user table is dropped. The two orders are not equivalent under partial failure and only one of them fails safe:

• Keys first, then drops. If a drop then fails, the database holds ledger rows with no activation key. A consumer reads "this mechanism is not live" and treats the rows as untrusted — conservative, and recoverable on the next boot, which re-probes the schema and rewrites the key.
• Drops first, then keys. If the key deletion then fails, the database holds an activation instant pointing at data that no longer exists. A post-reset task with no ledger row reads as "observed as nothing" rather than "not observed" — the precise inversion this section exists to prevent, and one nothing later detects, because a present key is exactly the state a healthy system is in.

The asymmetry is the whole argument: a missing key is a true statement that costs a boot to correct, while a stale key is a false statement that survives indefinitely. If the key deletion itself fails, the reset fails and is reported as such rather than proceeding to drop tables.

Classification

For each candidate (task, repository) pair, rules are evaluated in this exact order and the first match wins.

What a predicate may read. Every predicate below reads the inputs observed on this evaluation, plus the default-branch observation this evaluation has just computed. No rule reads a stored classification column (delivery_outcome, delivery_basis, delivery_ref, evidence_rank, observed_branch_commits). Rule 3 is the only rule that reads an observation, and it reads the freshly computed one, never the stored reached_default_at. Evaluation order within a single evaluation is therefore fixed: the default-branch observation is computed first, then the rules are matched.

The consequence is deliberate and must not be treated as a defect: if a pair's ancestry check errors or is skipped on a later evaluation, that evaluation computes branch_commits_unmerged (rank 5) rather than reached_default_unattributed (rank 6). That is a demotion, so Monotonic evidence suppresses it, the stored row keeps rank 6, and delivery_ledger_demotions_suppressed_total increments. Reading the stored column instead would hide a real evidence regression behind an equal-rank no-op; counting it is the point.

Normalization applied before any rule runs:

• A head_commit that is NULL, empty, or whitespace-only is not a distinct head value and is ignored everywhere in this document, not merely in this section. It is never counted toward a distinct-head predicate, never selected as a ref, and never submitted to git. The scope is stated document-wide because two selection rules that consume head_commit — the ancestry head under Default-branch observation, "Which commit", and the direct_commit ref under Ordering — live in other sections and select by greatest created_at; scoped to this section alone, a newer empty head would outrank a real one and reach either git --is-ancestor or a write-once column. Both rules restate the filter locally so neither can be read in isolation and get it wrong.
• An ahead that is NULL or negative is read as 0.
• A repositories.default_branch that is NULL is read as the empty string, and an empty default_branch triggers Degraded evaluation. The column is TEXT DEFAULT '' and not NOT NULL, so both forms occur.
• A task_sessions.repository_id that is NULL is read as the empty string, and an empty value attributes the session to no pair (see Failure modes). That column is also TEXT DEFAULT '' and not NOT NULL.
• Branch comparison against repositories.default_branch is exact and case-sensitive, and never matches when default_branch is empty — an empty default_branch is not a branch name, and treating it as one would let a provider row or snapshot with an equally empty branch column compare equal. See Degraded evaluation.

Head movement is a per-session fact. "Two or more distinct non-empty head_commit values" is evaluated within a single session's snapshots, and a pair satisfies such a predicate when at least one of its sessions does. It is never computed by pooling every session's snapshots together. A task may have many sessions on one repository, and two sessions that each merely inherited a different branch would pool into two distinct heads and falsely read as authored work — the exact false positive the ancestry precondition exists to prevent. The Evidence table above was measured per session for the same reason.

1. pr_merge — a provider pull/merge request row exists for this pair, is not detached, and reports merged (see Provider predicates). Basis provider_pr_merged.
2. direct_commit — at least one of the pair's sessions has two or more distinct non-empty head_commit values among its own snapshots whose branch equals the repository's default_branch. Basis default_branch_commit.
3. unknown — commits were observed: the greatest ahead across the pair's snapshots is > 0, or at least one of the pair's sessions has two or more distinct non-empty head_commit values among its own snapshots.
   • Basis reached_default_unattributed when this evaluation's default-branch observation produced a result, by any basis, whether or not that result was the one persisted (a write-once column already set by an earlier evaluation is not re-written, but the observation still counts here).
   • Basis branch_commits_unmerged otherwise — including when the observation was skipped or errored on this evaluation, which is a suppressed demotion rather than a reclassification.
4. no_delivery_observed — at least one snapshot exists for this pair, every snapshot shows ahead = 0, and no session of the pair has two or more distinct non-empty head_commit values among its own snapshots. Basis no_commits_observed.
5. unknown — no snapshot exists for this pair, at least one provider pull/merge request row exists, and none of them reports merged-and-not-detached. Basis provider_pr_unmerged.
6. unknown — neither a snapshot nor a provider pull/merge request row exists. Basis no_observations.

Totality. The rules are exhaustive over every candidate pair, and this is checkable by inspection. Rules 2–4 cover every pair with at least one snapshot: rule 3's predicate and rule 4's predicate are exact complements of each other (some ahead > 0 or some session has ≥2 distinct heads of its own, versus all ahead = 0 and no session has ≥2 distinct heads of its own), and rule 2 is a strict subset of rule 3's domain taken first — a session with ≥2 distinct heads on the default branch has ≥2 distinct heads. Rules 5 and 6 cover every pair with no snapshot: provider rows exist, or they do not. Rule 1 crosses both and is taken first. No candidate pair can reach the end of the list unmatched, and no evaluation ever leaves delivery_outcome at NULL — NULL means only "no evaluation has been persisted for this row".

Rule 3 is the deliberate consequence of the outcome enum being fixed at four values. "Reached the default branch by an unobserved route" is real, and it is recorded in reached_default_at / reached_default_basis rather than being forced into pr_merge or direct_commit, both of which would assert a route that was not observed. delivery_basis carries the distinction the enum cannot.

Provider predicates

Each provider table is read through the predicates below. There is no shared schema, so each column is named per table.

Concept	github_task_prs	gitlab_task_mrs	azure_devops_task_prs
Merged	merged_at IS NOT NULL	merged_at IS NOT NULL	LOWER(TRIM(status)) IN ('completed','merged')
Detached	detached_at IS NOT NULL	never detached (no column; a GitLab detach deletes the row)	never detached (no column)
Merge instant	merged_at	merged_at	updated_at
Request number	pr_number	mr_iid	pull_request_id
URL (delivery_ref)	pr_url	mr_url	pull_request_url
Base branch	base_branch	base_branch	target_branch

Azure's merged vocabulary is taken from the terminal-status set this repository already uses in internal/azuredevops/watch_cleanup.go (completed, abandoned, closed, merged); completed and merged are the merged states and every other value — including an unrecognised one — is not-merged. An unrecognised status is not an error and is never guessed at: the pair simply fails rule 1 and falls through. Azure carries no merge timestamp at all, so updated_at is its merge instant; this is a sort key only and is never written to reached_default_at.

Candidate pairs

A pair is a candidate when all three hold:

1. its repository_id is non-empty and it appears in any of task_repositories, task_sessions.repository_id, or any provider pull/merge request table; and
2. that repository_id resolves to a row in repositories; and
3. its task_id resolves to a row in tasks.

A task with no repository produces no ledger row — absence means "not applicable" and is distinct from unknown.

Why condition 2 is not redundant. A non-empty repository_id is not a guaranteed foreign key anywhere it is read from: task_sessions.repository_id is TEXT DEFAULT '' with no FK to repositories, and the three provider tables declare their repository_id the same way (github_task_prs.repository_id is TEXT NOT NULL DEFAULT ''). A dangling non-empty value is therefore representable in the data, while task_delivery_ledger.repository_id is a real FK to repositories(id).

Without condition 2 such a pair is a candidate every sweep, every input read succeeds, the upsert fails the foreign key forever, no row is ever written, and — because "no ledger row" makes a pair unconditionally due — it is retried on every pass for the life of the database, consuming work and producing nothing.

So the pair is excluded from candidacy and counted, never attempted: delivery_ledger_pairs_missing_repository_total is set per pass to the number of such pairs. Counting is what keeps this consistent with "a pair is never silently skipped" — the exclusion is explicit, observable and bounded, rather than being an INNER JOIN that drops rows invisibly. A repository row that later appears makes the pair a candidate again with no special handling, because candidacy is recomputed every pass.

Why condition 3 exists, and why it is not implied by condition 2. The hazard is structurally identical and it is reachable through a different table, so guarding only the repository side leaves the same failure loop open on the task side. github_task_prs.task_id is TEXT NOT NULL with no FK to tasks, and no code path deletes github_task_prs rows when a task is hard-deleted — the GitHub task-deleted subscriber prunes PR watches and credentials only. (Azure DevOps does clean up, with a DELETE FROM azure_devops_task_prs WHERE task_id = ?; GitHub does not, and the divergence is why this cannot be reasoned about per provider.) Because the provider tables are a declared candidacy source in condition 1, an orphaned GitHub pull request row yields a candidate pair whose task row is gone, while task_delivery_ledger.task_id is a real FK to tasks(id).

Three separate things break if such a pair is admitted, and none of them is recoverable at build time from the rest of this document:

• Its upsert fails the tasks(id) foreign key on every pass, forever, exactly as in the repository case — and because every failed upsert increments delivery_ledger_write_errors_total, the counter this spec designates as the primary migration-failure signal would climb continuously on a completely healthy schema. That does not merely add noise; it destroys the one signal a /debug/vars reader is told to watch, by making its resting value non-zero for an unrelated reason.
• The sweep order under Ordering is tasks.created_at ascending, then tasks.id. A pair with no task row has neither value. An INNER JOIN would drop it silently, which contradicts "a pair is never silently skipped"; a LEFT JOIN would sort a NULL in a position neither dialect fixes.
• workspace_id is NOT NULL and is defined as denormalized from the task. With no task row there is no value to denormalize and no honest default.

So the pair is excluded from candidacy and counted, never attempted, on the same terms as condition 2: delivery_ledger_pairs_missing_task_total is set per pass to the number of candidate pairs rejected because their task_id matched no tasks row. It is a separate gauge from the repository one rather than a combined "unresolvable pairs" count, because the two have different causes and different owners — a missing repository points at repository lifecycle, a missing task points at provider-row cleanup — and a single number would tell an operator neither. A tasks row that later appears (or a provider row that is finally pruned) changes the count on the next pass with no special handling, because candidacy is recomputed every pass.

Note that both conditions are different from soft-deletion. A soft-deleted repository (repositories.deleted_at non-NULL) still has a row, so its pairs remain candidates and are governed by the freeze under Persistence guarantees; a missing row is not a candidate at all. The two must not be collapsed: one retains its ledger rows, the other never had any. An archived task likewise still has a row and is still evaluated (Persistence guarantees); only a hard-deleted task removes the row, and its ledger rows go with it by cascade.

Degraded evaluation

When repositories.default_branch is empty — or NULL, which normalizes to empty — every default-branch-dependent step is suspended: rule 2, the ancestry observation, and the provider_pr_merged default-branch observation. All three are suspended, not just the first two, because the branch comparison is exact: a provider row whose own base branch column is empty would compare equal to an empty default_branch and permanently set the write-once reached_default_* triple during an evaluation that is blind to what the default branch actually is. That is the one outcome degraded mode exists to prevent, and it is why Classification's normalization states that an empty default_branch never matches any branch.

Rule 1 itself still runs — whether a pull request merged does not depend on knowing the default branch — so a degraded pair can still be classified pr_merge. Only the observation derived from that row's base branch is suspended.

Classification still runs and still matches exactly one rule, but the result is degraded: delivery_basis records default_branch_unknown in place of the matched rule's own basis, and evidence_rank is 1 regardless of which rule matched. delivery_outcome is whatever the matched rule produced. delivery_ref is NULL, per Ordering.

Recording the degradation rather than the rule is deliberate: "this pair was classified blind to the default branch" is the fact a consumer must not miss, and rank 1 guarantees the degraded row is replaced by any later real evaluation once default_branch is populated.

Rank 1 admits more than one outcome, and that has consequences the builder must not have to derive. Because every degraded evaluation lands at rank 1 whatever rule matched, two successive degraded evaluations of the same pair can carry different outcomes at the same rank. Worked example, which is reachable and not hypothetical: a degraded pair with a merged pull request matches rule 1 and stores pr_merge / default_branch_unknown at rank 1; the pull request is later detached, so rule 1 no longer matches, every snapshot reports ahead = 0, rule 4 matches, and the pair re-evaluates to no_delivery_observed / default_branch_unknown — also rank 1.

The rules that govern that write are:

• The write happens. The classification columns are written at equal rank, so delivery_outcome becomes no_delivery_observed. A degraded row is a blind placeholder and must track its inputs; freezing it at the first outcome it ever saw would be worse.
• It is not a suppressed demotion and delivery_ledger_demotions_suppressed_total does not increment — the rank did not fall, and that counter means what it says.
• It is not silent: delivery_ledger_degraded_outcome_changed_total increments whenever an equal-rank write at rank 1 changes delivery_outcome, so a pair thrashing while blind is visible rather than being invisible in both counters.
• updated_at advances, because a classification column changed.

None of this applies at ranks 2–8, where the rank is injective and an equal-rank write cannot change the outcome. See Ordering, idempotency, concurrency, "Equal-rank writes".

Default-branch observation

reached_default_at may be set by any of the four bases in Basis vocabulary. It is write-once and monotonic: once set it is never cleared, moved, or overwritten by a later observation with a different basis.

Basis precedence within one evaluation. A single evaluation can satisfy more than one basis at once — a merged pull request whose base branch is the default branch, snapshots committing on the default branch, and a positive ancestry check are not mutually exclusive. Because the triple is write-once, whichever basis is chosen is permanent, so the choice is fixed here and is not the builder's:

Precedence	Basis	reached_default_ref written
1 (strongest)	provider_pr_merged	the URL column of the row selected by the default-branch observation ref rule below — not the pr_merge ref rule
2	default_branch_commit	the commit SHA selected by the direct_commit ref rule under Ordering
3	ancestor_of_default	the commit SHA submitted to the ancestry check, selected by Which commit below
4 (weakest)	push_webhook_default	defined for a later card; nothing writes it here

The evaluation computes every basis it can, then writes the highest-precedence one that produced a result. The order is by strength of attribution: a merged provider request names the route, a default-branch commit names the act, ancestry names only the fact of arrival.

The default-branch observation ref rule. This is a different row set from the pr_merge ref rule under Ordering, and conflating the two writes the wrong ref into a write-once column. The pr_merge ref rule selects among the pair's merged, non-detached provider rows with no base-branch filter, because rule 1 asks only whether a pull request merged. The observation asks a strictly narrower question — whether work reached the default branch — so it selects among the pair's merged, non-detached provider rows whose base branch equals the repository's default_branch, and then applies the same tiebreak keys in the same order (earliest merge instant, then request number ascending, then provider name ascending in the order azure_devops, github, gitlab, then that provider's scope column ascending).

The two rules therefore agree whenever every merged row targets the default branch, and diverge exactly when they should. Concretely: a pair with a merged pull request into a release branch and a later merged pull request into main selects the release-branch row for delivery_ref (it merged first, and rule 1 does not care where) and the main row for reached_default_ref. Selecting the release-branch URL for the observation would permanently record, in a write-once column, a pull request that never reached the default branch.

Because both rules resolve through named columns with total tiebreaks, repeated evaluations of unchanged inputs select the same ref, and no new tiebreak is introduced.

This precedence governs only which basis is offered to the write-once triple. Whether it is stored is decided by Monotonic evidence: if reached_default_at is already non-NULL, none of the three columns is written, regardless of precedence.

Its value is the UTC instant at which the observation was first made — the evaluation's own clock reading — not the snapshot's created_at, not the provider's merged_at, and not the commit's author or committer date. Only the observation instant is available for all four bases, and a column whose source silently varies by basis cannot be compared across rows.

The absence of reached_default_at never means "did not reach the default branch". Ancestry in particular produces false negatives for every squash-merged branch — see Evidence, finding 2.

Ancestry precondition. An ancestry check is attempted only when at least one of the pair's sessions shows two or more distinct non-empty head_commit values among its own snapshots — that is, only when some single session's head actually moved and that session therefore authored commits. The grain is per session, never pooled across the pair; see Classification, "Head movement is a per-session fact". Pooling would let two sessions that each inherited a different branch satisfy the precondition without either one authoring anything, which is the precise failure this precondition exists to prevent. This precondition is load-bearing, not defensive. A session that produced nothing reports its inherited base commit as its head, and that commit is already on the default branch's history, so an ungated --is-ancestor returns true and would permanently set a write-once column on a pair that delivered nothing. ahead cannot substitute for this test: per Evidence finding 1 it is base-relative, so an inherited branch reports ahead > 0 with a head that never moved.

When the precondition is not met the check is skipped, delivery_ledger_ancestry_skipped_total increments, and nothing is written.

Which commit. The head submitted to the check is selected from the snapshots of the session(s) that satisfied the moving-head precondition — that is, only sessions showing two or more distinct non-empty head_commit values among their own snapshots contribute candidate heads — and, within that set, only from snapshots whose head_commit is non-empty after the normalization in Classification. A NULL, empty or whitespace-only head is not a candidate for selection at all, and a snapshot carrying one is skipped over rather than winning on recency. Among that doubly filtered set, the head is the head_commit of the snapshot with the greatest created_at; ties are broken by the lexicographically greatest head_commit among those sharing that created_at.

The filter is restated here rather than inherited by implication because the ordering key is created_at and the empty value would otherwise win whenever it is newest: a session that recorded a final snapshot with no head would send an empty string to git merge-base --is-ancestor, whose result is meaningless and whose failure would be counted as an ancestry error rather than as the selection bug it is.

The session restriction is load-bearing, and an earlier revision of this document had it backwards. That revision said the selection was "across the pair's snapshots, not restricted to the session that satisfied the precondition", on the reasoning that the precondition decides whether to check while recency decides what to check. That reasoning established only that a non-empty head exists somewhere across the pair. It never established that pooling every session's snapshots is safe, and it is not.

The failure it admits is the precondition's own, one step later. A session that authored nothing reports its inherited base commit as its head, and that commit is already on the default branch's history. Give a pair one authoring session on an unmerged feature branch and one idle session sitting on the default branch, and the idle session's snapshot can carry the later created_at — so pair-wide recency selects the inherited head, git merge-base --is-ancestor returns true trivially (it never diverged, so it is already an ancestor), and the write-once reached_default_* triple is permanently set with a ref naming a commit the pair did not produce. Rule 3 then reads that observation and promotes the classification from branch_commits_unmerged to reached_default_unattributed for the life of the row.

That is precisely the false positive Ancestry precondition above exists to prevent. The precondition closes it at the gate, by refusing to check at all unless some session's head moved; restricting selection closes the same hole at selection, which the gate alone does not reach. Both are required, because the gate and the selector can otherwise resolve to different sessions.

The restricted set is still never empty when a check is attempted: the precondition requires some session to hold two or more distinct non-empty heads, and that session's snapshots are exactly what the restriction keeps.

Which checkout. The repository's local checkout is repositories.local_path, and it is never read from the column directly. The behaviour this card requires is exactly what resolveRepositoryLocalPath in internal/task/service/repository_discovery.go already implements: reject an empty repository ID, load the repository row, reject an empty local_path, resolve the stored path through the explicit local-repository path resolution, and reject a stored path that canonicalizes to a different location than the one saved. This card inherits those canonicalization and containment checks rather than restating them, because restating them is how they drift apart.

The seam, stated because that helper is not directly callable. resolveRepositoryLocalPath is an unexported method on the task service's Service type and depends on that service's repository-entity handle, so it cannot be invoked from the evaluator as written, and the evaluator does not belong inside the task service. The contract is therefore stated as a port, not as a function call:

• The evaluator depends on a narrow, read-only, single-method port — repository ID in, validated absolute checkout path or error out — and on nothing else from the task tier.
• That port is satisfied by the task service's existing resolution behaviour, exposed for this consumer. Whether it is exposed by exporting the method, by an adapter, or by a wrapper is an implementation choice, and the choice is free provided the validation performed is the existing one and is not reimplemented.
• The evaluator must not take a dependency on the concrete task service type, and must not duplicate the canonicalization or containment logic. Duplicating it is the one outcome this paragraph exists to prevent: the copy would silently omit the "saved path resolves elsewhere" rejection, which is the check that stops a moved or substituted checkout from being read.
• The port returns an error for every rejection above and never a sentinel empty path, so the caller has exactly one failure shape to handle.

A session worktree is never used: worktrees are per-session and transient, and the ancestry question is about the repository. When local_path is empty or the port returns an error — the ordinary case for a provider-cloned repository that has never been materialized locally — the check is an error under Failure modes, never a negative result.

Which default branch. Within that checkout the check resolves the default branch as refs/remotes/origin/<default_branch>, falling back to the local branch <default_branch> when the remote-tracking ref does not exist. If neither resolves, the check is an error under Failure modes — never a negative result.

Evaluation triggers and cadence

The periodic sweep is the sole guaranteed mechanism. Every pair is evaluated by the sweep, on the cadence below, and every acceptance criterion in this document is satisfied by the sweep alone. An implementation that ships only the sweep is complete against this spec.

Event triggers are permitted accelerators, not requirements. They reduce latency from up to one sweep interval to near-immediate; they add no outcome the sweep would not eventually reach, because evaluation is idempotent and the sweep predicate re-selects any pair whose inputs moved. Where a trigger is wired it must use an existing bus event:

Input that moved	Event available today
A task session reached a terminal state	events.TaskSessionStateChanged (task_session.state_changed)
A GitHub pull request row changed	events.GitHubTaskPRUpdated (github.task_pr.updated)
A GitLab merge request row changed	events.GitLabTaskMRUpdated (gitlab.task_mr.updated)

Two inputs have no event on the bus today: a git snapshot write, and an Azure DevOps pull request sync. They are named here so the absence is a recorded fact rather than a gap a builder discovers and improvises around — this card adds no new event type for them, and their latency is one sweep interval.

A trigger, where wired, runs the same evaluation as the sweep, asynchronously, and never inside the caller's transaction: a telemetry writer must not be able to fail or slow a session transition or a provider sync. A trigger that is dropped costs latency and nothing else.

Every evaluation reads all input sources for the pair. There is no partial evaluator: if any input query fails, the evaluation is abandoned under Failure modes rather than classifying from what it managed to read.

Sweep selection predicate

The freeze is evaluated first and overrides all three conditions. A pair whose repository has a non-NULL repositories.deleted_at is never due, whichever condition below would otherwise select it. This precedence is stated explicitly because two of the three conditions would otherwise contradict the freeze promised under Persistence guarantees: a soft-deleted repository's pair with no ledger row would be unconditionally due forever, and one with reached_default_at IS NULL would be selected by stale refresh every 24 hours. Restoring the repository (clearing deleted_at) moves repositories.updated_at, which is itself a due source, so a restored pair resumes evaluation on the next sweep without special handling.

A candidate pair is due when the freeze does not apply and any of the following three conditions holds:

• it has no ledger row — a pair with no row is unconditionally due, on every sweep, until one is written. This is what makes rule 6 reachable: a pair with no snapshot and no provider row has no input observation to compare against, and would otherwise never be selected. It also means the first sweeps after activation evaluate every pre-existing pair, once each, until each has a row. That is intended and is not the historical backfill excluded under Out of scope — see the reconciliation there; or
• its last_evaluated_at is older than its most recent input observation, defined as the greatest of the following, ignoring sources with no rows:

Source	Column
Git snapshots for the pair's sessions	MAX(task_session_git_snapshots.created_at)
Sessions for the pair	MAX(task_sessions.updated_at)
Task/repository membership	MAX(task_repositories.updated_at)
The task row itself	tasks.updated_at
The repository row itself	repositories.updated_at
GitHub pull requests	MAX(github_task_prs.updated_at)
GitLab merge requests	MAX(gitlab_task_mrs.updated_at)
Azure DevOps pull requests	MAX(azure_devops_task_prs.updated_at)

repositories.updated_at is in this table for a specific reason and must not be dropped as redundant with task_repositories.updated_at, which is a different table tracking task/repository membership. repositories is where default_branch and deleted_at live, so without this row: a Degraded evaluation row could never be promoted once default_branch was populated — contradicting the promotion this spec promises and the scenario that asserts it — and a soft-delete or restore would never re-evaluate the freeze described under Persistence guarantees.

tasks.updated_at is in this table so a task moved between workspaces re-evaluates and refreshes the denormalized workspace_id (see Data model). It re-selects pairs more often than the other sources do, which is accepted: evaluation is idempotent and its inputs are indexed reads, so a redundant evaluation costs a little work and changes nothing. The alternative — leaving workspace_id to drift — silently mis-scopes the extract that the column exists to serve.

Third condition:

• Stale refresh. A pair whose reached_default_at is NULL is due when last_evaluated_at < (sweep pass start instant − 24 hours), even when no input moved. The comparison is strict, and the right-hand side is computed once per pass from the pass's own start instant rather than per pair, so every pair in one pass is tested against the same boundary and a long pass cannot let a pair drift past it mid-sweep.

  This exists because the two conditions above are both driven by Kandev's own tables, and the central question this feature asks — did this work reach the default branch? — can be answered by evidence that never touches them. Two concrete cases, both ordinary: a branch that merges weeks after its task's last session ends moves no row in any table above, and a provider-cloned repository whose local checkout did not exist when ancestry was first attempted moves no row when it is later materialized. Under the first two conditions alone, neither pair is ever re-examined, and its reached_default_at stays NULL forever — which would defeat the card for exactly the finished-card population the ledger exists to classify.

  It is bounded on both sides. It applies only while reached_default_at is NULL, so a pair that has been observed reaching the default branch is never re-swept by this condition — the column is write-once, so there would be nothing to gain. And at 24 hours it is far longer than the 5-minute sweep interval, so it adds at most one evaluation per unresolved pair per day and cannot interfere with the "not selected again on the next sweep" behaviour asserted in Scenarios.

  This condition also subsumes ancestry retry, which is why no separate retry state is persisted: an ancestry check that errored left reached_default_at at NULL, so the pair is refreshed a day later and the check is attempted again. Failure modes relies on this — an ancestry error is explicitly not an abandonment, so last_evaluated_at advances and only this condition brings the pair back.

When the ledger itself cannot be read

All three due conditions read task_delivery_ledger: condition 1 asks whether a row exists, conditions 2 and 3 compare last_evaluated_at and test reached_default_at. So dueness cannot be computed at all when the ledger table is missing or unreadable — which is precisely the state a swallowed migration leaves behind. Left unstated, the natural implementation is a single query joining candidates to the ledger, that query errors, the pass selects nothing, no upsert is ever attempted, and delivery_ledger_write_errors_total stays at 0 — silencing the counter this document designates as the primary migration-failure signal, and making the missing-table scenario under Scenarios unreachable. That is the same defect as the withdrawn "the stall detector fires" claim, one signal over, so it is closed here rather than left to be discovered.

The contract is therefore a two-stage selection with a defined fallback:

1. Candidacy is computed without touching the ledger. The candidate set comes from task_repositories, task_sessions, the three provider tables, tasks and repositories — all of which are Candidate pairs inputs. This stage never reads task_delivery_ledger, so a missing ledger cannot suppress it.
2. Dueness is then computed by reading the ledger rows for those candidates. If that read succeeds, the three due conditions apply exactly as written. If it fails — the table does not exist, or the read errors for any other reason — the pass treats every candidate as due, which is the same answer condition 1 gives for a pair with no ledger row, and proceeds to evaluate and upsert each one.

The fallback is what makes the designated signal true: each of those upserts then fails and increments delivery_ledger_write_errors_total, and delivery_ledger.write_failed is logged once for the pass, exactly as Failure modes promises. The sweep additionally logs once per pass at WARN with the message delivery_ledger.dueness_unavailable, carrying the error and the candidate count, so the fallback is distinguishable from a genuine first-sweep-after-activation pass in which every pair really is new.

Three properties bound it, and none of them is optional:

• A failed dueness read is not an input-query failure. It does not abandon evaluations under Failure modes and does not increment delivery_ledger_evaluation_errors_total. The ledger is this feature's output, not one of the inputs a classification is computed from, and conflating the two would abandon every pair and re-silence the counter by a different route.
• The fallback is idempotent and self-limiting. When the read failure is transient and the table does exist, the pass performs one redundant round of evaluations whose upserts succeed; monotonic evidence and the high-water rules make each of those a no-op in value, so the only cost is work. The next pass reads dueness normally.
• The freeze and the candidacy conditions still apply. The fallback widens dueness only. A soft-deleted repository's pairs are still never due (see the freeze above), and a pair failing conditions 2 or 3 of Candidate pairs is still excluded and counted rather than attempted — so the fallback cannot turn an unresolvable pair into a write attempt.

Which instant last_evaluated_at records. The value written is the UTC instant at which the evaluation began reading its inputs. It is not the instant the upsert committed, and this is not a stylistic preference — the natural implementation is wrong and fails silently.

Take an evaluation that reads its inputs at T0, and suppose an input row for the same pair changes at T1 while the evaluation is still running, with the upsert committing at T2. Writing last_evaluated_at = T2 records that the pair was evaluated after the T1 change when in fact it was evaluated before it. The dueness test is last_evaluated_at < MAX(input.updated_at), so T1 < T2 means the pair is not due and the T1 change is masked permanently. Writing last_evaluated_at = T0 leaves T1 > T0, so the pair stays due and the next sweep sees the change.

This is a lost update, and the case where it bites is the ordinary one rather than a rare race: the last snapshot a finishing session writes is frequently the last input movement that pair will ever have, so a masked T1 leaves the pair pinned at whatever the evaluation computed one moment too early — for example no_delivery_observed on a pair whose final snapshot reported ahead > 0. Event triggers cannot rescue it, because they are explicitly optional accelerators and an implementation that ships only the sweep is complete against this spec.

The high-water rule under Monotonic evidence still applies on top of this: the stored last_evaluated_at never moves backwards, so a slow evaluation that began before a fast one cannot rewind the column.

The sweep evaluates every due pair in the order given under Ordering. It has no result cap: a pair is never silently skipped. If a sweep is interrupted, the next sweep resumes from the same ordering and re-evaluates whatever it did not reach; because evaluation is idempotent, partial completion is safe.

Boundary values, all fixed by this spec so they are not invented downstream:

Value	Setting
Sweep interval	5 minutes, completion-relative: the next pass starts 5 minutes after the previous pass finished, not 5 minutes after it started
First sweep	runs at boot, immediately after the schema probe under Activation points, with no initial delay
Concurrent sweep passes	never. A single sweep actor runs at most one pass at a time; a pass that overruns the interval delays the next one rather than overlapping it
Refresh interval (stale-refresh due condition)	24 hours
Ancestry call timeout	10 seconds per (task, repository)
Ancestry calls per evaluation	at most 1 per pair
Ancestry admission class	subproc.GitBackground
evaluation_seq initial value	1 on insert
Stall threshold for the data-side health signal	15 minutes, i.e. three missed sweeps
Sweep result cap	none

The three scheduling rows are fixed here rather than left to the implementation because each one changes observable behaviour. Completion-relative with no overlap is what makes the per-pass gauges (delivery_ledger_sessions_unattributed_total, delivery_ledger_pairs_missing_repository_total) well defined — "set at the end of every pass" has no single meaning if two passes can be in flight, and two overlapping passes would race on the same rows, making evaluation_seq advance twice for one round of inputs and letting the write-once reached_default_* triple be decided by scheduling. A fixed-rate timer would allow exactly that whenever a pass ran long. First sweep at boot matters because the alternative — waiting one interval — leaves a freshly migrated database with an empty ledger for five minutes while publishing an activation instant that says the mechanism is live.

A pair whose task still has running sessions is evaluated normally. Its outcome may be promoted by any later evaluation; there is no "wait until the task is finished" gate, because the rank order makes early classification safe.

API surface

No new HTTP route, WebSocket message, or MCP tool, and no new frontend state or user-visible copy. The ledger is a telemetry table read by the writer-health signals below and by the external extract described under Out of scope. Existing task, session, and pull-request responses are unchanged.

Slice A changes two existing day-grain dashboard response shapes additively: AgentRunActivityDay gains skipped and unclassified, and AgentSuccessRateDay gains unclassified. No field is removed or renamed, no run-grain DTO changes, and no new route is added. That contract is specified under Office run outcome § Response shapes. The values those shapes carry do change for pre-activation days, which is a behavioural change to an already-rendered chart even though no frontend file changes; the new unclassified field is what makes that change legible in-band.

Persistence guarantees

• The ledger survives backend restarts. last_evaluated_at in the table is the authoritative writer-liveness record; no in-process state is required to detect a stalled writer.
• reached_default_at and first_classified_at are write-once for the life of the row.
• Deleting a task deletes its ledger rows by cascade. Archiving a task does not: archived tasks continue to be evaluated.
• Soft-deleting a repository (repositories.deleted_at) freezes evaluation for its pairs. Existing rows are retained and last_evaluated_at stops advancing.
• Migrations follow ADR 0027: nullable ADD COLUMN then idempotent backfill, replay-safe on SQLite and Postgres, classified through db.IsDuplicateColumnError / db.IsAlreadyExistsError rather than a local string match.

Ordering, idempotency, concurrency

Ordering. A sweep evaluates due pairs ordered by tasks.created_at ascending, then tasks.id ascending, then repositories.id ascending.

Within a pair, evidence is selected deterministically without relying on a random identifier or a dialect-specific row number:

• pr_merge ref: among the pair's merged, non-detached provider rows, the one with the earliest merge instant (per Provider predicates: merged_at for GitHub and GitLab, updated_at for Azure DevOps); ties broken by request number ascending (pr_number / mr_iid / pull_request_id); further ties by provider name ascending in the order azure_devops, github, gitlab; and further ties by that provider's scope column ascending — azure_devops_task_prs.azure_repository_id, gitlab_task_mrs.project_path, and github_task_prs.owner then github_task_prs.repo. The ref written is that row's URL column.

  The scope column is not decoration, but it is load-bearing for two of the three providers, not all three, and the difference is stated exactly because the uniqueness keys are quoted here and a reader can check them:

  • gitlab_task_mrs is UNIQUE(task_id, repository_id, project_path, mr_iid) and azure_devops_task_prs is UNIQUE(task_id, repository_id, azure_repository_id, pull_request_id). Both keys include the scope column, so one pair can legitimately hold two rows from the same provider with the same request number and different URLs. For these two the scope tiebreak is what makes the selection deterministic, and dropping it would leave exactly the ambiguity this section exists to rule out.
  • github_task_prs is UNIQUE(task_id, repository_id, pr_number), which does not include owner or repo. That constraint already makes (pair, pr_number) unique for GitHub, so the collision the scope key resolves cannot occur there and the owner-then-repo tiebreak is redundant for GitHub. It is retained anyway so the ordering is total by the same construction for every provider, which keeps the rule checkable by inspection.

  No schema change is implied. The GitHub key is correct as it stands; the redundancy is in the tiebreak, not in the constraint. Do not "fix" the uniqueness key to match the other two — widening it would let a pair hold two GitHub rows with the same pr_number, which the current constraint deliberately prevents.

• direct_commit ref: restricted to the snapshots of the session(s) that satisfied rule 2's own predicate — sessions holding two or more distinct non-empty head_commit values, among their own snapshots, whose branch equals the repository's default_branch — and, within that set, among the pair's default-branch snapshots whose head_commit is non-empty after the normalization in Classification, those sharing the greatest created_at, and of those the lexicographically greatest head_commit. The non-empty filter is applied before the created_at comparison, not after, so a newer empty-headed snapshot cannot displace a real commit SHA and cannot be written into delivery_ref — or, through the default_branch_commit basis, into the write-once reached_default_ref. Rule 2 requires two or more distinct non-empty heads on the default branch for this basis to be reachable at all, so the restricted set is never empty here.

  Why the session restriction, stated because the same defect appears twice in this document. This is the direct_commit twin of the restriction argued at length under Default-branch observation, "Which commit", and it exists for the same reason. Rule 2 is earned per session, but an earlier revision selected the ref pair-wide, so a second session merely sitting on the default branch could supply a newer snapshot whose head is its inherited tip. That head would then be written as delivery_ref — and, because default_branch_commit is basis precedence 2, into the write-once reached_default_ref as well — permanently naming a commit that the session which actually earned the classification did not author. Restricting the candidate set to the session(s) that satisfied rule 2 is what keeps the ref attributable to the work that produced it.

• Every other rule writes delivery_ref as NULL. Rules 3, 4, 5 and 6 — branch_commits_unmerged, reached_default_unattributed, no_commits_observed, provider_pr_unmerged, no_observations — and any Degraded evaluation row identify no single artifact that carries the delivery, so there is nothing honest to name. In particular rule 5 does not write the unmerged pull request's URL: that row is evidence the pair did not deliver, and putting it in a column defined as "the identifying evidence" for a delivery would invite a consumer to read it as one. The head commit is likewise not written, because a branch head is not a delivery.

  This completes the ref rules over all six classification rules, which is what makes the equal-rank no-op claim under Monotonic evidence true for every rule rather than only for the two that name a ref.

• observed_branch_commits incoming value: the greatest ahead across the pair's snapshots after the NULL/negative normalization in Classification, which needs no tiebreak. When the pair has no snapshots at all the incoming value is NULL, not 0 — the greatest of an empty set is not zero, and 0 would assert "we looked and there were no commits" for a pair where nothing was ever observed, which is the exact NULL-versus-0 confusion this feature exists to prevent. Combined with the high-water rule, a NULL incoming value can never lower a stored one: a pair that had snapshots and then lost them keeps its high-water mark.

Idempotency. Evaluation is a pure function of the observed inputs. Re-running an evaluation whose inputs have not changed must leave delivery_outcome, delivery_basis, delivery_ref, evidence_rank, observed_branch_commits, reached_default_at, reached_default_basis, reached_default_ref and first_classified_at byte-identical and must not advance updated_at. Only last_evaluated_at and evaluation_seq advance.

Monotonic evidence. The classification columns move only up the Evidence rank ladder. Comparing the incoming rank to the stored rank gives exactly three cases, and every column's behaviour is fixed in all three:

	incoming rank > stored	incoming rank = stored	incoming rank < stored
delivery_outcome, delivery_basis, delivery_ref, evidence_rank	written	written	not written
first_classified_at	written if currently NULL	written if currently NULL	not written
observed_branch_commits	high-water (below)	high-water	high-water
reached_default_at / _basis / _ref	written only if reached_default_at is currently NULL, as one unit	same	same
last_evaluated_at	high-water (below)	high-water	high-water
evaluation_seq	stored + 1	stored + 1	stored + 1
workspace_id	written	written	written
delivery_ledger_demotions_suppressed_total	—	—	incremented
delivery_ledger_degraded_outcome_changed_total	—	incremented only at rank 1 when delivery_outcome changed	—

workspace_id is written unconditionally in all three columns of that table, including the demotion case. It is not evidence about delivery and the rank guard has no business gating it: a pair that moved workspace has moved workspace regardless of what its classification did.

Equal-rank writes, stated separately for ranks 2–8 and for rank 1. The two cases are genuinely different and collapsing them is what made an earlier revision of this section wrong.

At ranks 2–8. Equal rank implies the same (outcome, basis), because the rank is injective there (Evidence rank). So delivery_outcome and delivery_basis are always a no-op in value. delivery_ref is not guaranteed unchanged: the ref names the currently-selected evidence, and the evidence set can move while the rank does not — a pair already at rank 8 that acquires a second merged pull request with an earlier merge instant re-selects to that row's URL. That is intended, not a defect: the ref must name evidence that exists. When the ref changes, updated_at advances and delivery_ledger_rows_written_total increments; when nothing changed, neither does.

At rank 1. Equal rank does not imply the same outcome, because rank 1 is deliberately non-injective. The classification columns are still written, and the outcome therefore tracks the current inputs — which is the correct behaviour for a degraded row, since it is a blind placeholder and pinning it to a stale outcome would be worse than letting it move. But this write can change delivery_outcome without any demotion being recorded, so it is counted rather than left silent: an equal-rank write at rank 1 that changes delivery_outcome increments delivery_ledger_degraded_outcome_changed_total (see Writer health).

The concurrency consequence at rank 1 is stated honestly rather than papered over: two evaluators racing at rank 1 with different outcomes are last-writer-wins, so arrival order decides which outcome is stored. This is bounded and self-repairing — the next sweep recomputes from the same inputs and converges, and the whole row is superseded by any rank ≥ 2 evaluation once default_branch is populated. The "converge regardless of arrival order" guarantee below therefore holds for ranks 2–8 and is explicitly not claimed for rank 1.

High-water columns, stated as behaviour and not as a SQL function. observed_branch_commits and last_evaluated_at take the greater of the stored and incoming values, unconditionally, in all three rank cases, with a NULL stored value treated as lower than any non-NULL incoming value. observed_branch_commits therefore never decreases when a session — and with it, by ON DELETE CASCADE, its snapshots — is deleted. It is a stored high-water mark and not a recomputed aggregate; this is why rule 3's predicate reads the freshly observed ahead values rather than this column.

That behaviour is the contract. The obvious SQL spelling does not implement it, and the difference is silent, so it is called out rather than left to be discovered:

• SQLite's two-argument max(X, Y) returns NULL if either argument is NULL, so max(observed_branch_commits, excluded.observed_branch_commits) erases a real value the first time either side is NULL — the opposite of a high-water mark.
• PostgreSQL has no two-argument max at all; the equivalent is GREATEST, whose NULL handling differs again.

So the implementation must make the NULL handling explicit — coalescing to a floor before comparing, and using each dialect's own spelling — rather than relying on a bare MAX. This is the one place where Concurrency's "never by a read-then-write in application code" needs qualifying: the rule stays, and the NULL handling belongs inside the statement, not in a Go read-modify-write.

The same trap applies to the rank guard itself. x >= NULL evaluates to NULL on both dialects and a CASE on it takes the ELSE branch, so a nullable evidence_rank would silently suppress every write against a row that had one. That is why evidence_rank is declared NOT NULL DEFAULT 0 in the data model.

Both dialects are in scope for this statement. ADR 0027 governs the migrations, and the exemption recorded under Office run outcome covers only the pre-existing SQLite-only RunCountsByDayForAgent; new code added by this card is expected to run on SQLite and PostgreSQL alike.

A demotion is never written. If a pull request is detached after it merged, or a snapshot is deleted, the row keeps its stronger evidence and the suppression is counted. This is what makes the ledger safe: an evaluation that runs after the evidence has been removed can never erase what an evaluation that could see it recorded.

Concurrency. The ledger is written with a single INSERT ... ON CONFLICT (task_id, repository_id) DO UPDATE statement. Every rule in the table above is expressed inside that statement's SET clause — as CASE WHEN excluded.evidence_rank >= task_delivery_ledger.evidence_rank THEN ... END for the classification columns (sound precisely because evidence_rank is NOT NULL), CASE WHEN task_delivery_ledger.reached_default_at IS NULL THEN ... END for the write-once triple, and the explicitly NULL-handled, dialect-appropriate greatest-of expression described under Monotonic evidence for the high-water columns — never by a read-then-write in application code. Consequences, all of which are contract:

• Two evaluators racing on the same pair with different ranks — say one computing rank 1 and one rank 8 — converge on rank 8 regardless of arrival order, and neither can lose the other's write. This is the rank guard doing its job and it holds for every unequal pair of ranks.
• Two evaluators racing at equal rank 1 with different outcomes are the one exception and are not order-independent: rank 1 is deliberately non-injective, so the last writer's outcome is stored. This is bounded and self-repairing — see Degraded evaluation and "Equal-rank writes" above. It is called out here so the bullet above is not read as a guarantee it does not make.
• Two evaluators supplying a first default-branch observation concurrently: whichever statement commits first writes all three of reached_default_at, reached_default_basis and reached_default_ref; the second sees a non-NULL reached_default_at and writes none of them. The triple is therefore always internally consistent — it is never assembled from two different observations.
• evaluation_seq increments on every persisted evaluation, so a consumer can tell that the row was re-evaluated even when nothing changed.

Ancestry checks run through the existing class-aware git subprocess admission pool at class subproc.GitBackground — the sweep is background work and must not contend with user-facing git — with a bounded timeout, at most one per (task, repository) per evaluation.

Failure modes

• An input query fails — a snapshot, session, membership or provider read returns an error. The evaluation for that pair is abandoned: no column is written, not even last_evaluated_at, so the pair stays due and is retried on the next trigger or sweep. delivery_ledger_evaluation_errors_total increments. A classification is never persisted from a partially-read input set.

• The ledger upsert itself fails — the INSERT ... ON CONFLICT returns an error: the table does not exist because its migration was swallowed, a constraint is violated, or the write times out. This is a distinct failure from an input-query failure and must not be folded into it, because only this one indicates the ledger's own schema or storage is broken. No column is written, so the pair stays due and is retried on the next sweep. delivery_ledger_write_errors_total increments — this counter is the primary migration-failure signal and the one a /debug/vars reader should watch. The sweep logs once per pass at WARN with the message delivery_ledger.write_failed, carrying the error and the count of pairs that failed in that pass; once per pass rather than once per pair, so a missing table cannot emit one log line per candidate. A failing upsert does not abort the pass — the sweep continues to the next due pair, so one poisoned pair cannot stop the writer.

• Ancestry cannot be computed — the repository has no readable local checkout, neither default-branch ref resolves, the head commit object is absent, or the git call fails or times out. No evidence is produced: reached_default_at stays NULL and the outcome is unaffected. delivery_ledger_ancestry_errors_total increments. The error is never persisted as a negative result, and it does not abandon the evaluation — the rest of the classification still runs.

• The ancestry precondition is not met — fewer than two distinct non-empty head_commit values. The check is skipped, delivery_ledger_ancestry_skipped_total increments, and this is not an error.

• A negative ancestry result is not evidence. It must not set any column and must not influence the outcome. Squash-merge makes it a routine false negative.

• repositories.default_branch is empty — handled by Degraded evaluation: rules still run, delivery_basis is default_branch_unknown, evidence_rank is 1.

• A session has an empty or NULL repository_id — the column is TEXT DEFAULT '' and not NOT NULL, so both forms occur; both normalize to empty. The session contributes to no pair, is excluded from the stall comparand, and is counted in delivery_ledger_sessions_unattributed_total. Three such sessions exist in the reference store.

• head_commit is empty, whitespace-only, or NULL — it is not a distinct head value and is ignored.

• repositories.default_branch is NULL — the column is TEXT DEFAULT '' and not NOT NULL. It normalizes to empty and takes the Degraded evaluation path, the same as an empty string. There is no third behaviour.

• Azure DevOps has no merged_at — resolved by Provider predicates: merged is read from status, and updated_at is the merge instant used for ordering only. An unrecognised status is not-merged, so the pair falls through to a later rule rather than being guessed at.

• The same pull request is attached to more than one task — this occurs in the reference store (PR #2418, two tasks). Each task's pair is classified independently and both may read pr_merge. The ledger does not deduplicate credit across tasks.

• A migration fails — the migration runner logs at WARN and swallows the error (apps/backend/internal/db/migratelog.go, MigrateLogger.Apply), so a failed migration is invisible at boot. Three signals make it visible, and it is worth being exact about which one does the work, because an earlier revision of this document claimed "the stall detector fires" and that was false:

  • telemetry.delivery_ledger.activated_at is absent from kandev_meta, because the schema probe under Activation points found no table. This is the cheapest check and the one a consumer should make first.
  • delivery_ledger_write_errors_total climbs on every sweep pass and delivery_ledger.write_failed is logged, per the upsert-failure mode above. This is the signal that actually fires — and it fires only because of the dueness fallback under Sweep selection predicate, "When the ledger itself cannot be read". Without that fallback the missing table would break dueness computation first, the pass would select nothing, and this counter would stay at 0. The two statements are load-bearing for each other: do not implement one without the other, or this bullet becomes as false as the withdrawn stall-detector claim below.
  • delivery_ledger.dueness_unavailable is logged once for the pass, which is what distinguishes a broken ledger from a legitimate first sweep in which every candidate is genuinely new.
  • delivery_ledger_last_evaluated_unix publishes the unavailable sentinel -1, per Writer health.

  The stall detector specifically does not fire, and relying on it would have been the mistake: with the table missing there is nothing to take MAX(last_evaluated_at) over, and the empty-table rule would report delivery_ledger_stall_seconds = 0, which reads as healthy. That is why the stall signal is not the migration-failure signal and why the sentinel above exists.

Writer health

If this writer silently stops, nothing today would notice. Both signals below are required, because they fail in different ways.

In-process counters, following the subproc_* / routing_* precedent (apps/backend/internal/common/subproc/metrics.go), published at package init and exposed through the existing dev-mode /debug/vars handler:

Counter	Increments
delivery_ledger_evaluations_total	once per persisted evaluation, keyed by the delivery_outcome that evaluation computed. An abandoned evaluation persists nothing and is not counted here; it is counted only by delivery_ledger_evaluation_errors_total. A suppressed demotion is counted, keyed by the outcome the evaluation computed, not the one that stayed stored — otherwise a pair stuck in demotion looks idle.
delivery_ledger_rows_written_total	once per upsert that changed at least one classification or observation column, i.e. exactly when updated_at advances. Not once per evaluation: a re-evaluation with unchanged inputs advances only last_evaluated_at and evaluation_seq, and counting it would make the counter a duplicate of evaluations_total.
delivery_ledger_demotions_suppressed_total	once per upsert whose incoming rank was strictly lower than the stored rank.
delivery_ledger_evaluation_errors_total	once per abandoned evaluation (an input query failed).
delivery_ledger_ancestry_errors_total	once per ancestry check that was attempted and could not produce a result.
delivery_ledger_ancestry_skipped_total	once per evaluation where the ancestry precondition was not met.
delivery_ledger_write_errors_total	once per pair whose ledger upsert returned an error (see Failure modes). Kept separate from evaluation_errors_total because an input-query failure means the inputs are unreadable while this means the ledger's own schema or storage is broken — the migration-failure case. This is the counter that fires when a swallowed migration left the table missing.
delivery_ledger_degraded_outcome_changed_total	once per equal-rank write at rank 1 that changed delivery_outcome (see Degraded evaluation). Rank 1 is deliberately non-injective, so such a write is neither a promotion nor a suppressed demotion and would otherwise be invisible in every other counter here.
delivery_ledger_pairs_missing_repository_total	a gauge, not a running total, set per sweep pass for the same reason as sessions_unattributed_total: the count of candidate pairs the pass rejected because their repository_id matched no repositories row (see Candidate pairs).
delivery_ledger_pairs_missing_task_total	a gauge, not a running total, set per sweep pass: the count of candidate pairs the pass rejected because their task_id matched no tasks row (see Candidate pairs, condition 3). Kept separate from the repository gauge because the two have different causes — a missing repository points at repository lifecycle, a missing task at provider-row cleanup — and a combined number would identify neither. A non-zero resting value here is a data-hygiene fact about orphaned provider rows, not a ledger fault, and specifically not a migration failure.
delivery_ledger_sessions_unattributed_total	a gauge, not a running total. It is set — not incremented — at the end of every sweep pass to the count of distinct sessions with an empty repository_id that the pass encountered. It is the one value here whose natural reading is "how many are there", and incrementing per encounter would add the same three reference-store sessions on every 5-minute pass, turning a fact about the data into a number that only measures uptime. The _total suffix is retained for consistency with the subproc_* precedent.

Every counter is keyed and cadenced above so that two implementations produce the same numbers from the same inputs. A counter whose meaning is left to the writer is not a health signal.

The data-side stall signal. Counters reset to zero on restart, so a writer that stopped before the last restart looks healthy by counters alone. The stall signal is computed from the database instead, which is what makes it survive a restart:

• Actor and cadence: the sweep, at the end of every pass, including a pass that evaluated nothing.

• What it computes: MAX(task_delivery_ledger.last_evaluated_at) across the whole table, and as the comparand, MAX(task_sessions.updated_at) across only those sessions that could have produced work for the writer:

  Filter	Column	Why
  session attributes to a pair	task_sessions.repository_id non-empty after normalization	A session with no repository contributes to no pair, so it can never advance last_evaluated_at. Three such sessions exist in the reference store.
  repository still live	the joined repositories.deleted_at IS NULL	Pairs of a soft-deleted repository have last_evaluated_at frozen by design under Persistence guarantees.

  Each filter removes a session whose progress the writer is supposed to ignore. Without them the comparand advances on work the ledger is correctly not doing, and the signal reports a stall on a perfectly healthy writer — a false alarm, which is how a real one gets ignored.

  There is deliberately no archived filter, and the earlier "non-archived sessions" wording is withdrawn. It named no real column — task_sessions has no archived column in its CREATE TABLE or in any migration, and archival lives on tasks.archived_at — but more importantly it was wrong on the merits: Persistence guarantees states that archived tasks continue to be evaluated, so their sessions are work the writer really is expected to keep up with. Excluding them would have hidden a genuine stall on a board whose recent activity is mostly archived. The comparand covers every session the writer is responsible for, and nothing else.

• What it publishes: two expvar Ints alongside the counters, delivery_ledger_last_evaluated_unix and delivery_ledger_stall_seconds. Two independent queries feed them — the ledger query (MAX(task_delivery_ledger.last_evaluated_at)) and the comparand query (the filtered MAX(task_sessions.updated_at)) — and either can fail or return an empty result on its own. The table below is total over both, in that order of precedence; states that look identical without a sentinel are given distinct ones:

  State	..._last_evaluated_unix	..._stall_seconds	Meaning
  The ledger query errored (table missing or unreadable)	-1	-1	The ledger is unavailable. Distinct from healthy-and-empty, which is the whole point of the sentinel. Takes precedence over every row below: if the ledger cannot be read, the comparand's state is irrelevant.
  The ledger query succeeded and the table is empty	0	0	No pair has been evaluated yet. Not a stall: an empty table is not an infinite stall.
  Ledger rows exist and the comparand query errored	MAX(last_evaluated_at)	-1	The stall figure is unknown, not zero. The last-evaluated value is real and is still published, because it was read successfully; only the derived figure is unavailable.
  Ledger rows exist and the comparand set is empty (no session survives the filters)	MAX(last_evaluated_at)	0	Not a stall. There is no work the writer is responsible for keeping up with, so it cannot be behind. This is the ordinary state of a fresh database whose pairs come from task_repositories and whose sessions have not run yet.
  Ledger rows exist and the comparand is present	MAX(last_evaluated_at) as Unix seconds	comparand minus it, in seconds, clamped at 0	The real values.

  The comparand-empty and comparand-error rows are separated deliberately: an empty comparand is a true statement about the data and must read healthy, while a failed comparand read is an absence of information and must not be able to masquerade as healthy. Publishing 0 for both would let a repeatedly failing comparand query report a permanently healthy writer.

  When the ledger query errors the sweep logs once per pass at WARN with the message delivery_ledger.unavailable; when the comparand query errors it logs once per pass at WARN with delivery_ledger.comparand_unavailable. Without the -1 sentinels a missing table would publish 0/0, which is the healthy-and-empty state — a broken ledger would be indistinguishable from a fresh one, which is exactly the inversion this section exists to prevent.

  A consumer reading delivery_ledger_stall_seconds therefore treats -1 as "no measurement", never as a magnitude, and never compares it against the 15-minute threshold.

  Because all of these are recomputed from the database on every pass, the first sweep after a restart republishes the true values.

• What "fires" means: when delivery_ledger_stall_seconds exceeds the 15-minute threshold, the sweep logs once per pass at WARN with the message delivery_ledger.stalled, carrying both values as fields.

What these signals do NOT cover, stated as an accepted residual rather than left to be discovered. Every signal in this section is published by the sweep being monitored. A sweep goroutine that panics on its first pass, or is never started, publishes nothing at all — so the counters keep whatever value they last held (typically 0, which reads as healthy) and no WARN is ever emitted. This is the literal "the writer silently stops" case this section opens with, and no in-process signal can close it: a process cannot report its own death.

It is accepted rather than solved, for a specific reason that makes the residual small. The authoritative liveness record is task_delivery_ledger.last_evaluated_at, which lives in the database, not in the process. Any consumer — the external extract above all, which is the reason this table exists — can compute now() - MAX(last_evaluated_at) for itself without the sweep participating at all, and that computation is correct whether the sweep is running, wedged, or was never started. The in-process signals are a convenience for a live /debug/vars reader; the data-side record is the ground truth, and this spec's obligation is to keep it accurate. No acceptance criterion asserts the in-process signals detect a dead sweep, because they cannot.

Office run outcome

A second, delimited contract in the same card, because it is the run-grain form of the same defect: a terminal status is not an outcome.

Call sites. Every call site that finishes a run records the outcome that describes it. The semantic label in the right-hand column is authoritative; the line number is a pointer (see Citation convention).

Call site	Outcome
office/service/scheduler_integration.go:218 — agent not active	agent_inactive
office/service/scheduler_integration.go:247 — idle skip	idle_skipped
office/service/scheduler_integration.go:517 — task-tree hold	task_tree_held
office/service/scheduler_integration.go:829 — pre-execution budget block	budget_blocked
office/service/event_subscribers.go:408 — agent-completed for a task-bearing run	processed
office/service/event_subscribers.go:512 — handleTasklessAgentCompleted	processed

Checkout errors and checkout contention do not finish a run. A checkout error uses the normal retry and failure path. A contention result requeues the run and retries it. Neither path reports work that did not run.

Reachability of :512. handleTasklessAgentCompleted resolves its run through GetClaimedTasklessRunForAgent, which requires status = 'claimed' and an empty payload.task_id. Taskless runs fail before they can remain claimed, so the lookup normally returns sql.ErrNoRows and the site is a no-op. It is mapped to processed because an AgentCompleted event may still arrive for a legacy claimed run, and it is retained so the mapping is total over the call sites that exist.

:408 is the path where an agent actually ran to completion and is the ordinary source of processed. Leaving any terminal site unset would grow unclassified forever after activation and falsify the guarantee that the activation point tells a consumer when unclassified stops growing.

Concurrency, retry and error behaviour for this column. Slice A does not introduce a transaction or a guard, because it must not change runs.status semantics:

• outcome is written in the same UPDATE statement as status, so a run can never hold a terminal status with a stale outcome from a different transition.
• Where that statement actually lives, stated precisely, because the obvious answer is wrong. transitionRunTerminal (office/service/scheduler_runs.go:52) contains no UPDATE. It pre-fetches the run, calls s.repo.FinishRun(ctx, id, status), and publishes OfficeRunProcessed. The single UPDATE runs SET status = ?, finished_at = ? WHERE id = ? lives one layer down, in internal/runs/repository/sqlite, func (r *Repository) FinishRun(ctx context.Context, id, status string) error — which is the only implementation of that method in the repository. Per Citation convention the semantic label is authoritative: the statement to extend is the one inside the runs repository's FinishRun, not a statement inside transitionRunTerminal, which does not exist. This distinction is not pedantic, because the statement's real home has a caller the service layer does not.
• outcome becomes a parameter of both layers. The runs repository's FinishRun gains an outcome parameter alongside status and writes both in its one UPDATE; transitionRunTerminal gains the same parameter and forwards it. FinishRun (scheduler_runs.go:38) takes the value from the call-site table above and FailRun (:44) passes NULL. NULL is correct rather than a placeholder — a run that reached status = 'failed' is bucketed by RunCountsByDayForAgent on its status alone and never reaches the succeeded / skipped / unclassified buckets, so no value from the five-value vocabulary would ever be read, and inventing one would assert a classification nothing consumes. This also makes the sentence under ### runs.outcome exact: the five-value claim describes the finished path; the failed path writes NULL in the same statement.
• The second caller pair of the shared repository method, and what it passes. Changing that signature necessarily reaches office/scheduler.SchedulerService.FinishRun and .FailRun (internal/office/scheduler/run_processing.go), which call the same repo.FinishRun without going through transitionRunTerminal or the six-site table. Both pass NULL, and neither is added to the call-site table. The reasoning, so a builder does not have to guess and does not "improve" it into a vocabulary value:
  • SchedulerService.FailRun writes RunStatusFailed. It is reached in production (via that package's own retry path), and NULL is the same value FailRun passes at the service layer, for the same reason — a failed run is bucketed on status alone.
  • SchedulerService.FinishRun writes RunStatusFinished and has no production caller at the time of writing. It is a dormant parallel copy of the service-layer method. It passes NULL because there is no outcome to describe: no call site means no semantic label, and inventing processed for it would be the exact defect this slice exists to remove — a run in which nothing is known to have happened counted as a success. NULL routes it to unclassified, which is the honest bucket for a path whose meaning is unestablished.
  • Consequently the activation guarantee below is scoped to the six sites and is not weakened by these two: neither is a terminal site this card classifies, and if SchedulerService.FinishRun is ever wired to something real, the card that wires it owns choosing its outcome and adding it to the table. Deleting the dormant method is not in scope here (see ## Out of scope).
• That statement is an unconditional UPDATE runs SET status = ?, outcome = ?, finished_at = ? WHERE id = ? with no status guard, matching today's behaviour. If two terminal callers ever reach the same row, last writer wins for status and outcome together. This is the existing contract for status, extended unchanged.
• A zero-row update (the run was deleted) is not an error and is not retried.
• Four of the six sites discard FinishRun's error (_ = si.svc.FinishRun(...)). That is unchanged by this card. A discarded failure leaves the row non-terminal with outcome NULL; if it later reaches finished by another path it is bucketed by whatever that path wrote, and if it never does it is not finished and so never reaches the succeeded / skipped / unclassified buckets at all.
• Consequently the activation guarantee is stated precisely: after activation, unclassified stops growing for runs that reach finished through one of the six sites above. It is not a claim that no finished row can ever carry a NULL outcome, because this card does not add error handling to paths that discard errors today.

runs.status is unchanged. Nothing that reads status today changes behaviour.

Repository query. RunCountsByDayForAgent (office/repository/sqlite/agent_summary.go) reports five buckets where it reports three today. The bucketing is total over every possible column value:

Bucket	Predicate
succeeded	status = 'finished' and outcome = 'processed'
skipped	status = 'finished' and outcome is any other non-NULL value
unclassified	status = 'finished' and outcome IS NULL
failed	status IN ('failed','timed_out') (unchanged)
other	every remaining status (unchanged)

Response shapes. Two shapes in office/dashboard/agent_summary.go derive from those rows, and both change additively:

• AgentRunActivityDay (built by padAgentRunActivity) gains skipped and unclassified JSON fields. Its documented invariant becomes total = succeeded + skipped + unclassified + failed + other, so total is unchanged in value for any given day.

• AgentSuccessRateDay (built by buildSuccessRate) gains one JSON field, unclassified. succeeded now counts processed runs only, while total remains the same full denominator, so the success rate falls to the truth rather than being inflated by non-work.

  Why it gains a field rather than keeping its two. Without one, this shape changes meaning mid-series with no in-band marker, which is the exact discontinuity the NULL-not-0 rule in ## What exists to prevent — and it is worse here than elsewhere, because the consequence is not a subtle miscount. succeeded is today status = 'finished' and becomes status = 'finished' AND outcome = 'processed', while every run finished before activation carries outcome IS NULL. So every pre-activation day reports succeeded = 0 against an unchanged denominator — the Success Rate chart reads 0% across all of history the moment this ships. That is not wrong data (those runs genuinely have no recorded outcome), but presented as two fields it is indistinguishable from a real collapse in agent success, and a reader has no way to tell without going outside the response to kandev_meta.

  With unclassified present the discontinuity is legible in the response itself: a day where unclassified accounts for the whole non-failed, non-other remainder is a pre-activation day, and a day where it is 0 is fully classified. This is the same reasoning, and the same additive treatment, already applied to AgentRunActivityDay; the earlier revision that left this shape at two fields was inconsistent with its own principle rather than deliberately excepting it.

  succeeded + unclassified is deliberately not offered as a compatibility value and no consumer should compute it: it would resurrect exactly the finished-as-success count this slice removes, because unclassified contains pre-activation budget-blocked and idle-skipped runs alongside genuine work.

The Succeeded field in office/repository/sqlite/dashboard.go is sourced from task_sessions.state, not from runs.status, and is not changed by this spec.

No new user-visible copy is introduced: the existing charts keep rendering the fields they already render, and the two new fields are additive on the wire. Consequently no t() string, no locale catalog entry, and no Playwright spec is added by this card. A later card that surfaces skipped or unclassified in the UI owns that copy and that coverage.

RunCountsByDayForAgent is pre-existing SQLite-only code (it uses strftime). This spec does not make it dialect-portable; the Postgres parity requirement under Migration and activation binds the migrations, which is what ADR 0027 governs.

Legacy rows land in unclassified, not succeeded. They are not reinterpreted and not backfilled: the pre-activation series keeps its own bucket, so the discontinuity is visible in the data rather than silent. The activation point tells a consumer when unclassified should stop growing.

"Visible in the data" is meant literally and is satisfied at both grains, which is why AgentSuccessRateDay gains unclassified above. A consumer reading either response shape can separate "this day had no successes" from "this day predates the mechanism" without consulting kandev_meta — the activation instant remains the authoritative answer for when the change happened, but no shape requires it to avoid a false reading.

Scenarios

Classification

• GIVEN a task whose repository has a non-detached merged pull request, WHEN the ledger is evaluated, THEN the pair records delivery_outcome = pr_merge, delivery_basis = provider_pr_merged, delivery_ref set to that pull request's URL, and evidence_rank = 8.
• GIVEN a task whose repository is tracked on GitLab and whose merge request has a non-NULL merged_at, WHEN the ledger is evaluated, THEN the pair records pr_merge on the same basis as a GitHub pull request.
• GIVEN a task whose only Azure DevOps pull request has status = 'Completed', WHEN the ledger is evaluated, THEN the pair records pr_merge — the status match is case-insensitive and whitespace-trimmed.
• GIVEN a task whose only Azure DevOps pull request has status = 'abandoned', and no snapshots, WHEN the ledger is evaluated, THEN the pair records unknown with delivery_basis = provider_pr_unmerged and evidence_rank = 3.
• GIVEN a task whose only Azure DevOps pull request has an unrecognised status, and no snapshots, WHEN the ledger is evaluated, THEN the pair records unknown with provider_pr_unmerged — the status is not guessed at and the evaluation does not error.
• GIVEN a task whose only session ran on a branch equal to the repository's default_branch and whose snapshots carry three distinct head commits, WHEN the ledger is evaluated, THEN the pair records delivery_outcome = direct_commit, delivery_basis = default_branch_commit, and reached_default_at set.
• GIVEN a task with snapshots showing ahead = 12 on a feature branch, no provider pull request, and no default-branch observation, WHEN the ledger is evaluated, THEN the pair records delivery_outcome = unknown with delivery_basis = branch_commits_unmerged, observed_branch_commits = 12 and evidence_rank = 5.
• GIVEN that same task, WHEN a later evaluation observes its head commit as an ancestor of the default branch, THEN reached_default_at and reached_default_basis = ancestor_of_default are set and delivery_basis becomes reached_default_unattributed, while delivery_outcome remains unknown.
• GIVEN a task whose every snapshot shows ahead = 0 and one distinct head commit, WHEN the ledger is evaluated, THEN the pair records no_delivery_observed with basis no_commits_observed and evidence_rank = 4.
• GIVEN a task whose only snapshot shows ahead = 0 and an empty head_commit, WHEN the ledger is evaluated, THEN the pair records no_delivery_observed — zero distinct non-empty heads satisfies rule 4's "at most one", so no pair falls through the rule set.
• GIVEN a task whose snapshots carry ahead = NULL and ahead = -1, WHEN the ledger is evaluated, THEN both are read as 0 and the pair is classified as if every snapshot reported ahead = 0.
• GIVEN a task with a declared repository but no snapshot and no provider pull request, WHEN the ledger is evaluated, THEN the pair records unknown with basis no_observations — not no_delivery_observed.
• GIVEN a task with no repository at all, WHEN the ledger is evaluated, THEN no ledger row is written for it.
• GIVEN a repository whose default_branch is empty and a task with snapshots showing ahead = 12, WHEN the ledger is evaluated, THEN the pair records delivery_outcome = unknown, delivery_basis = default_branch_unknown and evidence_rank = 1 — the rule's own basis is superseded — and WHEN default_branch is later populated and the pair is re-evaluated, THEN it is promoted to branch_commits_unmerged at rank 5.
• GIVEN that same degraded pair, WHEN repositories.default_branch is populated and nothing else changes, THEN the next sweep selects the pair as due — because repositories.updated_at advanced and is one of the named due sources — so the promotion above is reachable without any other input moving.
• GIVEN a repository whose default_branch is empty and a merged pull request whose base_branch is also empty, WHEN the pair is evaluated, THEN reached_default_at stays NULL — an empty default_branch matches no branch, so the provider-derived observation is suspended along with rule 2 and ancestry.
• GIVEN a repository whose default_branch is NULL rather than empty, WHEN the pair is evaluated, THEN it takes the same degraded path as an empty string, with delivery_basis = default_branch_unknown and evidence_rank = 1.
• GIVEN a task with two sessions on one repository, each on its own inherited branch, each reporting a single distinct head_commit that differs between the sessions, WHEN the pair is evaluated, THEN no session has two or more distinct heads of its own, so the pair is not classified direct_commit, no ancestry check is attempted, and reached_default_at stays NULL — distinct heads are never pooled across sessions.
• GIVEN a pair classified by rule 3, 4, 5 or 6, or degraded by Degraded evaluation, WHEN the row is written, THEN delivery_ref is NULL — including for provider_pr_unmerged, whose provider row URL is evidence of non-delivery and is deliberately not recorded as a delivery ref.

Evidence rank and reclassification

• GIVEN a pair whose first snapshot shows ahead = 0 with one head commit, classified no_delivery_observed at rank 4, WHEN a later snapshot shows ahead = 12 and the pair is re-evaluated, THEN the row is promoted to unknown / branch_commits_unmerged at rank 5, delivery_ledger_demotions_suppressed_total does not increment, and observed_branch_commits reads 12. Mid-session evaluation must not pin a working pair at no_delivery_observed.
• GIVEN a pair classified unknown / provider_pr_unmerged at rank 3, WHEN its pull request merges and the pair is re-evaluated, THEN the row reads pr_merge at rank 8.
• GIVEN a repository whose default_branch is empty and a pair with a merged pull request, stored degraded as pr_merge / default_branch_unknown at rank 1, WHEN the pull request is detached, every snapshot reports ahead = 0, and the pair is re-evaluated while default_branch is still empty, THEN the row reads no_delivery_observed / default_branch_unknown still at rank 1 — the equal-rank write happens — AND delivery_ledger_degraded_outcome_changed_total increments AND delivery_ledger_demotions_suppressed_total does not increment AND updated_at advances. Rank 1 admits more than one outcome, so this is neither a promotion nor a suppressed demotion, and it must not be silent in both counters.
• GIVEN that same degraded pair, WHEN default_branch is later populated and the pair is re-evaluated, THEN it is promoted to a rank ≥ 2 classification — a degraded row at rank 1 is superseded by any sighted evaluation, whichever outcome it currently holds.
• GIVEN a pair stored pr_merge / provider_pr_merged at rank 8 whose delivery_ref names pull request A, WHEN a second merged, non-detached pull request B with an earlier merge instant is synced and the pair is re-evaluated, THEN the rank is still 8 and delivery_outcome and delivery_basis are unchanged, but delivery_ref becomes B's URL, updated_at advances and delivery_ledger_rows_written_total increments — equal rank guarantees the same (outcome, basis), never the same ref.
• GIVEN a pair whose delivery_outcome is unknown and whose workspace_id is W1, WHEN its task is moved to workspace W2 and the pair is re-evaluated, THEN the ledger row's workspace_id reads W2 — it is refreshed on every persisted evaluation and is not gated by the rank guard — AND the pair was selected as due because tasks.updated_at advanced.

Squash-merge, ancestry preconditions and negative evidence

• GIVEN a merged pull request whose branch head is not an ancestor of the default branch because the merge was squashed, WHEN ancestry is evaluated, THEN the negative result is discarded, no column records false, and the pair's pr_merge classification from rule 1 is unaffected.
• GIVEN a pair whose snapshots all report the same single head_commit — the inherited base commit, which is trivially an ancestor of the default branch — WHEN the pair is evaluated, THEN no ancestry check is attempted, delivery_ledger_ancestry_skipped_total increments, and reached_default_at remains NULL.
• GIVEN a pair reporting ahead = 4 on an inherited branch whose head_commit never moved across its snapshots, WHEN the pair is evaluated, THEN the ancestry precondition is still not met and no ancestry check is attempted — ahead > 0 does not satisfy it.
• GIVEN a pair one of whose sessions carries two distinct head commits among its own snapshots, and whose most recent two snapshots share the greatest created_at, WHEN the ancestry head is selected, THEN it is the lexicographically greatest head_commit of those two, and repeated evaluations select the same one. The session grain is stated in the GIVEN because selection is restricted to the precondition-satisfying session(s); two heads split across two sessions would satisfy no session's precondition and no check would be attempted at all.
• GIVEN a pair whose session holds two distinct non-empty head commits and whose newest snapshot by created_at carries a whitespace-only head_commit, WHEN the ancestry head is selected, THEN the whitespace-only snapshot is skipped and the newest non-empty head is submitted to the check — an empty value is never sent to git and never counted as an ancestry error.
• GIVEN a pair classified direct_commit whose newest default-branch snapshot carries an empty head_commit, WHEN delivery_ref is selected, THEN it is the newest non-empty head_commit among the default-branch snapshots of the session(s) that satisfied rule 2, and the same value is offered as reached_default_ref — no empty string reaches either column.
• GIVEN a pair with two sessions on one repository — session A, on a feature branch, holding two distinct non-empty head commits of its own and therefore satisfying the moving-head precondition, and session B, which merely sat on the repository's default_branch and wrote a single snapshot carrying its inherited head, with a later created_at than any of session A's — WHEN the ancestry head is selected, THEN it is session A's newest non-empty head and not session B's inherited head, even though B's snapshot is the newest on the pair. Selection is restricted to the precondition-satisfying session(s), so a non-authoring session can never supply the commit submitted to git merge-base --is-ancestor.
• GIVEN that same pair, WHEN the evaluation completes, THEN reached_default_at is not set from session B's inherited head — an inherited head is trivially an ancestor of the default branch, so pair-wide selection would have set the write-once triple with reached_default_basis = ancestor_of_default on a pair whose only authored work is unmerged, and promoted rule 3's basis to reached_default_unattributed. This is the same false positive the Ancestry precondition prevents at the gate, and it is prevented here at selection.
• GIVEN a pair with two sessions on one repository — session C, which committed on the repository's default_branch and holds two distinct non-empty heads there, and session D, which sat on the same default_branch holding a single inherited head whose snapshot has a later created_at — WHEN delivery_ref is selected for the resulting direct_commit classification, THEN it is session C's newest non-empty head, and the same value is offered as reached_default_ref. Only the session(s) satisfying rule 2's own predicate contribute candidate heads, so session D's inherited head reaches neither column.
• GIVEN a repository whose local checkout is missing, WHEN ancestry is evaluated, THEN delivery_ledger_ancestry_errors_total increments, reached_default_at stays NULL, delivery_outcome is unchanged, and the rest of the classification is still persisted.
• GIVEN a repository whose refs/remotes/origin/<default_branch> does not exist but whose local branch <default_branch> does, WHEN ancestry is evaluated, THEN the local branch is used and the check proceeds.
• GIVEN a provider-cloned repository whose local_path is empty, WHEN ancestry is evaluated, THEN the checkout-resolution port returns an error rather than a path, delivery_ledger_ancestry_errors_total increments, reached_default_at stays NULL, and the rest of the classification is still persisted.
• GIVEN a repository whose stored local_path canonicalizes to a different location than the one saved, WHEN ancestry is evaluated, THEN the port returns an error and no git command is run against the resolved location — the evaluator inherits that rejection instead of implementing its own path check.
• GIVEN a pair with a merged pull request whose base branch is the default branch, snapshots committing on the default branch, and a head commit that is an ancestor of the default branch — all three observable in one evaluation — WHEN reached_default_at is first written, THEN reached_default_basis is provider_pr_merged and reached_default_ref is that pull request's URL, because provider merge outranks both other bases; and repeated evaluations of the same inputs select the same basis and ref.
• GIVEN a pair whose only default-branch evidence is a positive ancestry check, WHEN reached_default_at is written, THEN reached_default_basis is ancestor_of_default and reached_default_ref is the commit submitted to the check.
• GIVEN a repository whose default_branch is main, and a pair with two merged, non-detached pull requests — request A into release/1.2 with the earlier merge instant, and request B into main — WHEN the pair is evaluated, THEN delivery_ref is A's URL (the pr_merge ref rule does not filter on base branch) while reached_default_ref is B's URL and reached_default_basis is provider_pr_merged (the observation ref rule selects only rows whose base branch equals default_branch). The two refs are drawn from different row sets and must not be the same selection.
• GIVEN a pair whose only merged pull request is detached and whose base branch is the repository's default_branch, plus snapshots showing ahead > 0, WHEN the pair is evaluated, THEN rule 1 does not match, no provider_pr_merged observation is offered, reached_default_at stays NULL, and the pair classifies unknown / branch_commits_unmerged at rank 5 — a detached row is excluded from the observation exactly as it is from rule 1.

Idempotency, ordering and concurrency

• GIVEN a ledger row classified pr_merge, WHEN it is evaluated again with unchanged inputs, THEN every classification and observation column is unchanged, updated_at is unchanged, and last_evaluated_at and evaluation_seq advance.
• GIVEN a pair with two merged pull requests, WHEN delivery_ref is selected, THEN it is the one with the earliest merge instant, and on an exact tie the one with the lower request number.
• GIVEN a pair with one merged GitHub pull request and one completed Azure DevOps pull request, WHEN delivery_ref is selected, THEN the GitHub row's merged_at and the Azure row's updated_at are compared as merge instants, and on an exact tie at equal request numbers azure_devops sorts before github.
• GIVEN a pair with two default-branch snapshots sharing the same created_at, WHEN delivery_ref is selected, THEN it is the lexicographically greatest head_commit of the two, and repeated evaluations select the same one.
• GIVEN a row classified pr_merge at rank 8 with observed_branch_commits = 12, WHEN the pull request is detached and the pair is re-evaluated so the computed evidence ranks lower, THEN the stored outcome, basis, ref and rank are all unchanged, delivery_ledger_demotions_suppressed_total increments, and observed_branch_commits still reads 12.
• GIVEN a row classified pr_merge whose snapshots are all deleted with their session, WHEN the pair is re-evaluated, THEN observed_branch_commits does not decrease.
• GIVEN two evaluators writing the same pair concurrently, one computing rank 1 and one computing rank 8, WHEN both statements commit in either order, THEN the row reads pr_merge at rank 8.
• GIVEN a row whose reached_default_at is NULL and two concurrent evaluations each supplying a different first observation, WHEN both commit, THEN reached_default_at, reached_default_basis and reached_default_ref all come from the same one of the two — the triple is never mixed.
• GIVEN a row whose reached_default_at is set, WHEN a later evaluation observes the default branch again through a different basis, THEN reached_default_at and reached_default_basis are unchanged.
• GIVEN a pair with no ledger row and no snapshot and no provider row, WHEN a sweep runs, THEN the pair is selected as due and a row is written with basis no_observations; AND WHEN the next sweep runs with nothing changed, THEN the pair is not selected again.
• GIVEN an evaluation whose snapshot query returns an error, WHEN the pair is evaluated, THEN no column is written — including last_evaluated_at — delivery_ledger_evaluation_errors_total increments, delivery_ledger_evaluations_total does not increment, and the pair is still due on the next sweep.
• GIVEN a row whose stored observed_branch_commits is NULL and an incoming value of 7, WHEN the upsert runs, THEN the column reads 7 — a NULL stored value is lower than any incoming value and must not swallow it.
• GIVEN a pair whose inputs have not changed, WHEN it is re-evaluated, THEN delivery_ledger_evaluations_total increments but delivery_ledger_rows_written_total does not, because no classification or observation column changed and updated_at did not advance.
• GIVEN a pair with two merged GitLab merge requests carrying the same mr_iid under different project_path values, WHEN delivery_ref is selected, THEN the lower project_path wins and repeated evaluations select the same URL.
• GIVEN a sweep pass that encounters the same three sessions with empty repository_id on two consecutive passes, WHEN each pass publishes, THEN delivery_ledger_sessions_unattributed_total reads 3 after both — it is a gauge set per pass, not a running total.
• GIVEN a repository that is soft-deleted, WHEN sweeps run, THEN its pairs' last_evaluated_at stops advancing and their existing rows are retained unchanged.
• GIVEN a soft-deleted repository with a pair whose reached_default_at is NULL and whose last_evaluated_at is three days old, WHEN sweeps run, THEN the pair is not selected — the freeze is evaluated before the three due conditions and overrides stale refresh.
• GIVEN a soft-deleted repository with a candidate pair that has no ledger row, WHEN sweeps run, THEN no row is written and the pair is not selected on any pass — the freeze also overrides the unconditionally-due rule.
• GIVEN that same soft-deleted repository, WHEN deleted_at is cleared, THEN repositories.updated_at advances and the pair is selected as due on the next sweep.
• GIVEN an archived task with a live repository, WHEN sweeps run, THEN its pairs remain candidates and remain eligible for selection under the same three due conditions as any other pair — archiving a task neither excludes it from candidacy nor freezes it, and no predicate anywhere reads tasks.archived_at.
• GIVEN that same archived task, WHEN one of its sessions writes a new git snapshot, THEN the pair is selected as due on the next sweep and last_evaluated_at advances — archived pairs are re-evaluated on input movement exactly like unarchived ones.
• GIVEN that same archived task with reached_default_at already set and no input row moving, WHEN sweeps run, THEN the pair is not selected and last_evaluated_at does not advance — it is due under none of the three conditions, which is correct and is not a freeze. Eligibility is what archiving preserves; continuous advance is not something any pair gets.
• GIVEN an evaluation that begins reading its inputs at T0 and commits its upsert at T2, and a snapshot for the same pair written at T1 with T0 < T1 < T2, WHEN the upsert commits, THEN the stored last_evaluated_at is T0, so last_evaluated_at < MAX(input.created_at) still holds and the pair is selected as due on the next sweep. Recording T2 would mask the T1 snapshot permanently.
• GIVEN a pair whose evaluation began at T0 and a concurrent, faster evaluation of the same pair that began at T3 > T0 and committed first, WHEN the slower evaluation commits, THEN last_evaluated_at still reads T3 — the high-water rule means a slow evaluation cannot rewind the column.
• GIVEN a pair with no snapshots at all, WHEN it is evaluated, THEN observed_branch_commits is NULL and not 0.
• GIVEN a pair whose stored observed_branch_commits is 12 and whose snapshots have all been deleted, WHEN it is re-evaluated so the incoming value is NULL, THEN the column still reads 12.
• GIVEN a candidate pair whose non-empty repository_id matches no row in repositories, WHEN a sweep runs, THEN no ledger row is written for it, no upsert is attempted, delivery_ledger_pairs_missing_repository_total counts it for that pass, and delivery_ledger_write_errors_total does not increment — the pair is excluded from candidacy rather than attempted and failed.
• GIVEN that same pair, WHEN the missing repositories row is later created, THEN the pair becomes a candidate on the next sweep and a ledger row is written.
• GIVEN a github_task_prs row whose task_id matches no row in tasks — the task was hard-deleted and the provider row was not pruned with it — WHEN a sweep runs, THEN no ledger row is written for that pair, no upsert is attempted, delivery_ledger_pairs_missing_task_total counts it for that pass, and delivery_ledger_write_errors_total does not increment — so the primary migration-failure signal keeps its resting value of 0 on a healthy schema.
• GIVEN that same orphaned provider row, WHEN two consecutive sweep passes run with nothing changed, THEN delivery_ledger_pairs_missing_task_total reads the same count after both — it is a gauge set per pass, not a running total — and neither pass writes a row or logs delivery_ledger.write_failed.
• GIVEN a candidate pair rejected for a missing tasks row, WHEN the sweep orders its due pairs, THEN the pair is absent from the ordering entirely rather than sorting on a NULL tasks.created_at, and the exclusion is observable through the gauge rather than being an invisible join drop.
• GIVEN a ledger table that does not exist because its migration was swallowed, WHEN a sweep pass runs, THEN candidacy is still computed from the input tables, the dueness read fails, every candidate is treated as due, delivery_ledger.dueness_unavailable is logged exactly once for that pass, delivery_ledger_write_errors_total increments once per pair whose upsert failed, delivery_ledger.write_failed is logged exactly once for that pass, delivery_ledger_evaluation_errors_total does not increment, and the pass still reaches its last candidate rather than aborting on the first failure.
• GIVEN that same missing table and a candidate pair whose repository is soft-deleted, WHEN the pass runs under the dueness fallback, THEN that pair is still not evaluated and no upsert is attempted for it — the fallback widens dueness only, and the freeze is evaluated ahead of it.
• GIVEN that same missing table and a candidate pair whose task_id matches no tasks row, WHEN the pass runs under the dueness fallback, THEN the pair is excluded by Candidate pairs condition 3 and counted in delivery_ledger_pairs_missing_task_total, and no upsert is attempted for it — so it contributes nothing to delivery_ledger_write_errors_total.
• GIVEN a healthy ledger table and a transient failure of the dueness read on one pass, WHEN that pass runs, THEN every candidate is evaluated once, every upsert succeeds, delivery_ledger_write_errors_total does not increment, no classification or observation column changes value for a pair whose inputs did not move, and the next pass computes dueness normally.
• GIVEN that same missing table, WHEN the sweep publishes at the end of the pass, THEN delivery_ledger_last_evaluated_unix reads -1 and delivery_ledger_stall_seconds reads -1, and delivery_ledger.unavailable is logged — not 0/0, which is the healthy-and-empty state and would make a broken ledger indistinguishable from a fresh one.
• GIVEN a boot at which the task_delivery_ledger migration failed, so telemetry.delivery_ledger.activated_at is absent from kandev_meta, WHEN the backend runs, THEN the sweep still starts and still attempts its upserts — the activation key does not gate the writer, and gating it would silence the very counters that detect the failed migration.
• GIVEN a pair whose ancestry check errored and whose reached_default_at is therefore NULL, and no input row moves afterwards, WHEN 24 hours pass, THEN the pair is selected as due by the stale-refresh condition and the ancestry check is attempted again.
• GIVEN a pair whose reached_default_at is NULL, whose session authored two or more distinct non-empty head commits so the ancestry precondition is met, and whose selected head commit is an ancestor of refs/remotes/origin/<default_branch> in the repository's local checkout — a merge that landed long after the task's last session ended, moving no row in any Kandev table — WHEN the next stale refresh evaluates it, THEN reached_default_at is set, reached_default_basis is ancestor_of_default, and reached_default_ref is that commit. The ancestry relation is stated as a precondition rather than assumed: this repository squash-merges by policy, so a merged branch head is normally not an ancestor (see Evidence, finding 2), and a test that omits the relation is asserting nothing.
• GIVEN that same pair where the merge was squashed, so the selected head is not an ancestor of the default branch, WHEN the next stale refresh evaluates it, THEN the negative result is discarded, reached_default_at stays NULL, and the pair is selected again by stale refresh 24 hours later — the condition retries indefinitely while the observation is missing, and that is the intended cost of not being able to see a squash.
• GIVEN a pair whose reached_default_at is already set, WHEN 24 hours pass with no input movement, THEN it is not selected by the stale-refresh condition — the condition applies only while the observation is missing.
• GIVEN a pair evaluated by a sweep pass, WHEN the next sweep runs 5 minutes after that pass finished, THEN at most one pass is ever in flight, so a pass that evaluates that pair advances its evaluation_seq by exactly one, never two, and each per-pass gauge is set exactly once for that pass. This says nothing about whether the pair is evaluated at all on a given pass — a pair that is not due is not evaluated and its evaluation_seq does not move, per the dueness scenarios above. The guarantee is against double-counting within a pass, not a promise of one increment per pass.

Migration and activation

• GIVEN a database created before this feature, WHEN the backend boots, THEN task_delivery_ledger exists, runs.outcome exists and is NULL on every pre-existing row, and no pre-existing row's values change.
• GIVEN the backend boots twice against the same database, WHEN migrations replay, THEN they apply cleanly the second time and telemetry.delivery_ledger.activated_at retains the value written on the first boot.
• GIVEN a Postgres deployment, WHEN the same migrations run fresh and then replay, THEN both succeed and duplicate-object errors are classified through internal/db.
• GIVEN a boot in which the task_delivery_ledger migration fails and the runner swallows the error at WARN, WHEN the boot completes, THEN telemetry.delivery_ledger.activated_at is absent from kandev_meta, because the schema probe found no table; AND WHEN a later boot applies the migration successfully, THEN the key is written with that boot's instant.
• GIVEN a boot in which the runs.outcome migration fails, WHEN the boot completes, THEN telemetry.run_outcome.activated_at is absent for the same reason, so no consumer reads the mechanism as live while the column is missing.
• GIVEN an activated database, WHEN a database reset runs, THEN telemetry.delivery_ledger.activated_at and telemetry.run_outcome.activated_at are absent from kandev_meta afterwards, and WHEN the backend next boots, THEN both are rewritten with the new instant.
• GIVEN an activated database, WHEN a reset deletes both activation keys and then fails partway through dropping user tables, THEN task_delivery_ledger rows may remain but both keys are absent — so no consumer reads the mechanism as live over data it cannot trust — and WHEN the backend next boots and the schema probe succeeds, THEN the keys are rewritten with that boot's instant.
• GIVEN a reset in which the activation-key deletion itself fails, WHEN the reset runs, THEN it fails and reports the failure, and no user table is dropped — the keys are never left pointing at data that a later step removed.
• GIVEN a task created before telemetry.delivery_ledger.activated_at that has no ledger row, WHEN the database is read, THEN the two facts are separately observable — the activation instant from kandev_meta and the absence of a row from task_delivery_ledger — so "not observed by this mechanism" is distinguishable from no_delivery_observed without inspecting any consumer.

Office run outcome

• GIVEN a run blocked by the pre-execution budget check, WHEN it finishes, THEN runs.status = 'finished' and runs.outcome = 'budget_blocked'.
• GIVEN a run skipped because the agent is not active, WHEN it finishes, THEN runs.outcome = 'agent_inactive' — even though that path writes no office_activity_log row.
• GIVEN a run held by an active task-tree hold, WHEN it finishes, THEN its outcome is task_tree_held.
• GIVEN a run whose task checkout fails transiently, WHEN the scheduler handles it, THEN it is retried or escalated after the retry budget and is not finished as completed work.
• GIVEN a run whose task is already checked out, WHEN the scheduler handles it, THEN it is requeued for retry and is not finished as completed work.
• GIVEN a task-bearing run whose agent was launched by the task starter, WHEN the agent-completed subscriber finishes it, THEN runs.outcome = 'processed' and it is not left NULL after activation.
• GIVEN a taskless run, WHEN the scheduler cannot launch it, THEN it is marked failed with a diagnostic error and does not report completed work.
• GIVEN a task-bearing run in a deployment with no task starter configured, WHEN the scheduler handles it, THEN it is marked failed with a diagnostic error, its checkout is released, and the agent is not launched.
• GIVEN two terminal callers reaching the same run row, WHEN both write, THEN the row's status and outcome both come from the later write — they are set in one statement and can never disagree.
• GIVEN a run that fails, WHEN FailRun transitions it through the shared transitionRunTerminal statement, THEN runs.status = 'failed' and runs.outcome IS NULL — the failed path writes NULL in the same statement, and no value from the five-value vocabulary is invented for it.
• GIVEN a day containing one failed run written that way, WHEN RunCountsByDayForAgent reports that day, THEN it counts in failed and in neither unclassified nor skipped — the NULL outcome is never read, because the three outcome-derived buckets are all conditioned on status = 'finished'.
• GIVEN a run whose FinishRun call fails and whose error the call site discards, WHEN the run is later inspected, THEN it is not finished, so it counts in neither succeeded nor skipped nor unclassified.
• GIVEN a run transitioned to a terminal status through office/scheduler.SchedulerService.FailRun, which reaches the runs repository's FinishRun without passing through transitionRunTerminal, WHEN the row is inspected, THEN runs.status = 'failed' and runs.outcome IS NULL, and the row counts in failed and in neither unclassified nor skipped.
• GIVEN a run transitioned through office/scheduler.SchedulerService.FinishRun, WHEN the row is inspected, THEN runs.status = 'finished' and runs.outcome IS NULL, so it counts in unclassified and not in succeeded — a terminal path with no established semantic label is never counted as a success.
• GIVEN a day containing one processed run, one budget-blocked run, one failed run and one pre-activation finished run with outcome IS NULL, WHEN RunCountsByDayForAgent reports that day, THEN it returns succeeded = 1, skipped = 1, unclassified = 1, failed = 1 and other = 0.
• GIVEN a finished run whose outcome holds a value outside the five named ones, WHEN that day is reported, THEN it counts in skipped — the bucketing is total and no query errors.
• GIVEN that same day, WHEN the agent dashboard renders it, THEN AgentRunActivityDay.total equals succeeded + skipped + unclassified + failed + other, and AgentSuccessRateDay reports succeeded = 1 and unclassified = 1 against the same total.
• GIVEN a day made up entirely of pre-activation finished runs with outcome IS NULL — three of them, and nothing else — WHEN RunCountsByDayForAgent reports that day, THEN succeeded = 0, skipped = 0, unclassified = 3, failed = 0, other = 0; AND WHEN the dashboard renders it, THEN AgentSuccessRateDay reports succeeded = 0, unclassified = 3 and total = 3, so a reader can tell from the response alone that the day predates the mechanism rather than recording three failures to succeed.
• GIVEN a day made up entirely of post-activation runs, WHEN the dashboard renders it, THEN AgentSuccessRateDay.unclassified is 0 — the field is the marker for the pre-activation series and reads zero once every terminal run carries an outcome.

Writer health

• GIVEN the ledger writer has not evaluated any pair for longer than its 15-minute stall threshold while task sessions continue to complete, WHEN the sweep completes a pass, THEN delivery_ledger_stall_seconds exceeds 900 and a WARN log with the message delivery_ledger.stalled is emitted once for that pass.
• GIVEN the backend restarts, WHEN the first sweep after the restart completes, THEN delivery_ledger_last_evaluated_unix reports the true MAX(last_evaluated_at) from the database even though every counter has reset to zero.
• GIVEN an empty ledger table, WHEN the sweep publishes, THEN delivery_ledger_last_evaluated_unix is 0 and delivery_ledger_stall_seconds is 0 — an empty table is not reported as an infinite stall.
• GIVEN a ledger holding evaluated rows and a database in which no session survives the comparand filters — every session has an empty repository_id, or belongs to a soft-deleted repository, or there are no sessions at all — WHEN the sweep publishes, THEN delivery_ledger_last_evaluated_unix reports the true MAX(last_evaluated_at) and delivery_ledger_stall_seconds is 0, and no delivery_ledger.stalled WARN is emitted — an empty comparand means there is no work to be behind on, not that the writer is stalled.
• GIVEN a ledger holding evaluated rows and a comparand query that errors while the ledger query succeeds, WHEN the sweep publishes, THEN delivery_ledger_last_evaluated_unix reports the true MAX(last_evaluated_at), delivery_ledger_stall_seconds reads -1, and delivery_ledger.comparand_unavailable is logged once for that pass — the stall figure is unknown rather than zero, so a repeatedly failing comparand read can never report a healthy writer.
• GIVEN a healthy writer that has evaluated every due pair, and a session with an empty repository_id that updated one hour ago, WHEN the sweep publishes, THEN delivery_ledger_stall_seconds is 0 and no delivery_ledger.stalled WARN is emitted — an unattributed session contributes to no pair and must not drive the comparand.
• GIVEN a healthy writer and a session belonging to a soft-deleted repository that updated one hour ago, WHEN the sweep publishes, THEN delivery_ledger_stall_seconds is 0 — that pair's evaluation is frozen by design.
• GIVEN a writer that has stopped, and an archived task whose session updated twenty minutes ago, WHEN the sweep publishes, THEN delivery_ledger_stall_seconds exceeds 900 and delivery_ledger.stalled is emitted — archived tasks are still evaluated, so their sessions still count toward the comparand and a stall on them is a real stall.

Out of scope

Each exclusion below is a contract, not an omission.

• The extract itself. The downstream point-in-time extract that reads this table is external to this repository; no extract code exists here and none is added. This spec's obligation is to make the ledger readable without ambiguity — the activation instant in kandev_meta, NULL rather than 0 for legacy rows, and evaluation_seq — and every scenario above is stated as an observable property of the database, never of a consumer.

• A structured stop reason for a task or session. task_sessions carries free-text error_message ("task archived", "task tree archived", raw rate-limit JSON) and a state enum, and nothing else. This is a different grain (session, not run), a different table, and its enum cannot be derived without enumerating every writer of error_message and every state transition. It gets its own card. The runs.outcome contract in this spec does not cover it and must not be extended to task_sessions.

• Consuming the GitHub push webhook for merge inference. The push_webhook_default basis is defined in the vocabulary so a later card can populate it without a schema change, but no subscriber is added here. The webhook fires only for GitHub App installations; 10 of the 12 repositories in the reference store have no provider at all, so it can never be the primary mechanism.

• Reconstructing history. No ledger column is ever backdated or inferred from evidence the mechanism did not itself observe. first_classified_at and reached_default_at are the instants this mechanism made the observation, never the instant the underlying work happened, so a pair whose branch merged months before activation records the observation instant and not the merge. There is no import, no reconstruction from office_activity_log, and no derivation from a provider's history API.

  This is not a claim that old pairs go unevaluated. Every pre-existing (task, repository) pair is a candidate, has no ledger row, and is therefore due on the first sweep after activation and classified from whatever evidence is still present — see Sweep selection predicate. Those two statements were previously in tension in this document; the distinction that resolves them is reconstruction versus evaluation. Classifying an old pair from evidence visible today is ordinary evaluation. Asserting when that pair delivered, from evidence the ledger never saw, is reconstruction, and only reconstruction is excluded. The activation instant in kandev_meta is what lets a consumer tell the two apart: every row is timestamped at or after it.

• Making RunCountsByDayForAgent dialect-portable. It is pre-existing SQLite-only code; this card reshapes its buckets and nothing else.

• Retiring the dormant office/scheduler.SchedulerService.FinishRun / .FailRun pair. They call the runs repository's FinishRun directly, bypassing transitionRunTerminal and therefore also bypassing the OfficeRunProcessed publish that the service-layer path performs. This card threads outcome through them (both pass NULL, see Office run outcome) because the shared signature change forces the compiler to reach them, and stops there. Deciding whether a second terminal-transition path should exist at all — and whether the missing bus publish is a defect — is a behavioural question about run lifecycle, not about telemetry, and it gets its own card.

• The second status = 'finished'-as-success consumer. apps/backend/internal/office/summary/inputs.go counts r.status = 'finished' as completed when it assembles continuation summaries for an agent. It has exactly the defect this card fixes in RunCountsByDayForAgent — a budget-blocked or idle-skipped run reads as completed work — and it is deliberately not changed here. It is a different consumer at a different grain, feeding agent prompt context rather than a dashboard, and changing what an agent is told about its own history is a behavioural change that deserves its own card and its own review. It is named here rather than left silent so that after this card ships, nobody concludes from ## Why that every finished-as-success reader has been corrected. It gets its own card.

• Distinguishing a research card from a chore. The ledger separates delivery from non-delivery. It does not classify intent, and no_delivery_observed is not a judgement about whether the card should have delivered.

• Attributing delivery to a session, a turn, or a workflow step. The ledger's grain is (task, repository). A session's snapshots attribute to that session's single task_sessions.repository_id; a session spanning more than one repository is not modelled.

• Deduplicating delivery credit when one pull request serves several tasks. Both tasks read pr_merge.

• Recording a closed pull request's disposition (superseded, duplicate, withdrawn). That is a separate card against the provider tables.

• Any user-visible surface. No board column, badge, filter, dashboard tile, or settings control is added, and no new copy is rendered. If a later card surfaces the ledger or the new run-outcome buckets in the web UI, that copy goes through t() and that card owns the E2E coverage.

• Changing runs.status semantics, or changing what any existing consumer of runs.status reports.

• Populating task_session_commits, pre_commit_snapshot_id, or post_commit_snapshot_id. Those are separate cards and this spec does not depend on them.