task: enumerate the mechanisms that could enforce a ledger row for upstream-owned files

[tucktuck101]

Parent PRD

#273

The question

What mechanisms could enforce "a change to an upstream-owned file requires a ledger row", and what does each cost a contributor?

#301 asks whether the divergence register is machine-checked and what that costs. It weighs one implementation — extending launchpad-pr-check.yml — against the cost of a contributor fixing a typo in an upstream-owned file and getting a red check. The mechanism set was never enumerated, and at least one candidate is materially different in cost and has not been named anywhere in the thread:

• CODEOWNERS on upstream-owned paths. This does not check for a ledger row; it routes the review to whoever owns the boundary. Different assurance, much lower contributor friction, no script to maintain, and it composes with branch protection rather than with CI. Whether it can express "everything except launchpad/" is the open question — CODEOWNERS pattern semantics are last-match-wins and its negation support is limited.
• A CI check on the PR diff, the assumed option — the cost being that it fires on every legitimate upstream-file edit, not only on new divergence.
• A pre-push or pre-commit hook via the existing lefthook.yml, which fails earlier and locally but is bypassable and is itself one of the contested files.
• A post-merge assertion rather than a pre-merge gate: notice that an unregistered divergence exists and report it, instead of blocking the PR that created it. Weaker, but it never blocks anyone and it catches divergence that arrives by a path no gate covers.
• Nothing, plus a scheduled drift report. The precedent exists in this repo: task: make project-board membership automatic, and detect it when it drifts #293 argues for exactly this shape for board membership, on the grounds that a control whose failure is invisible provides no assurance.

Measured 2026-08-22: no CODEOWNERS file governs the boundary and no check enforces it.

Objective

A recorded enumeration of enforcement mechanisms for the upstream-file boundary, each with what it assures, what it costs a contributor, and whether it can express the launchpad/-excluded path set.

Why #273 cannot proceed without this

Under ADR-0022 a contested file with no ledger row is never presented for adjudication at all — it falls into the 99% adopted wholesale. That makes ledger completeness a correctness property, not a documentation nicety, and it makes the enforcement mechanism load-bearing rather than optional. #301 cannot weigh cost against assurance while the cheapest candidate is missing from its options. It also depends on the required-checks gap filed alongside this one: a pre-merge gate that cannot be made required is a suggestion, and that reorders the candidates.

Definition of done

• Each candidate is described by what it assures and what it costs, including the failure mode of each.
• Whether CODEOWNERS can express "all upstream-owned paths, excluding launchpad/ and .github/workflows/launchpad-*" is established by testing a pattern set, not by reading about it.
• For each pre-merge candidate it is stated whether it can actually block, given no status check is currently required on launchpad.
• The false-positive rate of the CI-check option is estimated against real history — how many merged PRs touched an upstream-owned file without creating new divergence.
• The "nothing, plus a drift report" option is assessed on its merits rather than as a null option, since task: make project-board membership automatic, and detect it when it drifts #293 makes that argument for a comparable control in this repository.

If we guess instead

#301 chooses between a bespoke check and nothing, having never considered the mechanism that is a two-line file. The likely outcome is the check — contributors hit it on unrelated edits, it acquires exceptions, and the exceptions are where lost ledger rows come from. Which is the failure the check existed to prevent, arriving through the check itself.

Impacted components

.github/workflows/launchpad-pr-check.yml
.github/CODEOWNERS                          (does not exist)
lefthook.yml
launchpad/upstream-sync/DIVERGENCE-REGISTER.md   (does not exist yet)

Unblocks the options half of #301. Depends on the required-checks gap filed alongside.

Out of scope

• Deciding whether the ledger is machine-checked — adr: whether the divergence register is machine-checked, and what that costs contributors #301.
• Implementing any mechanism or committing a CODEOWNERS file.
• Writing the ledger.

---

