process(sync): define a cursor-lag SLO, compute real ledger queue metrics, and write an escalation policy (batch/checkpoint syncs)

[IgorShevchik]

Background

Strategy-level companion to #75 (which tracks the operational blockers: automation PR #67, branch protection, env ephemerality). Surfaced during the June 2026 multi-angle project audit (CTO review). The sync design itself is sound (kill-switch, idempotent ledger, gated PRs) — what's missing is a throughput model: at the current manual gated cadence the upstream queue grows without bound, and lag isn't even measured.

Evidence

.sync/nuxt-ui.json: cursor at b597f90, 7 commits processed (PRs #68–#77) over ~3–4 weeks, sync_enabled: false, one-open-PR-at-a-time gate, and the stats block (queue_depth, noop_ratio, avg_pr_age) hardcoded to 0. nuxt/ui v4 lands commits daily. Process-fragility evidence: the ledger's last entry still says "b24ui_sha": "pending-merge" although that PR is merged at HEAD (overlap #75 §1).

Actions

• Define a lag SLO — e.g. "cursor stays ≤ 20 commits / ≤ 14 days behind upstream/v4" — and record it in .sync/PLAN.md.
• Compute queue metrics for real on every port: queue_depth = git rev-list --count <cursor>..upstream/v4, plus noop_ratio / avg PR age, written to the ledger so the trend is visible.
• Written escalation policy for SLO breach: batch consecutive same-component upstream commits into one PR, and/or switch to upstream release-tag checkpoint syncs when per-commit cadence can't keep up.
• Fix the stale ledger entry (pending-merge → actual merge SHA) and make "update ledger after merge" an explicit PORTING.md checklist line.
• One-line status note in .sync/PORTING.md + RUNBOOK.md: both reference sync-porter.yml / sync-on-merge.yml workflows that don't exist yet (pipeline not deployed) — a "status: not yet deployed, manual cadence" line prevents newcomer confusion.

Priority: P2 (P1 if automation in PR #67 stays blocked — then the manual model is the only model).

[IgorShevchik]

Closing this one — three of the five actions turned out to be already done, and the maintainer has decided against the other two.

Done, and recorded elsewhere:

• Fix the stale ledger entry, and make "update ledger after merge" an explicit checklist line. Both landed. .sync/PORTING.md §6 step 4 now says it outright — advance cursor, add the processed[sha] entry, reconcile the previous entry with its merged PR number and squash SHA — including the case the original wording missed, where the last entry of a run has no follower to reconcile it and needs its own small bookkeeping PR. No pending-merge remains in the ledger; chore(sync): reconcile the last four entries with #464 and #466 #467 reconciled the most recent four.
• A status note about the workflows that do not exist. .sync/nuxt-ui.json's _cursor_note states it plainly: "There is no dispatcher, no porter workflow and no kill-switch — .sync/PORTING.md is the whole procedure." .sync/PLAN.md and .sync/RUNBOOK.md, which described those workflows, were removed on 2026-08-12.
• Escalation policy — batch consecutive same-component commits. §6 step 4b covers this, with the constraint that batching taught us: two commits may share a PR only when nothing sits between them in topological order. Batching across a gap advances the cursor past the skipped commit and then moves it backwards when that commit is processed, so the ledger points behind upstream while every entry is present and correct.

Declined:

• A lag SLO (≤20 commits / ≤14 days). The sync is manual by explicit decision, and its pace is set by what else is worth doing that week. A threshold would not change the pace — it would only produce an alert nobody acts on, which costs more than it is worth.
• Real queue metrics written to the ledger. This existed as stats (queue_depth, noop_ratio, avg_pr_age) and was removed on 2026-08-12 for being telemetry that was never written to: noop_ratio: 0 against an actual 47 no-ops in 226 entries. Reinstating it only makes sense in service of the SLO above.

Worth flagging for anyone reading this issue later: the Evidence section describes a file that no longer exists. sync_enabled and the stats block are both gone, and the ledger is at 270 processed entries rather than 7. The keys today are upstream, branch, cursor, _cursor_note and processed.

If the queue ever does become the bottleneck, the thing to reopen is not this issue but the release-tag checkpoint idea in action 3 — the one option here that would actually change throughput rather than just measure it.

---

Generated by Claude Code