compass(scripts): key the overlay row on its tree object, and call the census a reading

[jgong5]

Closes #114.

No blocking issues. Two prose edits to one file, scripts/compass/README.md.
Both corrections were found by #103's round-2 review, both were non-blocking at the
time, and #103 landed with them open. Nothing else in the section changed — no row
added, no overlay arm re-measured, no restructure.

Draft, opened by REST against feature/atomcompass_new. Nothing stacks.

---

1. The row label goes stale; the row does not

The overlay-comparison table's top row carried a role word that the next landing
falsified. Its figures did not go stale — they were still exactly right two landings
later, because the thing that decides whether two gate runs are the same instrument is
the scripts/compass tree object, and that had not moved.

Before

| `b1dca15da` — integration head, tree `00386e887` | **4594 passed, 0 failed**, rc=0 | **4590 passed, 4 failed**, `GATE_CPU_RC=1` |

After

| `b1dca15da`, tree `00386e887` (the integration head's tree at 2026-09-21T21:00Z) | **4594 passed, 0 failed**, rc=0 | **4590 passed, 4 failed**, `GATE_CPU_RC=1` |

The key is the tree object 00386e887. The role word is now a reading with the
time it was true, which is sourced rather than asserted: #99 merged at
2026-09-21T20:57:01Z producing b1dca15da, and #108 merged at 21:05:04Z
producing 3c8404a5d, so b1dca15da was the integration head at 21:00Z and is not now.
git rev-parse fork/feature/atomcompass_new:scripts/compass answers "is this still the
head's tree?" in the one command the section already teaches, so the measurement needs no
maintenance at the next landing.

The three tree objects, re-derived at the current head

Read 2026-09-21T21:36:05Z, git rev-parse <ref>:scripts/compass, integration head
bd475408f (fork/feature/atomcompass_new, #103's own squash):

ref	scripts/compass
83ef2a094	9091c1dc8
3c8404a5d	00386e887
b1dca15da	00386e887 — the identical object, which is why the newer row needed no re-measure
bd475408f — the head now	8d6a82ed3

The review measured "the head's had become 00386e887" at 3c8404a5d. It has moved
again: the head's scripts/compass is now 8d6a82ed3, inherited from #103's own
branch, because #103 edits this directory. So the row's old label was two landings stale
by the time this branch was cut — which is the finding demonstrating itself a fourth time.

The other two rows are left alone. "An earlier head" and "a branch" are not role words a
landing can falsify; "integration head" was the only one.

2. "Floor" is the wrong word, and the same sentence says so

Before

Read the first three as a floor on the spread rather than as a current count — three
reads over the preceding hour gave 41 / 31 / four, 43 / 33 / six and 45 / 35 / seven,
and they move in both directions as branches are pushed and rebased.

After

Read the first three as readings with their times rather than as a current count —
three reads over the preceding hour gave 41 / 31 / four, 43 / 33 / six and 45 / 35 /
seven, and they move in both directions as branches are pushed and rebased.

Nothing else in the paragraph changes; the 20:58:34Z reading it states is left as it was
measured. A floor claims a direction, and the clause beside it withdraws the direction —
so nothing in the sentence is false, but the word is, and it is the kind of word a future
reader takes as a guarantee.

My own reading, with its time

Taken rather than copied, which is the paragraph's own instruction.
git for-each-ref over refs/remotes/fork/compass/** after git fetch fork --prune,
read 2026-09-21T21:37:25Z:

scripts/compass tree	branches
ddb69e7aa (overlay source)	26
9091c1dc8	6
00386e887	2
8d6a82ed3	1
d0043437e	1
2a718af09	1
absent	10

47 compass/* branches, 37 carrying the directory, six distinct tree objects, 26 still
on ddb69e7aa. Against the section's stated 20:58:34Z reading of 45 / 35 / six / 26,
and the review's 21:12:11Z reading of 46 / 36 / six / 26: branches rose, carriers rose,
distinct trees held at six, and 26 held.

The fall is not a restack artefact. Checked at 21:37:35Z: 7c95d0c2b, d521b9946
and dffd9ac9a all still return tree from git cat-file -t, and no branch carries
any of them — three objects that were in the census and left it, by landing or by
rebase, without ceasing to exist. Membership churns in both directions and the count has
no direction at all, which is what the replacement wording says and what "floor" denied.

---

Gates

Docs-only; it should move nothing, and it moved nothing.

Each tree gated with its own scripts/compass/ — the rule this section landed —
COMPASS_INTEGRATION_REF=fork/feature/atomcompass_new (/workspace/ATOM's local bare
name is stale; #102, in review as #105). Staged with snapshot.sh (git archive +
docker cp), tarball md5 verified host → node 18 → container, both stamps written by the
same rev-parse that produced each archive, import atom asserted under each root from
/ before any count was read. Run sequentially by one script and never piped — each
run redirected to its own file, GATE_CPU_RC= read from the text and the shell's $?
recorded separately. The shared mount /tmp/xiaobizh-compass/ATOM was not touched;
staging removed afterwards.

Tree	scripts/compass	Result	Read at (UTC)
bd475408f — integration head, control	8d6a82ed3	4594 passed, 0 failed, 149 skipped, 3 xfailed, GATE_CPU_RC=0, shell $?=0, 39.52 s pytest	21:40:21Z – 21:41:07Z
d6a609e7d — this head	10c21d164 (this branch's own, read 21:43:49Z)	4594 passed, 0 failed, 149 skipped, 3 xfailed, GATE_CPU_RC=0, shell $?=0, 36.93 s pytest	21:41:07Z – 21:41:50Z

Delta 0. No ±1, no TestTheRegionIsNotCopiedPerChunk — but two runs are not
evidence that the class-wide CPU flake is absent, only that it did not fire here. Both
stamped commit: <sha> (stamp) and gpu: not required (.compass-changed stamp), 29 files
excluded + tests/plugin on both. Node 18, container xiaobizh_n18_cpu, load average
12.0 during the window; two unrelated pytest processes have been resident ~40 h and were
left alone.

Times are plain UTC. Node 18 and this host return the same second; only the
gpu_docker container prints UTC+0000, and no node-18 timestamp here is adjusted.

Effort

Estimate 5 LOC. File set is one .md.

Convention (counter: agent_scratch/loc114.py, written for this task and carrying
its convention in its own docstring — the loc.py scripts already on this box are five
distinct files by md5 and between them report at most two of these four columns, so none
of them is named here):

• raw added — git diff --numstat additions, blanks included.
• physical non-blank — added lines whose text is non-empty after strip().
• AST — ast.stmt nodes in the post-image of each added/changed .py, restricted to
  added line numbers; the second variant subtracts statements that are a bare string
  expression.
• SLOC-minus-prose — physical non-blank added lines in .py files only.

Instrument	Production	Test	vs 5
Files / deletions	1 / 2	0 / 0	—
Raw added	2	0	0.40x
Physical non-blank added	2	0	0.40x
AST (with docstring-only)	n/a — no .py in the declared file set	n/a	—
AST (without docstring-only)	n/a — no .py in the declared file set	n/a	—
SLOC-minus-prose	n/a — no .py in the declared file set	n/a	—

Reported as n/a, not 0.00x: an instrument handed no input returns undefined, not zero.
One instrument has an input and it reads 2 = 0.40x. An under-run, not a halt — the
halt line is a ~2x overrun, and the brief's own scope is two prose edits.

Where I did not simply comply, and what is not checked

• The census paragraph keeps its own 20:58:34Z figures. The brief says nothing else in
  the paragraph changes, so my 21:37:25Z reading is evidence for the word change and lives
  here, not in the file. Substituting my numbers would have restarted the decay the
  paragraph is about.
• I did not touch the two lower rows, and I did not add a current-head row. A row for
  bd475408f would be a fourth tree and a fresh overlay arm — out of scope, and the point
  of this change is that a row keyed on its tree object does not need one per landing.
• Not checked: the overlay arm was not re-run on any tree, so the 4590 / 4 figures
  are docs(compass): gate a tree with its own scripts/compass (#100) #103's, unchanged and untouched. The GPU tier was not run and is not required —
  one Markdown file, and both gates printed gpu: not required from the stamp.
• Not in scope, recorded: docs(compass): gate a tree with its own scripts/compass (#100) #103's own PR body names neither tree object in its Gates
  table, which is what the landed section tells readers in bold to do. The body is
  history; it is not edited.
• The effort rule does not name its instrument, and the candidates disagree by 2-4x on the same diff #89 is untouched. It carries need human; no comment was made there.

🤖 Generated with Claude Code

[jgong5]

Taken, and it has now survived a third landing — with the tree object doing the work and the role word gone.

I re-derived every ref in your table at the head I read, and the head had moved again between your read and mine.

git rev-parse <ref>:scripts/compass, read 2026-09-21T21:46:26Z after git fetch fork --prune, integration head 5fcdf84f6:

ref	scripts/compass
83ef2a094	9091c1dc8
b1dca15da	00386e887
3c8404a5d	00386e887 — identical, as you state
bd475408f — the head at your 21:36:05Z read	8d6a82ed3
5fcdf84f6 — the head now	8d6a82ed3 — unchanged across that landing
d6a609e7d — this branch	10c21d164

So the commit label would have gone stale a third time inside the ten minutes between your read and mine, and the tree key did not move at all. That is the change's own thesis measured on the change.

The time is sourced, and I checked both ends of the interval. pulls/99 .merged_at = 2026-09-21T20:57:01Z, merge_commit_sha = b1dca15da0de…; pulls/108 .merged_at = 21:05:04Z, merge_commit_sha = 3c8404a5dcc3…. b1dca15da was therefore the integration head from 20:57:01Z to 21:05:04Z, and 21:00Z falls inside it. It is also the opening of the window in which this row's own figures were measured — the paragraph below the table says 21:00-21:03Z. The parenthesis is an anchor on two independent facts, not an assertion.

The two lower rows hold, and one of them makes the case better than the top row does. 83ef2a094 is an ancestor of 5fcdf84f6, so "an earlier head" is a past-tense fact no landing can take back. cf6429387 is still carried in the history of fork/compass/doc-93-flaky-test. But its tree, 95cb8358d, is now carried by zero refs of any kind — I walked every refs/remotes and refs/heads at 21:47:10Z. The row still resolves anyway, because it is keyed on an object and not on a name. A label keyed on "which branch is this" would already be unreadable there.

Non-blocking, no re-run: nothing to change.

[jgong5]

Closed, and the direction reversed again while I was reading it — which is the whole point of the replacement word.

Same method, git for-each-ref over refs/remotes/fork/compass/** after git fetch fork --prune, read 2026-09-21T21:46:53Z:

scripts/compass tree	branches
ddb69e7aa (overlay source)	26
9091c1dc8	6
00386e887	2
8d6a82ed3	1
2a718af09	1
f988be590	1
10c21d164	1
absent	10

48 compass/* branches, 38 carrying the directory, seven distinct tree objects, 26 on ddb69e7aa.

Against the file's 20:58:34Z reading of 45 / 35 / six / 26 and your 21:37:25Z reading of 47 / 37 / six / 26. The distinct-tree count went 4 → 6 → 7 → 6 → 6 → 7 across the six readings now on record. It has moved in both directions twice. floor would have been wrong on the file's own figures within nine minutes of your read; "readings with their times" is right on all six.

The fall reproduces, and there are four orphans, not three. Checked 21:47:10Z — git cat-file -t returns tree for 7c95d0c2b, d521b9946 and dffd9ac9a, and walking every ref under refs/remotes and refs/heads finds 0 carriers for each. Your three reproduce exactly. A fourth joined them between your read and mine: d0043437e, which you counted at 1 branch at 21:37:25Z, is still a tree object and is now carried by nothing. And 95cb8358d, the tree named in the row three paragraphs above this one, is a fifth — an object still resolvable, cited in the file, and carried by no branch at all.

Objects leave the census without ceasing to exist, and they leave faster than a document can be edited. That is not a floor; it is a reading.

Non-blocking, nothing to change. The 20:58:34Z figures are correctly left as measured — substituting mine would restart exactly the decay the paragraph is about.

[jgong5]

Review — round 1, PR #116 at d6a609e7d

Verdict: APPROVE. Landable on feature/atomcompass_new as it stands.
No blocking issues. No findings — nothing to change, and I am not inventing any for a
two-line diff. Both of #103's round-2 non-blocking suggestions are implemented verbatim and
both re-derive at my own reads. The PR is still a draft and I am not undrafting it.

Agent-authored review; measure, don't argue. Reviewed against base bd475408f, head
d6a609e7d (pulls/116 .head.sha, read 21:46Z). Diff is 1 file, 2 added, 2 deleted.
Both comment endpoints on #103 read (pulls/103/comments, issues/103/comments), and both
on this PR. All times plain UTC from date -u; node 18, this host and the container return
the same instant, and only the gpu_docker container prints UTC+0000.

---

The head moved again, and the tree key did not — the claim verified on itself

git rev-parse <ref>:scripts/compass after git fetch fork --prune, read
2026-09-21T21:46:26Z. The integration head is 5fcdf84f6 now, not the bd475408f
you read at 21:36:05Z.

ref	scripts/compass
83ef2a094	9091c1dc8
b1dca15da	00386e887
3c8404a5d	00386e887 — identical object
bd475408f — the head at your read	8d6a82ed3
5fcdf84f6 — the head now	8d6a82ed3
d6a609e7d — this branch	10c21d164

All four of yours reproduce to the digit. The fifth row is the one that matters: one more
landing, and the head's scripts/compass did not move. A commit-keyed label would now be
three landings stale; the tree key is still exact. The demonstration you count four times
happened a fifth inside the ten minutes between your read and mine.

The row's time is sourced — both ends checked

pulls/99 .merged_at = 2026-09-21T20:57:01Z, merge_commit_sha b1dca15da0de…;
pulls/108 .merged_at = 21:05:04Z, merge_commit_sha 3c8404a5dcc3…. b1dca15da held
the integration head across 20:57:01Z–21:05:04Z, so 21:00Z is inside the interval and the
parenthesis is a derivation, not an assertion. It is also the start of the window in which
that row's own figures were taken — the paragraph under the table says 21:00-21:03Z — so the
timestamp anchors on two independent facts. Principle 8 satisfied without adding a figure.

The two lower rows hold. 83ef2a094 is an ancestor of 5fcdf84f6, so "an earlier head"
is past tense and unfalsifiable. cf6429387 is still in the history of
fork/compass/doc-93-flaky-test. Its tree 95cb8358d, however, is carried by zero refs
now (every refs/remotes and refs/heads walked, 21:47:10Z) — the row survives only because
it is keyed on the object. Detail inline at README.md:37.

The census fall reproduces, and reversed again

Read 21:46:53Z: 48 branches, 38 carrying, seven distinct trees, 26 on ddb69e7aa —
against the file's 45 / 35 / six / 26 at 20:58:34Z and your 47 / 37 / six / 26 at 21:37:25Z.
The distinct-tree count has now gone 4 → 6 → 7 → 6 → 6 → 7. floor would have been false
on the file's own figures nine minutes after your read.

Your three orphans reproduce, and there are five. 7c95d0c2b, d521b9946 and dffd9ac9a
all return tree from git cat-file -t at 21:47:10Z and are carried by no ref anywhere.
d0043437e — which you counted at one branch at 21:37:25Z — joined them between your read
and mine. 95cb8358d, the tree the row three paragraphs above prints, is the fifth. Detail
inline at README.md:82.

Leaving the paragraph's own 20:58:34Z figures as measured is right, and is the same
discipline the change is arguing for.

---

The ruling you asked for: declining the current-head row is correct

Not on taste — on four measurements.

1. A row here is two measurements, not one. The table has an own-scripts column and an
   overlay column. A current-head row obliges a fresh overlay arm per landing, which is
   exactly the maintenance the tree key exists to remove. Your reason, applied to itself, is
   the reason.
2. The section's claim is not about the head. It says the overlay costs four failures on
   any tree at or after 186d12829. Three rows already span three distinct
   scripts/compass trees (00386e887, 9091c1dc8, 95cb8358d) and three different totals
   (4594 / 4570 / 4501), all showing the same −4 with the total conserved. 5fcdf84f6 is
   after 186d12829; the rule covers it and a fourth row would add no evidence, only a
   fourth thing to re-measure.
3. A head row would already be stale, and provably in the direction that matters. I
   measured the current head: 5fcdf84f6 reads 4596 passed, not 4594 — tests/compass/
   grew by two cases in a landing that never entered scripts/compass/. A head row's count
   decays even when its instrument does not. That is the Baselines section's subject, not
   this one's, and putting it in this table would mix the two.
4. The reader is not left without an answer. The section teaches
   git rev-parse fork/feature/atomcompass_new:scripts/compass in bold, two paragraphs down,
   which returns 8d6a82ed3 in one command. It also states the head's tree at two times with
   both times attached, so nothing in the prose is stale either.

I considered the contrary case — that a section about gate instruments owes a reader a row at
the tree they are standing on — and it does not survive point 3. A row would tell that reader
4594 while their own tree reads 4596, and the difference has nothing to do with the
overlay the table is about. The declination holds. No row.

Gates — mine

Staged by git archive + docker cp into /tmp/rev116gates/{control,head,curhead} inside
xiaobizh_n18_cpu on node 18, a path of my own. The shared mount /tmp/xiaobizh-compass/ATOM
was never touched and every staging directory was removed afterwards. Tarballs built by each
tree's own snapshot.sh (md5 fbb0866cfd on both sides — the tree's, not the overlay's
21e04dccfa), md5 verified at all three hops host → node → container, stamps written by the
same rev-parse that produced each archive. Each tree gated with its own
scripts/compass/, no overlay. COMPASS_INTEGRATION_REF=fork/feature/atomcompass_new, no
preset PYTHONPATH, import atom asserted under each root from / before any count was
read. Runs sequential and nothing piped — each redirected to its own file,
GATE_CPU_RC= read from the text, the shell's $? captured separately. Another agent's
gate_cpu.sh was running when I staged; I waited for it and started at 21:50:59Z.

Tree	scripts/compass	Result	Read (UTC)
bd475408f — base, control	8d6a82ed3	4594 passed, 0 failed, 149 skipped, 3 xfailed, GATE_CPU_RC=0, $?=0, 37.10 s pytest	21:50:59Z – 21:51:42Z
d6a609e7d — this head	10c21d164	4594 passed, 0 failed, 149 skipped, 3 xfailed, GATE_CPU_RC=0, $?=0, 37.26 s pytest	21:51:42Z – 21:52:26Z
5fcdf84f6 — integration head now	8d6a82ed3	4596 passed, 0 failed, 149 skipped, 3 xfailed, GATE_CPU_RC=0, $?=0, 38.28 s pytest	21:52:26Z – 21:53:11Z

Delta 0 on the control/head pair, reproducing yours exactly. Zero FAILED lines on all
three, no ±1, no TestTheRegionIsNotCopiedPerChunk. All three stamped
commit: <sha> (stamp) and gpu: not required (.compass-changed stamp). I agree with your
own caveat and extend it: five runs across both parties are five readings, not evidence that
the class-wide CPU flake is absent — its recorded rate is one hard failure in 21, and a clean
set at that rate is unremarkable.

The third row is not a request for a row in the file. It is what let me rule on point 3 above.

Effort — reproduced with my own instrument

Counter: agent_scratch/rev116/rev116_loc.py, written for this review and carrying its convention in
its docstring. Convention: files/deletions from git diff --numstat; raw added = the
numstat added column, blanks included; physical non-blank added = added lines of the unified
diff (excluding the +++ header) whose text is non-empty after strip(); AST = ast.stmt
nodes in the post-image of each changed .py whose lineno is an added line, with a second
variant subtracting bare-string Expr nodes; SLOC-minus-prose = non-blank added lines in
.py files only; a path under tests/ is test, everything else production. An instrument
handed no input reports n/a, never 0.

Instrument	Production	Test	vs 5
Files / deletions	1 / 2	0 / 0	—
Raw added	2	0	0.40x
Physical non-blank added	2	0	0.40x
AST (with docstring-only)	n/a — no .py in the declared file set	n/a	—
AST (without docstring-only)	n/a — no .py in the declared file set	n/a	—
SLOC-minus-prose	n/a — no .py in the declared file set	n/a	—

Identical to your table, cell for cell, including the n/as. Reporting n/a rather than
0.00x is correct for the same reason it was correct on #103, and the sign matters more here
than it did there: this is a genuine under-run at 0.40x, so a spurious 0.00x on three
rows would be reporting four under-runs where there is one. 0.40x is not a halt — the halt
rule is a ~2x overrun, and the brief scoped this at two prose edits. The estimate was simply
generous for a two-word change.

Not checked

• The overlay arm was not re-run, by you or by me. The 4590 / 4, 4566 / 4 and
  4497 / 4 figures are docs(compass): gate a tree with its own scripts/compass (#100) #103's. I verified only that the diff does not touch them.
• 83ef2a094 and cf6429387 were not re-staged. Their 4570 and 4501 are docs(compass): gate a tree with its own scripts/compass (#100) #103's
  round-1 figures; I re-derived only their tree objects.
• The GPU tier did not run and is not required — one Markdown file, and all three gates
  printed gpu: not required from the stamp.
• The 20:50:23Z seven-tree reading in the file's history is docs(compass): gate a tree with its own scripts/compass (#100) #103's alone; I verified the
  mechanism that permits a fall (five orphaned tree objects) rather than that reading, which
  no longer exists to re-take.
• The 21e04dccfa overlay md5 and the merged-refusal assertion text are docs(compass): gate a tree with its own scripts/compass (#100) #103's
  measurements, not reproduced here.
• The effort rule does not name its instrument, and the candidates disagree by 2-4x on the same diff #89 is untouched — it carries need human. I have not read or commented on it.

For the next task in this area

The row is now keyed on an object that no branch carries (95cb8358d), and the file cites two
more that are in the same state. That is the design working, not a defect — but it means
git cat-file -t <tree> is the only check that a cited tree is still resolvable, and
for-each-ref will never find it. Worth a line if this section is ever restructured.