rate-limit-guard: reader-contract overstates the tee's forward-pass upgrade path

[kyle-sexton]

What

plugins/rate-limit-guard/reference/reader-contract.md draws a conclusion from
the writer's forward-pass filter that is broader than the filter supports.

The description of the filter is accurate. The inference from it is not.

Evidence

reference/reader-contract.md (in the loop-lane single-account gap bullet):

Locally relevant today: the writer already forward-passes any top-level key
matching account, so an identity field costs no plugin change the release
one appears.

scripts/statusline-tee.sh — the filter itself:

+ (to_entries
   | map(select(.key == "rate_limits" or .key == "session_id"
                or .key == "session_name" or (.key | test("account"; "i"))))
   | from_entries)

to_entries is applied to the root object only, and the pattern matches the
literal substring account, case-insensitively. So the first clause is exactly
right.

The second clause is the problem: "an identity field costs no plugin change"
holds only if the field upstream eventually ships is both top-level and
account-named. A field called user, identity, org, subscription, or
seat, or one nested under an object (user.account_uuid), is silently
dropped — and silently, because the filter has no else branch.

The doc therefore promises a no-change upgrade path the code cannot guarantee,
in a contract that fail-closes on every other unresolvable input.

Why it matters

This sentence is load-bearing for the account-identity design in #1218. Anyone
planning that work reads it as "the writer is already ready" and skips checking
the filter. It is also the kind of claim that ages badly: it will read as true
right up until the release where it silently is not.

Resolution shapes

1. Narrow the claim to what the filter does. Say the field costs no plugin
   change if it is top-level and account-named, and that any other shape
   needs a filter change. Documentation-only, mechanical, trivially reversible.
2. Widen the filter to match the claim. Recurse, or match a wider set of
   identity-ish key names. Behavioral change to a shipped script, needs its own
   test coverage, and risks forward-passing fields nobody intended.

Shape 1 is the smaller and safer correction, and it is the one that makes the
document honest immediately. Shape 2 is a design question that belongs with
#1218 rather than with this correction, since #1218's recommended field is
deliberately named to satisfy the existing filter.

Related

• Found while researching the account-identity buildability question for rate-limit-guard: same-machine account rotation is real operation — tee file's single-account assumption feeds wrong windows to running lanes (account-identity design) #1218.
• plugins/rate-limit-guard/reference/reader-contract.md
• plugins/rate-limit-guard/scripts/statusline-tee.sh

No linked issue.

[kyle-sexton]

This was generated by AI (triage lane, gate-audit pass — cycle 2 retry, instance melo-lap-001-triage-20260727T125559Z).

Verdict: real, and the only fully-specified item in this batch — marked agent-ready.

The issue quotes both the doc sentence and the exact jq filter it overstates, and the judgment call is already made in the text: shape 1 (narrow the claim to top-level, account-named fields) is chosen, shape 2 (widen the filter) is explicitly deferred to #1218. What remains is a prose correction to one bullet in plugins/rate-limit-guard/reference/reader-contract.md — deterministic and trivially reversible, hence work-class: mechanical. No script behavior changes, so this does not touch the security floor.

Scope guard for whoever picks this up: do NOT touch scripts/statusline-tee.sh; widening the filter is #1218's call.

Labels: priority: low, work-class: mechanical, agent-ready (removed priority: needs-triage).

[kyle-sexton]

[kyle-sexton]

This was generated by AI (autonomous worker lane, instance MELO-LAP-001-worker-202607290351).

Handoff: PR #1734 opened, Closes #1685.

Took shape 1 as the issue and triage both chose. scripts/statusline-tee.sh's behavior is unchanged — the jq filter is byte-identical to main; only its header comment moved.

The overstatement was on four surfaces, not the one quoted here. Correcting only the Invariants bullet would have shipped a reader contract contradicting its own Tee-file-shape section, and would have left a broader, fully unqualified form of the claim on README.md — the plugin's front door, and a path a #1218 planner is at least as likely to read:

• reference/reader-contract.md "Tee file shape" — now owns the rule
• reference/reader-contract.md "Invariants" — the bullet quoted above; scoped, and now points at the rule instead of restating it
• README.md known-gap bullet — "The wrapper automatically adopts any future account-identifying field the schema grows"
• scripts/statusline-tee.sh header comment — qualifiers were in the parenthetical, but the so … inference dropped them

One correction this issue did not anticipate. The evidence above frames user.account_uuid as "nested, therefore dropped". That reasoning is inverted. Selection is on the top-level key name alone, and a selected key crosses with its whole value, nested objects included — account_info: {uuid, display_name} arrives complete. The drop is caused by nothing at the top level matching, not by depth. Because a passed key may therefore carry an object of arbitrary user/AI-influenced strings, the contract's untrusted-value discipline now covers the subtree rather than a scalar.

Two phrasings from this issue's body did not survive contact with the code and were left out:

• "the filter has no else branch" — map(select(…)) has no branch to lack an else. The accurate statement is that unmatched keys are dropped with no diagnostic, which is the substance either way.
• "That is the whole of the writer's filter" (an early draft) — untrue; the filter also selects rate_limits.

One claim in this issue is unverified and was deliberately kept out of the fix. The Resolution-shapes section states that "#1218's recommended field is deliberately named to satisfy the existing filter." #1218 specifies no field name — only "an account-identity field in the tee shape". The PR therefore makes no claim about whether #1218's eventual field will satisfy the filter. Worth correcting on #1218's side if a name has since been chosen somewhere I did not find.

Verification, honestly: doc-only prose with no executable surface. No test can reach this claim and none was invented. Verification is the read of the filter against the new prose plus the repo's full gate set (changelog parity + bump, catalog sync, plugin/contract validation, cross-plugin drift, shell portability, shellcheck, markdownlint) — all green, enumerated in the PR body.

Independent review ran fresh-context with rationale withheld and found the first pass incomplete; three IMPORTANT findings (the two unfixed surfaces, the nesting inversion, and a changelog that misdescribed what shipped) are all addressed in the PR as opened.

Merge-lane note: the PR bumps this plugin to 0.3.5, which PR #1692 also claims. Whichever merges second must rebase and re-bump; check-changelog-parity.sh --check-bump will red-line the loser until it does.