gate: correct the ratchet's own rationale to match its message

[iceteaSA]

Cubic caught this on #48 after it merged, and the finding is right.

#48 fixed the refusal message and left the doc comment above assert_floor_not_lowered still asserting the mechanism the message now refutes. So the function contained both:

comment (line 258):  "a branch forked before a raise carries the OLD number
                      forward in this file and merges green"
message (line 296):  "a squash does NOT carry a stale floor onto master"

A reader debugging a gate failure gets two mutually exclusive explanations from one function. That is worse than the original error was: a lone wrong explanation is simply wrong, but a contradiction reads as though one side is a subtlety you have not understood yet, and the natural move is to trust the comment because it is longer and looks considered.

What the comment now says

The same construction I ran for #46, in the file rather than only in a PR thread:

squash stale(610) onto master(616)   ->  floor 616, gate.sh not even staged
fork-before-raise, edits the floor   ->  UU scripts/gate.sh, conflict marker

Plus what it actually catches — a --ours conflict resolution, and a hand-edit downward — and why both are invisible in review: the gate passes either way, so there is no red to notice.

I also kept the correction visible rather than silently rewriting history. The comment states that it asserted the obvious mechanism until 2026-09-17, because the next person to reason about this will reach for the same wrong model I did, and knowing it was already tried and refuted is the part that saves them the afternoon.

Scope

One comment block, no behaviour change. Gate green, workspace floor 621 >= origin/master 621 at e97bc73.

Grepped for surviving instances of the refuted claim — the only hit is the new line stating its negation.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Summary by cubic

Corrects the doc comment above assert_floor_not_lowered in scripts/gate.sh to match the actual mechanism. The old comment claimed a fork before a raise carries the stale floor forward, but a squash applies the diff, so the raise survives; the comment now explains what the guard really catches (conflict resolution or hand-edit downward) and notes that the previous assertion was wrong until 2026-09-17.

^{Written for commit 26e6c37. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 1 file

_{You’re at about 95% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/gate.sh">

<violation number="1" location="scripts/gate.sh:274">
P3: The comment claims the ratchet catches "a plain hand-edit downward, on a branch or on master," but the guard compares this tree's floor against the target's `gate.sh` (`ours -lt theirs`). Once a lowering is committed on the target itself (e.g., pushed directly to `origin/master`), `ours == theirs` and the comparison passes, so master-side edits are invisible to this guard. Restrict the claim to branch-side edits (the tree under test vs. a target that still carries the higher floor) so the comment doesn't promise coverage the implementation cannot provide.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The comment claims the ratchet catches "a plain hand-edit downward, on a branch or on master," but the guard compares this tree's floor against the target's gate.sh (ours -lt theirs). Once a lowering is committed on the target itself (e.g., pushed directly to origin/master), ours == theirs and the comparison passes, so master-side edits are invisible to this guard. Restrict the claim to branch-side edits (the tree under test vs. a target that still carries the higher floor) so the comment doesn't promise coverage the implementation cannot provide.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/gate.sh, line 274:

<comment>The comment claims the ratchet catches "a plain hand-edit downward, on a branch or on master," but the guard compares this tree's floor against the target's `gate.sh` (`ours -lt theirs`). Once a lowering is committed on the target itself (e.g., pushed directly to `origin/master`), `ours == theirs` and the comparison passes, so master-side edits are invisible to this guard. Restrict the claim to branch-side edits (the tree under test vs. a target that still carries the higher floor) so the comment doesn't promise coverage the implementation cannot provide.</comment>

<file context>
@@ -255,13 +255,24 @@ stream and pass the arm without ever seeing it skip."
+#
+# What it catches is a HUMAN RESOLVING THAT CONFLICT by keeping their own side -- which
+# happened on this repo an hour before the ratchet landed, resolved by hand -- and a plain
+# hand-edit downward, on a branch or on master. Both are invisible in review for the same
+# reason: the gate passes either way, so there is no red to notice.
 #
</file context>

Suggested change

	# hand-edit downward, on a branch or on master. Both are invisible in review for the same
	# hand-edit downward on a branch, while the target still carries the higher floor. Both are invisible in review for the same