fix(dev): guard merge train ownership and validation

[lusoris]

Summary

The local train promoted stacked PR #1420, reused an active agent checkout, and merged it into #1396 after its rebase push failed. Route promotion, rebase, and merge through one tracked guard that requires a master target, honors holds and source ownership on every action, and stops promotion after any rebase/push failure.

Merges require a receipt generated by executing full make lint and make test on the exact clean PR head, plus present, passing required hosted checks. A separate migration helper previews an exact hashed plan, preserves original scripts/holds, and installs paused adapters with gateway hash checks and read-only observer defaults. The operator guide is docs/development/merge-train.md.

This PR remains draft and held. Source publication does not deploy the runtime or establish RC1 readiness.

Type

• fix — local merge-train control and ownership bugs
• build / ci — developer automation

Validation

• 26 disposable-repository regression tests pass. They run real Git and Make with fixture GitHub metadata and cover holds/non-master bases, active owners, failed rebases/pushes, exact-head checks, altered receipts/logs, environment overrides, migration snapshots, symlink/drift failures, and paused observer defaults.
• Strict mypy passes on both tools and both test files.
• Normal commit hooks pass, including Ruff, Black, markdownlint, Semgrep, and the regression hook. Generated shell adapters pass ShellCheck and shfmt.
• Full repository make lint and make test have not been run successfully for this head. The fixture Make commands validate the runner's behavior; they are not native VMAFx, backend, golden-data, or full local-gate acceptance.

Checklist

• Commits follow Conventional Commits.
• Full make lint and make test are green locally for this exact head — still required before merge.
• Human-readable operator and migration documentation ships with the tools.
• ADR-1244 was atomically reserved and committed before implementation; its index fragment/order/rendered index are included.
• No C, SIMD/GPU, public libvmaf, or FFmpeg surface changes; backend parity and patch replay are not applicable.

Bug-status hygiene

• docs/state.md records T-MERGE-TRAIN-CONTROL-2026-09-08 and leaves runtime migration open until independently evidenced.

Netflix golden-data gate

• No Netflix assertAlmostEqual(...) score was modified.

Deep-dive deliverables

• Research digest — docs/research/merge-train-control-2026-09-08.md records the incident, installed-tool semantics, experiments, and limits.
• Decision matrix — docs/adr/1244-merge-train-ownership-and-validation.md, Alternatives considered.
• AGENTS.md invariant note — scripts/dev/AGENTS.md preserves shared guards, full-gate receipts, failure propagation, and explicit runtime migration.
• Reproducer / smoke-test command — below.
• CHANGELOG fragment — changelog.d/fixed/merge-train-ownership-guard.md.
• Rebase note — docs/rebase-notes.md, local control boundary entry.

Reproducer

python3 -m unittest discover -s scripts/dev/tests -p 'test_*merge_train_guard.py'

Known follow-ups and migration

• The original watchdog/train/agent actors were suspended by the coordinating operator. This branch never kills, resumes, starts, or installs a runtime actor automatically.
• Review the committed installer plan, retire the exact old actors, preserve all active branch/worktree protections and holds, then install with --apply --expect-plan SHA256. The installed watchdog/operator remain read-only; PAUSED remains present.
• Obtain genuine exact-head full local gate receipts and passing required hosted checks before enabling promotion/merge. Zero required checks is not green; pending, skipped, failed, and cancelled checks are refused.
• A local hold cannot cancel auto-merge already stored on GitHub. Its owner must also disable that server-side state. Advisory locking serializes cooperating local tools; unrelated GitHub writers and arbitrary Git/editor mutations remain outside that lock.
• Local evidence is retained at .workingdir2/evidence/2026-09-08-merge-train-control/; it includes original runtime snapshots, fixture results, normal-hook logs, and the preview plan. That plan is not an installation or release-acceptance receipt.

Reviewed runtime migration update — 2026-09-08

The coordinating operator has now completed the runtime migration from this exact source head, adacaa9a1beb2806efd13ac42ad52a214e2b63a4, using reviewed plan 5dfaecc7e07c4c60305d3c3fcbf2cb4b1c4042ae4721479f829932b953a4d0d2. The installed gateway hash is 9ed100056bb7d98b89d080066b61dfbebe90de4db6d1d7fa38f18a110acec977.

• The three identity-verified suspended legacy actors were retired without resuming their old instructions; they and their bridge children were verified absent.
• Original runtime scripts and hashes are preserved in .claude/mergetrain/migration-6wtg48lv/. Holds were preserved and PAUSED remains present.
• Previously stored auto-merge was disabled on owned feat(bench): A/B the fork against upstream Netflix, gated on score parity (ADR-1228) #1393, perf(cuda): size the ADM AIM CM launch by SM count instead of a fixed 8 rows (ADR-1226) #1388, and fix(cuda): reassemble the int64 warp reduction, correct the ADM doc, add nvcc --threads #1385, with unchanged heads. Release PR chore(master): release 1.0.0-rc.1 #1213 was unchanged.
• A fresh read-only observer was started. Its first two passes completed with all candidates refused because the train is paused; promotion and merge were not enabled.

Detailed plan, installation, identity, before/after PR, and observer receipts are retained under .workingdir2/evidence/2026-09-08-merge-train-control/runtime-migration/. This supersedes the earlier runtime-migration-pending status only; no source changed. The 26 control/migration tests remain passing, but full repository make lint and make test for this guard head remain unverified. This runtime repair does not establish RC1 readiness or permit merging this held draft.

[lusoris]

Superseded by the pre-rc.1 fixing train in #1425, which carries this work.

Closing rather than leaving it open, because the ADR Collision Guard — a required check — fails #1425 while two open PRs claim the same ADR number. The guard is right that they collide; it cannot tell that one of them contains the other.

Verified before closing, not assumed: every ADR file this branch adds is byte-identical in #1425 (sha256 compared), and the branch's commits were replayed onto the train individually, with each conflict resolved by hand and recorded in the commit messages.

The branch is untouched, so this is reversible — reopen if #1425 is abandoned.