_{Filed by an AI agent (Claude Opus 5) on behalf of @tucktuck101 on 2026-08-22, as part of a knowledge-gap sweep over #273. This issue asks a question. It does not answer it, does not propose a decision and closes nothing — agents draft, humans decide (launchpad/AGENTS.md §5.1). Three headings beyond 02-task.yml (The question, Why #273 cannot proceed without this, If we guess instead) are present because the sweep brief requires each gap to carry them.}

[tucktuck101]

Answer

The cheapest mechanism is also the most accurate, and it was not in #301's options. CODEOWNERS expresses the boundary in six lines — tested against the real 4,351-file tree, partitioning 4,029 upstream-owned from 322 fork-owned with a two-file residue that is arguably correct.

And the CI-check option's cost, measured rather than estimated: 11 of 60 merged PRs touched an upstream path — 8 correctly, 2 false positives CODEOWNERS gets right, and 1 catastrophic: the 981-file drop PR.

Written up in PR #429 → launchpad/Research/369-enforcing-the-upstream-boundary.md.

---

Mechanism	Assures	Contributor cost	Blocks today?	Failure mode
CODEOWNERS	The boundary was reviewed	O(1) — one review request per PR	No — codeowners:false	Reviewer rubber-stamps
CI check for a ledger row	The boundary is documented	O(files) — a row per file	No — checks:null	Breaks on drop PRs (981 files)
lefthook pre-push hook	Same, earlier	O(files) + local run time	No — --no-verify	Silently skipped
Post-merge assertion	Divergence is noticed	Zero	Reports only	Report nobody reads
Nothing + drift report	Drift is visible	Zero	Reports only	Same, plus latency

CODEOWNERS: tested, not read about

No ! negation — "using ! to negate a pattern doesn't work" — but "you can exclude a subdirectory by adding a pattern for it without specifying any owners", with last-match-wins. So "own everything, then un-own what the fork owns" works:

*                                    @launchpad-26/boundary-reviewers
/launchpad/
/.github/workflows/launchpad-*.yml
/.claude/
/.github/ISSUE_TEMPLATE/
/LAUNCHPAD.md

Ran the documented semantics over every tracked file:

tracked files:            4351
CODEOWNERS-owned:         4029
CODEOWNERS-unowned:        322

fork-added files STILL owned (would trigger a review request): 2
    desktop/src-tauri/src/managed_agents/runtime/summary.rs
    scripts/test-ci-changed-paths-filter.sh

The residue is arguably correct, not a defect. Both are fork-only files living inside upstream's directory structure. summary.rs is the strongest case — #360 found the drop's one semantic conflict landed exactly there, because it holds code extracted from an upstream-owned file. If any two fork files deserve boundary review, these are they. Two more no-owner lines would exclude them; I would not.

The CI check's real cost

merged PRs sampled: 60
PRs touching an upstream-owned path: 11

#	Files	What it was	Right to fire?
#259 / #257 / #221 / #205 / #192 / #182 / #169 / #238	1–3 each	h2 bump, pack JSON, cfg(unix), Windows sidecars, lefthook pin, ci.yml filter, branch-skew, AGENTS.md	Yes — all 8 created real divergence
#194 / #189	1, 5	.claude/skills/*	No — false positive
#216	981	the upstream sync	No — catastrophic

More accurate than #301 assumes on ordinary PRs — 8 of 10 firings correct — and broken in two specific ways.

The false positives are fork-only additions living outside launchpad/. A path-based check flags .claude/skills/*; CODEOWNERS does not, because the pattern set un-owns /.claude/. A concrete accuracy win, not a tie.

The catastrophic case is what matters. A drop PR touches 981 upstream files and creates no new divergence, so a per-file ledger check must exempt drop PRs — and the drop is precisely when divergence is most likely to be silently lost. A gate that switches itself off during the event it guards is not a gate. CODEOWNERS has no equivalent: a 981-file drop produces one review request. O(1) versus O(files) is the whole comparison for a fork whose largest PRs are drops.

Neither can block today, and that separates nothing

From #358: {"approvals":1,"checks":null,"codeowners":false,"enforce_admins":false}. No required check; require_code_owner_reviews off. Both are the same single admin toggle, and four people including the owner of this work already hold repository admin — so the "needs an org admin" premise that shaped #301 is false here too.

One real asymmetry: with code-owner review required, CODEOWNERS blocks by requiring a human, which cannot be satisfied by writing a row. #301 is really choosing between "someone looked" and "it is written down" — different properties, neither implying the other — not between two implementations.

The others, briefly

lefthook hook — same assurance, earlier, bypassable. PR #216 was itself pushed with --no-verify, which answers empirically whether the bypass gets used. And lefthook.yml is one of the 27 contested files, so the enforcement would live in a file the boundary is about.

Post-merge assertion — zero cost, reports rather than gates, and the only option that catches divergence arriving by a path no gate covers, including inside a drop. Same shape as the durability mechanism #362 and #366 recommend, so one mechanism could serve both.

Nothing + scheduled drift report — has a precedent here: #293 argues exactly this for board membership, because "an auto-add that stops working looks exactly like an auto-add that is working" and "a control whose failure is invisible provides no assurance." The argument transfers directly: a ledger check exempted on drop PRs looks exactly like one that is working. #293's remedy — compare the two sets, fail loudly on divergence — maps onto comparing ledger rows against the computed contested set, which #368 established is two git commands.

What this changes for #273

#301 should add CODEOWNERS and state which assurance it wants. Six lines, tested, O(1), and more accurate than the path-based check.

The drop-PR hole is what to design around either way. Under ADR-0022 a contested file with no ledger row is never presented for adjudication — a missing row is a lost decision. The combination that covers it is CODEOWNERS (pre-merge, O(1), survives drops) plus a post-merge or scheduled comparison against the computed contested set. Not a recommendation — #301 owns it — but neither half alone closes the hole.

And the cost is small. 11 of 60 recent PRs would have triggered a review request, 8 for changes that genuinely created divergence — roughly one extra review a fortnight, not a tax on ordinary work.

Confidence, and what is still unknown

High on the PR figures and the classification of all 11 — real merged PRs whose files I listed, and the eight correct firings map onto divergences #352 independently established.

Medium-high on the CODEOWNERS result, with one specific limit: I tested the pattern set against the real file list using a local implementation of the documented semantics, not GitHub's parser. GitHub's codeowners/errors endpoint validates a committed file, and committing one is a change I am not making. The partition is right per the documented rules; whether GitHub agrees on every edge — particularly /.github/workflows/launchpad-*.yml, the only wildcard — is unconfirmed. That is the thing to check before adopting, and it costs one commit on a throwaway branch.

Not checked. I sampled the 60 most recent merged PRs, not all ~216. @launchpad-26/boundary-reviewers does not exist — the pattern set names a team someone must create, and I did not check whether repo admins can create teams here. I did not enable require_code_owner_reviews to observe it. I did not test the lefthook option at all. I did not measure how long a boundary reviewer would take on a drop PR — the real cost of the CODEOWNERS option and the number I would most want. No builds run; disk is at 99% with 5.2 GiB free.

Sources: About code owners · github/docs#19818 on ! negation · #293 · #358

---

_{Answered by an AI agent (Claude Opus 5) on behalf of @tucktuck101 on 2026-08-22. Read-only: gh api over merged PRs and their files, git ls-tree/diff, and a local test of documented CODEOWNERS semantics. No CODEOWNERS file was committed and no protection changed. The only repository write is one research document on branch research/369-ledger-enforcement, offered as PR #429 and not merged. Nothing closed, nothing decided.}