Repository navigation
docs(inflight): triage ten untriaged upstream mirrors, give the fork's branches one validated accounting, and index every issue so grep reaches the tracker - #327
Merged
Conversation
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
✅ Duplicate Code ReportTwo engines run in parallel for cross-validation. Each has its own thresholds tuned to its baseline - the real safety net is the per-engine "max increase vs base" check. ✅ PMD CPD
No new clones introduced by this PR. ✅ jscpd (language-agnostic)
No new clones introduced by this PR. Powered by astubbs/duplicate-code-cross-check |
|
🧪🔒 Quarantine Lane Report
🔴 expected while the owner PR is open · 🟡🎲 flapper, pass proves nothing · 🚨 a deterministic quarantined test passing means its fix landed: delete its |
astubbs
changed the title
astubbs
changed the title
astubbs
marked this pull request as ready for review
August 26, 2026 01:25
astubbs
force-pushed
the
docs/triage-untriaged-mirror-issues
branch
from
August 26, 2026 01:52
6cbd160 to
a926d98
Compare
astubbs
changed the title
Owner
Author
|
@claude review this Context and where to look hardest. The dispatched route was tried first and returned This branch's whole thesis is that records read as verified when they are not - and it has
Known and deliberate, so not findings unless you disagree with the reasoning: no GitHub |
|
Claude finished @astubbs's task in 10m 6s —— View job Review completeTreated the PR as unreviewed per the trigger's context (dispatched route returned nothing). HEAD confirmed at Todo
Applying the hardest lens the trigger asked for — claim verification — turned up real instances of the exact defect this PR's own thesis names, still present in this PR's new content. Findings below, most-severe first. 1. The
|
astubbs
changed the title
astubbs
force-pushed
the
docs/triage-untriaged-mirror-issues
branch
from
August 26, 2026 08:09
33e6b28 to
c81b542
Compare
…e records that were wrong Ten open `upstream-mirror` issues had never been assessed against this tree. They turned out not to be untriaged: each carries a `## Fork status` section written when it was mirrored, and THAT SECTION - not upstream-map.yaml, not upstream-pr-analysis.adoc - is where the fork's only judgement about most upstream issues lives. Searching the two documents came up thin for exactly that reason. Most had drifted, and the errors were the load-bearing kind. #241 restates an account of `commitOffsets` that confluentinc#355 falsified in 2022. #163 calls the poll path unguarded when a typed per-exception seam already exists, so the fix is far cheaper than recorded. #161 says the scheduler moves the user function off the control thread; it was never on it, which changes the answer to the reporter's question. #173 contradicts our own README on what the transactional mode guarantees. #175 credits the wrong PR and omits the close-path failure the reporter called the bigger problem. #162 misses that reporters hit the same warning AFTER the fix shipped, which is the fact deciding whether it can close. WHY THEY GOT THAT WAY is recorded at population level in `upstream-mirror-bodies-are-stale.md`, because the causes are structural and will recur: a tree-wide rename invalidated every `file:line` citation in every body in one commit, silently - one had been wrong since the day it was written, naming a method declaration rather than the statement it claimed. Nothing re-checks a body once written, unlike a map entry with its `last_checked`. And nothing in the format separates a verified claim from an inferred one, which is where every failure above sits. THREE VERDICTS ARE REFUTED, not softened, because each would have caused a wrong action. The worst: "merging confluentinc#893 + confluentinc#909 likely resolves confluentinc#777". Left standing, that closes confluentinc#777 the moment the cherry-pick merges - when upstream's own maintainer answered it in 2024, before either PR existed, saying the redelivery is expected at-least-once behaviour. EVERY CLAIM HERE WAS RE-VERIFIED AGAINST HEAD, after a review found several that read as checked and were not. Two citation anchors returned nothing when grepped - one a fabricated quotation around a fair paraphrase, one a `grep` instruction naming a string absent from the file it pointed at. A `RetryQueue` assertion was TRUE WHEN WRITTEN and falsified hours later by this branch's own master merge, so it now records the defect as fixed and names where the stale wording survives. And the confluentinc#893 cherry-pick had already moved from #57 to #337 before these notes were written, which three places still got wrong - including the manifest entry, corrected here. NOTE NAMES NOW CARRY THE FORK ISSUE NUMBER. A fifth of this directory already carried one and the existing names disagree about what it means - `bug-857-family` is a confluentinc number, `perf-192-followups` a fork one. That is the coin flip docs/issue-references.md exists to prevent, with none of the protection, because a filename cannot be qualified. The three notes first added here as `upstream-543`, `upstream-777` and `upstream-809` were the sharpest case: all three numbers also exist as fork issues meaning other things. The Renovate note lands here rather than on its own, because it is a triage finding with the same shape as the rest: the case FOR switching did not survive opening `.github/dependabot.yml`, which already carries the scoped ignores and the grouping the argument asked for. Kept for its counter-evidence, so the idea meets it rather than being re-derived. No issue has been touched - every correction and reporter-facing answer is drafted in its note and left unposted, pending a maintainer's decision on each. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
… 109 have no account Triggered by `origin/presentation`, which carries the code behind the asciinema cast embedded in the README - unmerged since 2021 and named in no ledger. THE TRANSFERABLE PART IS THE MECHANISM, not the number. Four inventories exist and three were correctly scoped to something that structurally excluded the branch. The fourth is the near miss: docs/upstream.md carries an entry titled "Orphan branches never attached to a PR" - the right check pointed at the wrong remote. It swept `upstream`; the branch exists only on `origin`. That reads as covering orphan branches generally while covering five branches on one of two remotes, which is worse than not looking, because it closes the question. The common shape: every audit was seeded from a list of interesting things and worked outward; none started from the complete set of refs and worked inward. Read the finding as "109 branches nobody has an account for", NOT "109 lost treasures" - most will be junk. What is not junk is that nothing distinguishes the junk from `presentation` today. THE OTHER REMOTE HAS THE SAME HOLE, and it is not ours to lose. 34 of upstream's branches existed on no branch of this fork. The tempting reading is that we deleted them; tested and REFUTED, because for 33 of the 34 every commit on the branch postdates this fork's creation, so they cannot have been ours to delete. The one exception, `features/dynamic-concurrency-control`, we do have - our copy diverged under our own work. The mechanism is invisible and permanent: A FORK RECEIVES BRANCHES ONCE, WHEN IT IS CREATED, AND NEVER AGAIN. This fork dates from 2020-11-11; upstream went on creating branches for years afterwards and not one of them arrives. The older the fork, the wider the gap, and nothing reports it. All are now mirrored here under `upstream/*`, tips verified identical. The namespace is load-bearing rather than tidy: eight share a name with one of ours carrying divergent work - including `master` - so pushing under their own names would have overwritten our history. Upstream is unmaintained, so this is the difference between that work being preserved somewhere we control and depending on a repository nobody maintains. `pyallel-consumer` is the immediate value: a prior Python client, prior art in the strongest sense, while a Python client is being written on `feats/proxy-requirements`. A CITATION HERE NAMED A FILE THAT HAS NEVER EXISTED. An earlier revision cited `branch-language-proxy.md` as where that client is being built; `git log --diff-filter=D --all` finds no deletion, because there was nothing to delete. It was a plausible filename written from an adjacent fact - the same defect class this branch exists to document, committed while documenting it. The wording now names the branch and its PRs, which a reader can check. `handoff-fork-branch-audit.md` carries the method and the failed approaches; the archaeology note is renamed off the retired `next-` prefix onto `process-`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…branch `upstream-map.yaml` gains a `branch_accounting` section keyed by ref. It records what we DECIDED about a branch, not what it currently is. The failure it prevents is specific: a branch is reviewed, judged worthless and deleted, its only trace was itself, and the next audit re-finds the absence, cannot tell a deliberate deletion from an accident, and redoes the work. So `state: deleted` keeps its entry, with tip, date and reason. IT REPLACES THREE OVERLAPPING RECORDS THAT HELD THE SAME COMMITS under different framings. `preserved_branch_tips` recorded branch tips pinned as tags; `sweep-2023-admin-closure.preserved_heads` recorded swept PR heads pinned as tags. Every one of those PR heads is the tip of an upstream branch - confluentinc#443 and the `pyallel-consumer` tip turned out to be two names for 4533f6d. Tag and PR are now fields on the branch entry rather than separate registers. That is the point of consolidating rather than adding a fourth: a corrected SHA fixed in one copy while another still reads as authoritative is exactly the drift that produced this branch's other findings. The tags themselves are KEPT alongside the mirrored branches rather than replaced by them. A branch can be deleted or force-moved; an annotated tag is the record that a specific commit was deliberately preserved. Verify without fetching: `git ls-remote --tags origin 'archive/*'`. THE RULE IN ITS HEADER IS WHAT STOPS IT ROTTING: nothing a command answers. Open PRs are `gh pr list`; merged-ness is `git branch --merged`; a live branch's tip is `git rev-parse`. It records the judgement, not the state - which is why a tip is recorded for branches that are gone and not demanded for ones that are not. docs/upstream.md's two pointers at the retired registers are repointed here, and the tag section is marked superseded by the mirror rather than deleted, since the tags still exist and the reasoning for them still holds. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
First use of the record added in the previous commit, and the reason it is a record rather than an absence: 17 of the branches mirrored from upstream were dependency-bot branches, deleted the same day once their contents were checked. Each keeps its entry with its tip, so a future audit can tell a deliberate deletion from an accident without redoing the work. Sixteen were one commit touching one `pom.xml`, bumping a dependency of UPSTREAM's tree - which has diverged from ours in both dependency set and package paths, so they would not apply here and will never merge upstream either. Not tagged, so upstream's copy is the last one; accepted, because a recreatable version bump is not work. THE SEVENTEENTH WAS NOT A BOT BRANCH AT ALL. A maintainer had pushed four commits onto `dependabot/maven/org.threeten-threeten-extra-1.8.0`: a semaphore CI java-home fix, missing licence headers, a `.gitignore` change, and a master merge. It was read before deletion and given its own entry saying so - none of it applies here, since the CI config is upstream's semaphore and the licence headers are on `io/confluent` paths this fork has renamed. A SWEEP KEYED ON `dependabot/*` WOULD HAVE TAKEN THOSE HUMAN COMMITS SILENTLY. That is the same failure as the stale mirror bodies this branch documents - a name trusted in place of the contents - and it is why each branch kept its own row rather than being collapsed into one aggregate `dependabot/*` entry. A glob in `ref` would also defeat the ref-matching this section exists to feed. Our own `dependabot/*` branch is deliberately untouched: it heads #38, and deleting it would have closed that PR. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This PR added a `branch_accounting` section to a manifest that has a validator, and left it outside the validator. Worse than untested: `upstream-map.py validate` reads only `entries`, so injecting `state: TYPO_NOT_A_STATE` still printed `OK: 39 entries, no schema errors` - a reassuring count of the section it HAD looked at. A gate reporting success about something it never inspected is the failure class this repo keeps rediscovering, so the success line now names both sections and their counts. THE VALIDATOR WAS ALSO RUN BY NOBODY. No workflow, no gate, no hook invoked it - only `upstream-sweep.sh` referenced the script at all, for other subcommands. So fixing the schema check without giving it a caller would have fixed nothing. `bin/check-upstream-map.sh` is that caller, and because `check-all.sh` discovers gates by glob, it needed no registration anywhere: the local sweep went from 38 to 40 with no edit to any workflow. Verified it will actually RUN in CI rather than skip - `check-docs-data.sh` shares the PyYAML dependency and the last hygiene run reports it `ok` with `0 could not run`, so the interpreter is present. WHAT THE NEW CHECK IMMEDIATELY FOUND, and why the first rule was wrong. It failed two entries for having no `tip`. The data was right and the rule was not: both are `state: ours`, live branches whose SHA is one `git rev-parse` away, and this section's governing rule is "nothing a command answers" - so demanding a tip there would have contradicted the schema it validates. A tip is now required only for `deleted` and `archived`, where nothing else can recover it. The self-test carries both halves of that pair, because the same omission being a finding in one state and legitimate in the other IS the rule. RED CONTROLS, RUN NOT ASSUMED. Every negative arm was executed against the pre-change validator and observed to pass wrongly - all four print `OK: 39 entries` and exit 0, including the integer-tip case that bit for real in review (`tip: 2559166` is all digits, so YAML makes it an int and it never compares equal to `git rev-parse` output). A regression test that has never failed proves nothing. The gate exits 2, never 0, when it cannot run, and distinguishes "manifest is invalid" from "the validator itself blew up" - otherwise a broken script and a broken file are indistinguishable, and the skip reads as a pass. BOTH HALVES OF THE TIP RULE ARE EXERCISED, after a review pointed out that only one was. The rule requires a tip for `deleted` AND `archived`; the self-test covered `deleted`, and the manifest has no archived entry, so narrowing the tuple back to `("deleted",)` would have been caught by nothing - data or test. Two arms added, and the regression injected to confirm the negative one goes red against it rather than passing for its own reasons. Caught by the repo's own rules while writing it: the first draft used `printf | grep -q`, which takes EPIPE under `pipefail` and turns a MATCH into a failure. `bin/AGENTS.md` forbids it and `check-shell-sigpipe.sh` enforces it; replaced with a herestring. `docs/upstream.md` said the fork side is checked by nothing. That claim survives and is deliberately kept - the gate checks the SHAPE of an entry, never whether its claims are true - but the sentence implied the schema check was unrun, which is no longer so. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
… tracker `gh issue list --state all` is, by the root AGENTS.md's own admission, the most skipped of the six prior-art checks. The reason is structural rather than laziness: an agent has to THINK of querying GitHub before it can do it, and it greps by reflex. So the tracker was the one knowledge surface a keyword sweep of `docs/` could not reach. One line per issue - number, state, title, labels - regenerated by `bin/issue-index.sh`. An agent working on offset encoding now finds #237 without having formed the intent to look for it. IT BREAKS "NEVER WRITE DOWN WHAT A COMMAND CAN ANSWER", DELIBERATELY, and the distinction is worth stating because the next reader will and should challenge it. That rule exists to stop a SECOND TRACKER forming: a copy that gets believed, drifts, and cannot be told apart from the truth. This one is not built to be believed. It carries the date the data was read, says twice that every row goes stale silently, and sends you to `gh issue view` before acting on any of them. The precedent is already in the repository - `.claude/hooks/inject-recorded-knowledge.sh` injects the TITLES of every `docs/solutions/` write-up at session start for exactly this reason, and says so: "these are the titles, so you know what exists; grep the ones that look close." WHY THERE IS NO `--check` GATE, unlike `bin/todo-index.sh`. That script regenerates from the tracked tree, so staleness is decidable offline and a gate is free. This one cannot be: deciding whether the index still matches reality means asking GitHub, which needs the network and a token. Such a gate is skipped for fork PRs and dies on a token expiry - precisely the failure `bin/check-cve-exclusions.sh`'s header describes, where an unwatched list rots exactly when its guard cannot run. Staleness is therefore handled by SAYING so, with a date, rather than by a check that reports "could not run" and gets read as a pass. IT EARNED ITS KEEP BEFORE MERGING. Within minutes of the first generation, #41 stood out as labelled `wontfix` while OPEN with `stateReason=REOPENED` - closed as wontfix once, reopened, and the label never removed. The label was wrong, not the issue; it is removed and the row regenerated. Nobody was going to find a stale label on a two-year-old issue by reading the tracker. It is also the worked example for why this is a discovery aid and not state: the label alone gave the wrong answer, and only the state column beside it revealed the contradiction. THE TAGS AND THE `issue-refs` OPT-OUT ARE BOTH EMITTED BY THE GENERATOR, not added to the file. The file is rewritten wholesale, so a hand-added `inflight-type` would be dropped by the next run and `check-inflight-tags.sh` would fail on a file nobody remembered editing. Type `register`, because the index is consulted and never completed - it has no done state. Every row is a bare `#NN`, so `bin/check-issue-refs.sh` correctly reads the file as 122 unqualified references - the rule exists because this fork's numbers sit inside confluentinc's range. Qualifying every row would be noise, so the header qualifies them once and the file takes the `exempt-file` opt-out the gate documents for exactly this case. Worth recording HOW that was found: the gate passed a local sweep while the file was still untracked, because it enumerates via `git diff --name-only`. Fifteen gates reported green having never looked at it - the same defect this branch documents elsewhere, biting one commit after being written down. `docs/inflight/AGENTS.md` says "No committed index", and that rule now says what it always meant: no index OF THESE NOTES, because such a file would be edited by every PR. An index of ISSUES is not that - nothing edits it but a deliberate regeneration - and the carve-out names this file so it is not deleted on sight by an agent correctly citing the rule. The script is NOT named `check-*`: that prefix grants a script to the review agent by pattern, and the grant is for read-only tree gates. This one reaches the network. Two guards worth having: it refuses to write an empty index if the query returns nothing, so a failed or rate-limited call cannot silently blank the file, and it passes `-R astubbs/parallel-consumer` explicitly, because a bare `gh` here resolves to confluentinc and an index quietly built from upstream's issues would be worse than none - the number ranges overlap, so every row would look plausible. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Nothing else asks it. The tracker is not in the diff, so a PR that finishes an issue without saying so leaves it open for someone to rediscover, and the checklist had no line covering that. THE HALF THAT MATTERS IS THE PARTIAL CASE, because closing on a partial fix is where the damage is - the remaining work goes with it. #41 is the worked example and the reason this rule exists: its reopening comment lists four remaining items, #366 did the first, and "366 closes 41" was a reasonable-sounding read that would have taken the other three - widening the mutation target, verifying excludedGroups, and the licence-blocked history plugin - with it. That issue also shows the second half: #366 did item one AGAINST the issue's stated preference, refuting "prefer push-on-master over a cron" with a measurement of this repo's actual merge rate. The recommendation lives on the issue and the evidence does not, so the disagreement has to be recorded there or the next reader re-derives it. The closing keyword needs the fully qualified form - Fixes #167 closes nothing - which docs/issue-references.md already owns and this only points at. docs/inflight/issue-index.md, added in this PR, is what makes the check cheap: grep it for the area the PR touches. The rule names its staleness in the same breath, because an index that gets treated as state is the failure it was written to avoid. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
astubbs
force-pushed
the
docs/triage-untriaged-mirror-issues
branch
from
August 26, 2026 08:23
46a70b4 to
53e6442
Compare
5 tasks done
astubbs
added a commit
that referenced
this pull request
Aug 26, 2026
…rows
Archiving `presentation` in the previous commit turned `test-check-upstream-map.sh`
red. Three arms anchored on the literal text `- {ref: presentation, state: ours,`,
which stopped existing the moment that row became `state: deleted` - so an ordinary,
correct manifest edit failed the test that guards the manifest.
IT FAILED AS "fixture anchor not found", which reads like a broken test rather than
a moved row, and sends the next person looking in the wrong place entirely.
EVERY NEGATIVE ARM NOW INSERTS ITS OWN ROW. A new `row:` mutation mode prepends a
synthetic entry to `branch_accounting`, so each arm depends on nothing but the
schema it is testing. Archiving a branch, retiring one or adding one cannot turn
them red again. Two arms keep the replace form deliberately: the unparseable case
corrupts the FILE rather than an entry, and has to.
Coverage went up rather than sideways while converting: `missing ref is rejected`
had no arm at all, and both terminal states now have the tip-required pair, so a
regression to just `("deleted",)` is caught - verified by injecting it and watching
only that arm go red.
WHY IT REACHED CI AT ALL, which is the more useful half. `bin/check-all.sh` runs
`check-*.sh`; the self-tests are `test-*.sh` and need `--with-tests`, which is what
the `repo: hygiene` job runs. So a local sweep reporting "15 ran, 15 passed" never
executed this file, and read as complete. The gate that would have caught it exists
and I did not run it - the same shape as the untracked-file miss recorded on
#327, one commit later and from the other direction.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
astubbs
added a commit
that referenced
this pull request
Aug 26, 2026
…k-plus-cherrypicks 51 commits, the branch's first master merge since the 2026-08-24 re-cut. Six conflicts; three were deletions master had already justified, three are decisions. **`scripts/upstream-map.py` - both sides added a different check, so both are kept.** This branch added the one that refuses `fork.status: pr-open` with an empty `fork.prs`, because `check-upstream-map-merged.sh` matches on the PR NUMBER and cannot fire on an entry that names none. Master (`12fdacbb6`) added `validate_branches`, because `branch_accounting` arrived in #327 outside the validator and a bogus `state` passed while the run printed a reassuring count of the section it HAD looked at. Neither supersedes the other - one guards an entry, one guards a section that was not being read at all. **`upstream-map.yaml`, the confluentinc#893 entry.** Both sides now say `prs: [337]`; this branch's version additionally carries `fork_issue: 121` and names the owning branch first, so it wins. Its `notes` still said "`prs:` is empty until that PR is opened" - true when the split happened, false since #337 opened - so that sentence now says what to do next instead: set `status: merged` in that branch before merging it. **`bug-857-family.md`: master's numbering is authoritative, and two of this branch's entries turned out to be duplicates under different ordinals.** Master and this branch had both grown the ledger since the recut. Two entries are byte-identical bodies under different headings - this branch's fourteenth and fifteenth ARE master's twelfth and thirteenth - so they take master's numbers, which are the ones cited by ordinal from `test-no-progress-window-may-not-transfer-to-w1.md`, `ci-disabled-jobs-and-runner-load.md` and from seven places inside the ledger. Verified by seed rather than by reading: master carries none of `7964289159858266180`, `6993732056053195542`, `257091693002036498` or `1883070987812776347`, so exactly three entries here are genuinely this branch's. They become the SEVENTEENTH to NINETEENTH and move below master's sixteenth, with a preamble saying why two of them predate it - master's own fifteenth states the rule: the numbers are recording order, not chronology. Their internal back-references were repaired with them ("identical to the twelfth" meant the entry now numbered seventeenth), and the file's existing advice stands: cite the seed, never the ordinal. **`bug-shared-collections-across-the-poll-boundary.md`** - this branch's text is the more accurate (it names the files and records that `PartitionState.java` left with the confluentinc#893 carry), but it cited `pr-323-docs-outstanding.md`, which master deleted when #323 merged. Kept the text, took master's pointer to `pr-blockers-and-collisions.md`, and said which note handed the ordering to which. **What the merge caught, which is the gate working.** `bin/test-check-agent-hooks.sh` went red on a registry check master added: this branch registers `check-upstream-map-merged.sh` in `.claude/settings.json` and never documented it in `docs/agent-harness.md`, so the two counts disagreed. The hook now has its bullet - what it refuses, why writing `merged` before the merge is honest rather than a lie, its four fail-open cases, and that it is disposable once the last upstream link closes - and the counts read twelve scripts across thirteen registrations. The check's number-word map stopped at "twelve", so the thirteenth registration reported "the doc no longer states a count" rather than the mismatch; spelled out to twenty rather than to today's figure. No master commit touched `PCMetrics.java`, `PCMetricsDef.java`, `ShardManager.java`, `PartitionStateManager.java` or `.claude/hooks/check-upstream-map-merged.sh`, so the PR's own subject arrives unconflicted. Checked that nothing the recut deleted was silently resurrected - the trap this branch hit on an earlier master merge, where a deleted test came back with no conflict raised. Local: core compiles, 423 tests, 0 failures, 8 skipped; `bin/test-check-agent-hooks.sh` all pass; `bin/check-all.sh` 14 of 15, with `check-branch-self-reference` assessed after this commit - a staged-but-uncommitted merge makes every line master contributed read as one this branch added. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
astubbs
added a commit
that referenced
this pull request
Aug 26, 2026
…369) `origin/presentation` carried Demo.java, the code behind the asciinema cast embedded in the README - unmerged since 2021 and named in no ledger, which is exactly how a published artefact came to depend on a branch nothing in the repository knew existed. It is the branch that triggered the fork-wide branch audit. The decision to archive and delete it was recorded in #327; this executes it. ORDER MATTERS AND WAS FOLLOWED: the annotated tag `archive/presentation` was pushed at ffda9c6 and VERIFIED present on the remote, and verified pointing at the exact branch tip, before the branch was deleted. Reversing that risks the commit being garbage-collected between the two steps - which would make the deletion the very thing the audit exists to prevent. Not merged, because the code is demo-grade and its own commit messages say so; one records an unfixed data race under load. Not dropped either, because the README still embeds the cast it produced, so the source behind a published artefact stays recoverable: `git show archive/presentation`. FIRST TIME `branch_accounting` HAS DONE ITS JOB on one of our own branches. The entry read "DECIDED: archive under an archive/ tag, then delete. Not yet done, so this entry is the only record of the decision." It now carries `state: deleted` with the tip, the date and the tag, which is the whole contract: a future audit finding no `presentation` branch can tell a deliberate deletion from an accident without redoing the work. One reference had just become actionable-and-broken - the handoff note told a reader to rescue Demo.java from a branch that no longer exists - and is repointed at the tag. AND THE SELF-TEST THAT GUARDS THE MANIFEST BROKE ON THIS EDIT, which is the transferable half. Three arms of `bin/test-check-upstream-map.sh` anchored on the literal text `- {ref: presentation, state: ours,`, so a correct manifest edit failed the test guarding the manifest - and failed as "fixture anchor not found", which reads like a broken test rather than a moved row. Every negative arm now inserts its own synthetic row via a new `row:` mutation mode and depends on nothing but the schema it tests. Coverage rose while converting: `missing ref` had no arm at all, and both terminal states now carry the tip-required pair - verified by injecting the regression and watching exactly one arm go red. It reached CI because `bin/check-all.sh` runs `check-*.sh` while the self-tests are `test-*.sh` and need `--with-tests`. A local sweep reporting "15 ran, 15 passed" had never executed the file, and read as complete. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Ten open
upstream-mirrorissues had never been assessed against this tree. They turned out not tobe untriaged: each carries a
## Fork statussection written when it was mirrored, and thatsection - not
upstream-map.yaml, notupstream-pr-analysis.adoc- is where the fork's onlyjudgement about most upstream issues lives. Searching the two documents came up thin for exactly
that reason.
Most had drifted, and the branch grew from there into two adjacent questions with the same shape:
what else in this repo reads as verified and is not, and what is keeping a record that nothing
checks.
Re-cut into seven atomic commits, so each can be read, bisected or reverted on its own. The
review fixes are not among them: a re-cut stages final state, so the corrected claims simply are
commits 1-5, with how they came to be wrong kept in their messages.
docs(inflight): assess ten untriaged upstream mirrors....adocverdicts, manifest corrections, the note-naming rule, and the Renovate counter-evidencedocs(inflight): nothing has ever audited the fork's own branches...docs/fork-branch-archaeology, and the upstream-branch gap it uncovereddocs(map): give every branch one record...branch_accounting, replacing three overlapping registersdocs(map): delete the mirrored bot branches...fix(gates): the branch record this PR adds was validated by nothingfeat(docs): index every GitHub issue in one file...bin/issue-index.sh, so grep reaches the trackerdocs(merge): ask at merge prep whether the PR should close an issueThe ten mirrors, and why their bodies were wrong
The errors were the load-bearing kind - each would have caused a wrong action:
commitOffsetsthatTransaction system improvements and docs confluentinc/parallel-consumer#355 falsified in 2022.
typed per-exception seam already exists and is load-bearing, so the fix is far cheaper than
recorded.
thread. It was never on the control thread - which changes the answer to the reporter's question.
guarantees, and names a fork PR as closest help when that PR moves the symptom the wrong way.
close-path failure the reporter himself called the bigger problem.
shipped - the fact that decides whether it can close.
Why they got that way is recorded at population level in
upstream-mirror-bodies-are-stale.md,because the causes are structural and will recur: a tree-wide rename invalidated every
file:linecitation in every body in one commit, silently (one had been wrong since the day it was written);
nothing re-checks a body once written, unlike a map entry with its
last_checked; and nothing inthe format separates a verified claim from an inferred one.
Three refuted verdicts, corrected rather than softened
Handling Partition Revocation in Parallel-Consumer Leading to Duplicate Event Processing confluentinc/parallel-consumer#777 and Record being picked up by multiple threads simultaneously confluentinc/parallel-consumer#843."
Replace the existing stale container when adding work container confluentinc/parallel-consumer#909 is already merged here as fix(core): replace a stale container at a reused offset after rebalance #31 with the
behaviour unchanged; make committed offset accurate when partition assigned to avoid offset reset confluentinc/parallel-consumer#893 fixes a commit running ahead of
completion, the opposite shape. Upstream's maintainer answered
Handling Partition Revocation in Parallel-Consumer Leading to Duplicate Event Processing confluentinc/parallel-consumer#777 in 2024, before either PR existed, saying the redelivery is
expected at-least-once behaviour. Left standing, this closes it the moment
fix(core) astubbs#120: unbounded PCMetrics heap growth, with the confluentinc#905 hot-shard metric #57 merges.
Record being picked up by multiple threads simultaneously confluentinc/parallel-consumer#843." That defect drops records and wedges an offset - loss and
stall, not duplication - and requires a rebalance the reporter explicitly denies.
was a kafka-clients SASL callback using a
SubjectAPI the JDK withdrew, fixed in kafka-clients3.9.1 by KAFKA-19024. This tree is on 3.9.2.
Note names now carry the fork issue number
A fifth of
docs/inflight/already carried a number and the existing names disagree about what itmeans -
bug-857-family.mdis a confluentinc number,perf-192-followups.mda fork one. That isthe coin flip
docs/issue-references.mdexists to prevent, with none of the protection, because afilename cannot be qualified. The three notes first added here as
upstream-543,upstream-777andupstream-809were the sharpest case: all three numbers also exist as fork issues meaning otherthings. Older disagreeing names are left alone - renaming breaks every citation and improves nothing.
The fork's own branches have never been audited
origin/presentationcarries the code behind the asciinema cast embedded in the README, unmergedsince 2021 and named in no ledger. Chasing that found 109 branches on this fork accounted for by no
inventory at all.
The transferable part is the mechanism. Four inventories exist; three were correctly scoped to
something that structurally excluded the branch. The fourth is the near miss:
docs/upstream.mdcarries an entry titled "Orphan branches never attached to a PR" - the right check pointed at the
wrong remote. It swept
upstream; the branch exists only onorigin. That reads as covering orphanbranches generally while covering five branches on one of two remotes, which is worse than not
looking, because it closes the question. Every audit was seeded from a list of interesting things
and worked outward; none started from the complete set of refs and worked inward.
The upstream half, now closed. 34 of upstream's 42 branches existed on no branch of this fork.
The tempting reading is that we deleted them; tested and refuted - for 33 of the 34 every commit
postdates this fork. The mechanism: a fork receives branches once, at creation, and never again.
This one dates from 2020, upstream kept creating branches for six more years, and none arrive.
All 42 are now mirrored under
upstream/*, tips verified. The namespace is load-bearing: eight sharea name with one of ours carrying divergent work - including
master- so pushing under their ownnames would have overwritten our history.
pyallel-consumeris the immediate value: a prior Pythonclient, prior art in the strongest sense, while a Python client is being written on
feats/proxy-requirements.One branch record, replacing three
branch_accountingrecords what we decided about a branch, in a form that outlives the branch.The failure it prevents: a branch is reviewed, judged worthless and deleted, its only trace was
itself, and the next audit re-finds the absence, cannot tell a deliberate deletion from an accident,
and redoes the work. So
state: deletedkeeps its entry, with tip, date and reason.It replaces three registers that held the same commits under different framings -
preserved_branch_tipsandsweep-2023-admin-closure.preserved_headsrecorded the same SHAs, andconfluentinc#443 and the
pyallel-consumertip turned out to be two names for onecommit. The rule in its header is what stops it rotting: nothing a command answers.
First use: the bot branches are gone. 17 mirrored dependency-bot branches deleted and recorded
as deleted. Sixteen were one commit touching one
pom.xmlagainst upstream's diverged tree. Theseventeenth was not a bot branch at all - a maintainer had pushed four commits onto
dependabot/maven/org.threeten-threeten-extra-1.8.0. It was read before deletion and given its ownentry. A sweep keyed on
dependabot/*would have taken human commits silently - a name trustedin place of contents, the same failure as the stale bodies. Our own
dependabot/*branch isuntouched: it heads #38, and deleting it would have closed that PR.
The record this PR adds was validated by nothing
upstream-map.yamlhas a validator. This PR addedbranch_accountingand left it outside thevalidator - so
state: TYPO_NOT_A_STATEvalidated clean while the run printedOK: 39 entries, no schema errors, a reassuring count of the section it had looked at. The successline now names both sections.
The other half was worse:
upstream-map.py validatewas invoked by no workflow, no gate and nohook, so fixing the schema check without giving it a caller would have fixed nothing.
bin/check-upstream-map.shis that caller, and needed no registration -check-all.shdiscovers byglob, so the sweep went 38 → 40 with no workflow edit. Confirmed it will genuinely run in CI rather
than skip:
check-docs-data.shshares the PyYAML dependency and the last hygiene run reports itokwith
0 could not run.The new check immediately failed two of my own entries, and the rule was wrong rather than the
data. Both are
state: ours- live branches whose SHA is onegit rev-parseaway, and thissection's governing rule is nothing a command answers. A tip is now required only for
deletedandarchived. The self-test carries both halves of that pair.Every negative arm was run against the pre-change validator and observed to pass wrongly - all
print
OK: 39 entriesand exit 0, including the integer-tip case that bit for real in review(
tip: 255916684is all digits, so YAML makes it an int and it never compares equal togit rev-parseoutput).What review and the master merge caught - all six now fixed
A multi-agent review, including an independent cross-model adversarial pass, turned this branch's own
thesis on it: several corrections overstated what had been checked. The worst was a postable draft
quoting a fourth chaos-suite cell as measured, when the owning test's javadoc records three and
predicts the fourth. Cut, with the run listed as work to do. Others were narrowed to what was
established: a first poll at offset 0 does not take the truncation branch, because the comparison is
strict; the poll-path claim is now about deserialization failures specifically; an anchor occurring
twice was replaced by the unique callee.
Merging master then brought gates that caught three more:
check-file-refs.shcould not seesame-directory links until master fixed it; with that fixed it flagged
branch-language-proxy.md,cited as where the Python client is being built.
git log --diff-filter=D --allfinds no deletion,because there was nothing to delete - a plausible filename written from an adjacent fact. The
third instance on this branch of the failure the branch was opened to document, and the second I
committed myself.
next-prefix and the link did notfollow.
against this branch's dated, verified "42", which matches
git ls-remotetoday. Master had justwidened never write down what a command can answer to name counts explicitly.
One review finding was rejected by validation and deliberately not applied, recorded so it is not
re-raised: the java-24 entry's
status: mergedwith no branch or PR is legitimate, because theschema defines
mergedas "landed on fork master" without requiring either.Coverage gap, stated rather than hidden: on the delta review the cross-model peer hit its
deadline and returned nothing, so that lens is uncovered for the later slice.
A second review, asked to attack the claims, found six more - all fixed
Each was re-verified against HEAD before being touched:
RetryQueueclaim was backwards. The note saidsize()andisEmpty()read a plainHashMap"with no lock at all"; both takelock.readLock(). It was true when written andfalsified by
d2e00faf0, which arrived in a master merge on this branch hours later - so thebranch's own hygiene step invalidated its own record and nothing re-checked it. Rewritten to what
is true, and kept rather than deleted, because the defect was real (in
removeAll's fast path)and it is the worked example the note needs.
split out of fix(core) astubbs#120: unbounded PCMetrics heap growth, with the confluentinc#905 hot-shard metric #57 onto fix(core) astubbs#121: commit the offset the encoded payload was written against (confluentinc#894) #337 before these notes
were written; one note hung a deadline argument on the old PR being open, and the
.adoclinethis branch rewrote still named it. A live citation resolving to the wrong PR is worse than one
that breaks.
a
grepinstruction pointing at a string that does not exist in the file it names. Exactly whatAGENTS.md's "run the grep before you commit the citation" exists to catch, and neither grep wasrun.
also arrived by master merge. Narrowed to the suites the argument actually needs.
archivedhad no test coverage. The validator requires a tip fordeletedandarchived;only
deletedwas exercised, and the manifest has no archived entry, so a regression to("deleted",)would have been caught by nothing. Two arms added, and the regression injected toprove the negative one goes red rather than passing for its own reasons.
next-toprocess-rename onecommit message describes. Rewriting history again to repair a sentence about history costs more
than it returns.
Three of those six were created by this branch's own merge and re-cut, after the content had been
written and reviewed - which is the argument for verifying claims after the final merge, not before.
An index of every issue, so grep reaches the tracker
gh issue list --state allis, byAGENTS.md's own admission, the most-skipped of its sixprior-art checks - structurally, not through laziness: an agent has to think of querying GitHub
before it can, and it greps by reflex. So the issue tracker was the one knowledge surface a keyword
sweep of
docs/could not reach.bin/issue-index.shwritesdocs/inflight/issue-index.md- one line per issue, with number, state,title and labels. Working on offset encoding now surfaces #237 without
anyone having formed the intent to look for it.
It breaks "never write down what a command can answer" deliberately, and the distinction matters
because the next reader should challenge it. That rule exists to stop a second tracker forming: a
copy that gets believed, drifts, and cannot be told from the truth. This one is not built to be
believed - it carries the date the data was read, says twice that rows go stale silently, and sends
you to
gh issue viewbefore acting. The precedent is already here:.claude/hooks/inject-recorded-knowledge.shinjects the titles of everydocs/solutions/write-up at session start for exactly this reason.
It earned its keep before merging. Within minutes of generating it,
#41 stood out as labelled
wontfixwhile beingOPENwithstateReason=REOPENED- closed as wontfix once, reopened, and the label never removed. The label waswrong, not the issue; it has been removed and the row regenerated. Nobody was going to notice a stale
label on a two-year-old issue by reading the tracker, and a grep-visible row made it obvious.
It is also the worked example for why this is a discovery aid and not state: reading the label alone
gave the wrong answer, and only the state column beside it revealed the contradiction. That is what
the header warning is for.
No
--checkgate, unlikebin/todo-index.sh. That script regenerates from the tracked tree, sostaleness is decidable offline and a gate is free. This one cannot be - deciding whether it still
matches reality means asking GitHub, needing network and a token. Such a gate is skipped for fork PRs
and dies on a token expiry, which is the failure
bin/check-cve-exclusions.sh's header describes:an unwatched list rotting exactly when its guard cannot run. Staleness is handled by saying so, with
a date.
The inflight tags are emitted by the generator, since the file is rewritten wholesale and a
hand-added tag would be dropped by the next run.
docs/inflight/AGENTS.md's "No committed index"rule now says what it always meant - no index of these notes - and names this file, so it is not
deleted on sight by an agent correctly citing it.
Other instances of the same defect
The class is a record that reads as verified and is not, sharpened by the invented citation into
its nastiest form: a reference written from adjacent evidence that names something which never
existed.
check-file-refs.shcatches a broken link; it cannot see a bare filename in backticks.So I swept the whole tree for backticked
.mdfilenames resolving to nothing. No furtherinstance - every other hit is explained by its own prose (a note deliberately deleted, one landing
with a different branch, a superseded audit), and the two on this branch are the deliberate
cross-branch case, stated inline both times.
Also checked and ruled out:
upstream-map.yamlentries were accurate where they existed, except thetwo corrected here;
docs/solutions/entries were cited by several assessors and none was stale. Twopre-existing notes still carry
file:linecitations, left alone as out of scope.Surfaced and worth fixing separately:
bin/check-issue-refs.shenumerates viagit diff --name-only,so it scans tracked files only - every agent's first "gate passes" asserted nothing about an
untracked new file.
Deliberately not done
No issue has been touched - no comment, label, close or body edit. Every correction and every
reporter-facing answer is drafted in its note and left unposted, pending a maintainer's decision.
Two are recommended for closing (#161, and
#163 after answering), one is a judgement call
(#181 - closeable on the code, but no CI lane above Java 17 proves it), and
the rest stay open with corrected bodies.
origin/presentationis still live: its archive-then-delete decision is recorded inbranch_accountingbut not executed, and that entry is currently the only record the decision exists.Checklist
docs/upstream.mdand the manifest header name the new gate, and keep thestill-true claim that the fork side is checked by nothing
docs/features/-N/A - no user-facing feature; internal triage records and a repo gatebin/test-check-upstream-map.sh, ten arms, every negative one verified red against the pre-change validator🤖 Generated with Claude Code
https://claude.ai/code/session_01SFRbSkHwaRw6YYFHHBWZ7p