tech-debt(guards): a floor comment accumulates negotiation history and conflicts on every rebase — decide the rule before writing a guard #17384

Activity

1. mrveiss

   added

   tech-debt

   on Sep 24, 2026
2. github-actions commented on Sep 24, 2026

   

   github-actionsbot

   on Sep 24, 2026 – with GitHub Actions

   Contributor

   More actions

   👋 Auto-triage could not confidently classify this issue (no confident signal). Could a maintainer add the appropriate labels (frontend, backend, infrastructure, docs, testing and good-first-issue, intermediate, advanced)?
3. mrveiss commented on Sep 24, 2026

   

   mrveiss

   on Sep 24, 2026

   OwnerAuthor

   More actions

   The worked example, found in merged main, five layers deep — and one layer is mine

   While rebasing two of my own PRs onto the 635 pin, I read the comment block above it in
   repo_tests/import_hermeticity_test.py on origin/main. It is this issue's whole argument in one
   place, so quoting rather than describing it (elisions marked):

       # four (api/analytics_cost_pricing.py, …) against 60 of allowance that main
       # had already spent 61 of, so the branch did not cause the red on its own.
       # Re-pinned 601 -> 602: measured 662 non-test modules … This branch adds exactly one
       # (autobot_shared/security/path_http.py …)
       # Re-pinned 602 -> 604 (#17305, #17306, held here for #17307/#17308):
       # measured 664 non-test modules … this branch's own new modules live under
       # llm_shared/, outside this scope, so the pin does not move again.
       # #14881 pins 635 rather than main's 604. This branch adds a module under
       # the counted roots (autobot_shared/code_review_enums.py …), and main's pin
       # is `population - growth` -- zero headroom by construction …
       #
       # NO MEASURED NUMBERS HERE, deliberately: prose citing a population survives
       # the rebase that changes it, which is how these floor files accumulated
       # several stale narratives in one night -- the resolver owns the value and
       # nothing owns the sentence. …
   

   Four stacked "this branch" narratives, then a paragraph stating the rule that forbids them. The
   rule is already written, in the same comment, directly beneath the four paragraphs that break it. It
   was added going forward and never applied backwards, so the file simultaneously documents the
   convention and violates it four times.

   Every one of those "this branch" references now points at a branch that no longer exists, and
   "main's 604" is stale in the file that is main. A reader cannot tell which paragraph describes the
   current value — the honest answer is none of them; only floor=635 and the last paragraph are true.

   One of the four is mine. The 602 -> 604 note is from my #17305/#17306 work earlier today. I
   wrote a paragraph explaining a value that two re-pins later is wrong, in a file I knew was
   conflict-prone, which is as good a demonstration as the issue needs that this is a structural
   problem and not carelessness by one author.

   What this sharpens

   • The second acceptance criterion should include this file, not just the two the git grep found:
     its narrative is the deepest, and it is the file that conflicts.
   • It answers part of the open question. A guard is not the only instrument available — the rule
     already exists as prose and was not retroactively applied, which suggests the gap is
     "nobody rewrites the paragraphs above their own", not "nobody knows the rule". A review-time
     checklist line ("if you re-pin a floor, delete the previous narrative rather than appending to
     it") would have caught all four. That is cheaper than a detector that must tell a derivation from
     a negotiation, and it fails in a visible place.
   • The mechanical piece that is tractable: a floor comment block should hold at most one
     re-pin narrative. Counting paragraphs that begin "Re-pinned"/"pins N rather than" is a keyword
     list — but counting how many distinct floor values a comment block mentions is not, and this
     block mentions 601, 602, 604, 635 and 662/664 populations. One value in the comment, one value in
     the declaration; anything else is history. Worth testing whether that formulation survives contact
     with the legitimate cases before it becomes a guard.
4. mrveiss commented on Sep 24, 2026

   

   mrveiss

   on Sep 24, 2026

   OwnerAuthor

   More actions

   A mechanical rule that is decidable, with a measured baseline

   The issue records that matching negotiation phrasings ("proposed", "adopted", "re-pinned") is a keyword list the next author phrases around. Agreed. But there is a countable property that does not need to read prose at all:

   A floor comment should mention one floor value — the current one. Every other value in it is history.

   Counting distinct numbers in comments is too crude on its own: it catches issue references, years, and legitimate arithmetic. Restricting to numbers in the floor's own magnitude and stripping #NNNN refs makes it a clean signal. Measured on merged main:

   file	declared floor	in-range values in comments
   repo_tests/hooks_path_override_15961_test.py	6736	52
   autobot-backend/security/prompt_injection_detector_strict_mode_test.py	3100	29
   repo_tests/audio_extension_allowlist_test.py	5764	15
   repo_tests/import_hermeticity_test.py	635	11

   import_hermeticity_test.py in full: 504 556 600 601 602 604 608 635 661 662 664. Eleven values, one of which is true.

   Method, so it can be re-derived rather than trusted:

   body=$(git show origin/main:<file>)
   dec=$(echo "$body" | grep -oE "floor=[0-9]+" | head -1 | cut -d= -f2)
   echo "$body" | grep -E "^\s*#" | sed 's/#[0-9]\{4,5\}//g' \
     | grep -oE "\b[0-9]{2,6}\b" | sort -un \
     | awk -v l=$((dec/2)) -v h=$((dec*3/2)) '$1>=l && $1<=h'
   

   Two known leaks, both small and fixable: years (2025, 2026) fall inside the range for the 3100 floor, and a comment doing legitimate arithmetic ("population 6952, slack 216") contributes operands. Neither changes the ranking, and both are narrower problems than reading prose.

   Why this is worth more than the count

   The rule it enforces is checkable by a human in one glance and by a script in four lines: one value in the comment, one in the declaration. It does not need to distinguish a derivation from a negotiation, which is the distinction the issue correctly says cannot be drawn mechanically. It sidesteps that question entirely by noticing that both kinds of stale prose share one observable — they carry a number that is no longer the floor.

   The worked example, verified

   import_hermeticity_test.py on main carries stacked per-branch narratives and, directly beneath them, the paragraph stating the rule that forbids them. The rule was written going forward and never applied backwards.

   That suggests the gap is "nobody rewrites the paragraphs above their own" rather than "nobody knows the rule" — which is worth knowing before choosing a remedy, because it means a review-checklist line would have caught every instance, and is cheaper than any detector.
5. mrveiss commented on Sep 24, 2026

   

   mrveiss

   on Sep 24, 2026

   OwnerAuthor

   More actions

   Correction to my own count, with the method this time

   My comment above said the block carries "four stacked this branch narratives". That number is not
   reproducible as stated, which on this issue of all issues is the wrong way to write a figure. It
   conflated the UNIT (narrative) with the PHRASE (this branch), and it named no window.

   Measured, so it can be re-run:

   $ git show origin/main:repo_tests/import_hermeticity_test.py | sed -n '100,182p' > block.txt
   
   $ grep -c -i -E "^\s*#\s*(Re-pinned|#[0-9]+ pins)" block.txt
   4        # re-pin narrative openers: 600->601 (#16230), 601->602, 602->604 (#17305/#17306), "#14881 pins 635"
   
   $ grep -o -i "this branch" block.txt | wc -l
   5        # the phrase itself
   
   $ grep -o -i "the branch" block.txt | wc -l
   1
   

   So: four narrative blocks, five occurrences of the phrase, one window — sed -n '100,182p', the
   comment block above the declaration. A count of 2 is what my own elided quotation contains, not
   what the file contains, and quoting with elisions and then counting the quote is how the second
   number appears.

   The disagreement is more useful than either figure. Two readers measured the same file, both
   honestly, and got 2, 4 and 5 depending on the unit and the window — which is precisely why
   the value-counting criterion is the better instrument than any count of prose. A floor
   value is unambiguous: it either equals the declaration or it is history. There is no window to
   choose and no unit to conflate.

   Adopting the measurement from the comment below this one as the issue's own number, since it carries
   its method: eleven in-range values in this file against a declared 635, and fifty-two in
   hooks_path_override_15961_test.py against 6736 — on the file that conflicted four times in a day.
6. mrveiss commented on Sep 24, 2026

   

   mrveiss

   on Sep 24, 2026

   OwnerAuthor

   More actions

   Correcting my correction: it was CASE, not elision — and the bias runs one way

   My comment above explained the disagreement as "one reader counted the elided quotation". That is
   wrong, and I am replacing it rather than leaving it, because the real cause is a stronger argument
   for this issue's instrument than the one I gave.

   Both readers ran their count against the same file, origin/main:repo_tests/import_hermeticity_test.py.
   Four methods, one file, one moment:

   $ f=import_hermeticity_test.py    # git show origin/main:repo_tests/...
   
   grep -c   "this branch" $f          LINES,   case-sensitive    -> 2
   grep -o   "this branch" $f | wc -l  MATCHES, case-sensitive    -> 2
   grep -oi  "this branch" $f | wc -l  MATCHES, case-insensitive  -> 5
   grep -ci  "this branch" $f          LINES,   case-insensitive  -> 4
   

   The entire 2.5x gap is the case flag. And the three matches a case-sensitive count misses are
   capitalised — This branch — because they start sentences:

   $ grep -oin "th[ei]s* branch" $f
   149:this branch
   149:This branch     <- same line, different case
   152:the branch
   155:This branch
   162:this branch
   165:This branch
   

   A narrative begins at a sentence start, so the capitalised occurrences are the openers. A
   case-sensitive count is not merely differently calibrated — it is biased against the feature being
   measured, and it would be wrong in the same direction on any file. That is the same defect class as
   a scanner that reads one spelling of a thing spelled several ways, which is what three separate
   guards were widened for this week.

   Line 149 also happens to carry two occurrences, so grep -c's line-counting would have reported 1
   where there are 2 — a second latent hazard on the same line, masked here because only one of the two
   matched case-sensitively.

   For completeness: my own 4 was a third unit again — grep -c -i -E "^\s*#\s*(Re-pinned|#[0-9]+ pins)",
   narrative openers by their own pattern. It equals grep -ci by coincidence on this file, not by
   agreement, and reading it as corroboration would be the third version of this mistake.

   Why this strengthens the criterion

   Three honest readers, one file, answers of 2, 4 and 5 — from three degrees of freedom: unit
   (lines vs matches), window (whole file vs quoted excerpt vs comment block), and case, with
   case silently correlated with what was being counted.

   A floor value has none of them. 635 has no plural, no capitalisation, no sentence position, no
   synonym, and no window worth arguing about: it either equals the declaration or it is history. Every
   degree of freedom that produced our three answers is absent from the thing this issue proposes
   measuring, which is the argument for it — not that prose is hard to read, but that prose has
   parameters and a number does not.
7. mrveiss

   added 3 commits that reference this issue on Sep 24, 2026

   chore(guards): re-pin the tracked-file floor mid-window (#17126, #17090)

   ...

   4f2f387

   feat(agents): verify an issue's acceptance criteria against merged ma…

   ...

   b92b80e

   fix(ci): a skipped smoke-test must not satisfy the required context (#…

   ...

   dc76db3