Documentation
¶
Overview ¶
Command upstream-drift reports how far mast's ported files have fallen behind the go-steer/core-agent commits they were copied from.
Why this exists rather than a diff ¶
Every ported file carries an attribution trailer naming the upstream commit it was copied at:
// Originally derived from go-steer/core-agent@<sha>[:<upstream-path>]
The obvious detector — diff the file against upstream — is useless here: 100% of ported files already differ. They differ by the attribution line itself, by ~/.mast vs ~/.core-agent paths, by mast-flavored comments, and (increasingly) by real product divergence. A diff-based report says "180 of 180 files differ" every week and means nothing.
The question worth answering is the other one: *has upstream moved this file since we copied it?* That is a git-log query against the attributed SHA, and it is what this tool runs. It reports what changed upstream, not how the two copies differ today — a file mast deliberately rewrote still shows its upstream commits, because "upstream fixed a bug in code we rewrote" is exactly the case a human needs to look at.
Why it never fails the build ¶
Drift is normal and expected. Some of it is code mast will re-port wholesale when P1.3's gate opens (see docs/fork-design.md); some is in packages that have genuinely forked and will never sync again. A red build on a condition nobody can clear teaches people to ignore red builds. The signal goes to a job summary and a tracking issue; the exit status stays 0 unless the tool itself could not run.
A non-zero exit therefore means one thing only: the report could not be produced (no clone, unreadable repo, unknown SHA). That distinction matters — a silent "0 commits of drift" caused by a broken clone is strictly worse than no report at all, so every way of failing to *look* is reported as a status on the row rather than counted as clean.
Usage:
go run ./dev/upstream-drift --upstream ../core-agent go run ./dev/upstream-drift --upstream ../core-agent --ref origin/main
Source Files