tooling(agents): one front door for the in-flight tools, and the survey that scoped it

.claude/hooks/inject-recorded-knowledge.sh

@@ -77,6 +77,48 @@ emit "you know what exists; grep the ones that look close. Skipping this is the
 emit "skipped, and its failure is silent - you rediscover the problem and it feels like progress."
 emit ""
 
+# THIS INDEX IS BRANCH-SCOPED, AND SAYING SO IS THE POINT.
+#
+# Every enumeration in this file - `find docs/solutions`, `find docs/plans`, `grep -rl docs/inflight`
+# - reads the WORKING TREE, so it lists what the current branch carries and nothing else. Most of
+# this repo's documentation has never landed on master: notes, plans and write-ups are authored on
+# the branch that produced them and stay there until that branch merges, which many never do.
+#
+# An index that is silently partial is worse than no index, because it reads as complete. On
+# 2026-09-01 a session investigating astubbs/parallel-consumer#44 ran all six AGENTS.md checks from
+# master, got a plausible-looking set of hits, and missed a decomposition plan, an architecture
+# write-up on the exact seam under investigation, and a sibling-defect note - all of them
+# branch-only, none of them findable by any command the table gave it.
+#
+# So the block below states the gap in the same breath as the list, and names the one command that
+# closes it. Cost is one `git grep` across every ref, in a single process.
+branch_only_note=$(
+    set -uo pipefail
+    refs=$(git for-each-ref --format='%(refname:short)' refs/heads refs/remotes/origin 2>/dev/null \
+        | grep -v '/HEAD$') || exit 0
+    [ -n "$refs" ] || exit 0
+    baseline=origin/master
+    git rev-parse --verify --quiet "$baseline" >/dev/null 2>&1 || baseline=master
+    # shellcheck disable=SC2086 # word splitting is how the ref list reaches git grep
+    everywhere=$(git grep -l -I -E '.|^$' $refs -- 'docs/' 2>/dev/null | cut -d: -f2- | sort -u | wc -l) || exit 0
+    here=$(git ls-tree -r --name-only "$baseline" -- docs/ 2>/dev/null | wc -l) || exit 0
+    [ "$everywhere" -gt 0 ] && [ "$here" -gt 0 ] && [ "$everywhere" -gt "$here" ] || exit 0
+    echo "$((everywhere - here)) $everywhere"
+) || branch_only_note=""
+
+if [ -n "$branch_only_note" ]; then
+    set -- $branch_only_note
+    emit "**This list is what the CURRENT BRANCH carries, and that is not all of it.** \`$1\` of the"
+    emit "\`$2\` documents under \`docs/\` across every ref exist only on branches that have not merged,"
+    emit "so nothing below names them and no working-tree grep can reach them. To search all of it:"
+    emit ""
+    emit "    node bin/inflight.mjs prior-art <mechanism> [<mechanism>...]"
+    emit ""
+    emit "Run it before concluding \"no prior art\" - that conclusion is otherwise a false negative"
+    emit "wearing the authority of a completed check."
+    emit ""
+fi
+
 current=""
 while IFS= read -r f; do
     category=$(basename "$(dirname "$f")")

.github/workflows/maven.yml

@@ -954,10 +954,37 @@ jobs:
             setup-java-Linux-x64-maven-
       - name: Build and Test
         run: bin/ci-build.sh
-      - name: Upload coverage to Codecov
+      # PER-SUITE FLAGS, MATCHING THE PR LANE - because the base and the head have to be measured
+      # the same way for a coverage COMPARISON to mean anything, and they were not.
+      #
+      # This job is `push`-only and uploaded everything under one `default` flag, while a PR runs the
+      # `test` matrix and uploads `unit`, `integration`, `performance`, `lincheck`, `chaos` - and no
+      # `default` at all. So codecov compared a PR total built from the suite flags against a base
+      # total built from `default`: disjoint measurement sets, differing by more than `codecov.yml`'s
+      # 1% threshold, on identical code. Observed on astubbs/parallel-consumer#400, a docs-and-tooling
+      # PR touching ZERO Java: Files 90 -> 90, Lines 4822 -> 4822, Branches 463 -> 463, and a reported
+      # -3.53%. Nothing had changed; the two sides were counting different things.
+      #
+      # NOT CARRYFORWARD FLAGS, which is the reflexive fix. Carrying master's `default` into a PR's
+      # total merges a STALE master measurement of the same code, so a genuine drop in any line that
+      # measurement covered is masked. That trades a noisy false positive for a silent false negative,
+      # and this repository has spent too long removing the second kind to add one back here.
+      #
+      # `clean verify` passes through both `test` and `post-integration-test`, so the pom's `report`
+      # and `report-integration` executions both run: jacoco/ is the surefire (unit) half and
+      # jacoco-it/ the failsafe (integration) half, which is exactly the split the PR lane makes with
+      # two separate jobs.
+      - name: Upload unit coverage to Codecov
         if: always()
         uses: codecov/codecov-action@v5
         with:
-          files: '**/target/site/jacoco/jacoco.xml,**/target/site/jacoco-it/jacoco.xml'
-          flags: default
+          files: '**/target/site/jacoco/jacoco.xml'
+          flags: unit
+          token: ${{ secrets.CODECOV_TOKEN }}
+      - name: Upload integration coverage to Codecov
+        if: always()
+        uses: codecov/codecov-action@v5
+        with:
+          files: '**/target/site/jacoco-it/jacoco.xml'
+          flags: integration
           token: ${{ secrets.CODECOV_TOKEN }}

AGENTS.md

@@ -73,6 +73,7 @@ is untracked (a whole triage doc was once written duplicating `docs/refactoring.
 | Document | Read it when |
 |---|---|
 | [`docs/logging.md`](docs/logging.md) | Changing a logback file, adding a log stream, or wondering why a logging change had no effect - the two test profiles and how to prove which one loaded |
+| [`docs/inflight-tool.md`](docs/inflight-tool.md) | Querying the repo across every ref - worked examples for `bin/inflight.mjs`, and why each working-tree answer is wrong |
 | [`docs/testing.md`](docs/testing.md) | Writing or debugging tests: suite split, **why a run prints nothing and the flag that fixes it**, the ambient probe autopsy, the quarantine lane, the chaos suite, shared test utilities |
 | [`docs/ci.md`](docs/ci.md) | CI is red, or you are changing a workflow: what each workflow does, the self-hosted lanes, how to fetch a failed job's log |
 | [`docs/investigating.md`](docs/investigating.md) | Past the prior-art checks and into diagnosis: control arms, instrumentation traps, reporting rates |
@@ -104,7 +105,7 @@ a file in it is touched, rather than waiting to be opened.
 |---|---|---|
 | **`AGENTS.md`** (this file) | Rules that bind every agent, and the map above | Work items of any kind; anything only one topic needs |
 | **`STRATEGY.md`** (repo root) | What the product is and why: target problem, the client-side guiding choice, who it is for, success metrics, tracks under investment | A roadmap or feature list. It is a *claims* document nothing tests - work that falsifies a claim must update it; the branches that will are named in `docs/inflight/pr-strategy-doc-merge-triggers.md` |
-| **`docs/inflight/`** | *Transient* cross-branch state, **one file per item**, named `<area>-<slug>.md` - the prefix names an AREA, never a status. Rules, the prefix table and the tag vocabulary in [`docs/inflight/AGENTS.md`](docs/inflight/AGENTS.md), which owns them | A backlog. A committed index file, which every PR would edit. **Not a place knowledge goes to die**: when your PR resolves a note, migrate what outlives it to its durable owner first - deleting the file is one of four outcomes, and that doc names them |
+| **`docs/inflight/`** | *Transient* cross-branch state, **one file per item**, named `<area>-<slug>.md` - the prefix names an AREA, never a status. Rules, the prefix table and the tag vocabulary in [`docs/inflight/AGENTS.md`](docs/inflight/AGENTS.md), which owns them | A backlog. A committed index file, which every PR would edit. **Not a place knowledge goes to die**: when your PR resolves a note, migrate what outlives it to its durable owner first - deleting the file is only one of the outcomes, and that doc names them |
 | **`docs/refactoring.md`** | Refactors **too small to deserve their own note** - a line or two each, grouped by file, no owner or tags - plus **breaking changes queued for the next major** (release-gated section) and the **triage of `TODO`/`FIXME`/`XXX` markers** | Anything carrying a decision, evidence or tracking - that is a `docs/inflight/` note; promote the line and delete it in the same commit |
 | **`docs/todo-index.md`** | Generated inventory of every marker in the tree (`bin/todo-index.sh`, `--check` fails when stale) | Priorities - deliberately unsorted; triage goes in `refactoring.md` |
 | **`docs/quarantined-tests.md`** | CI-enforced registry of quarantined tests and, when one exists, their owning fix PR (unowned entries are legal, flagged advisory) | Tests that merely flake - quarantine requires evidence: a diagnosis, or a recorded sighting ledger proving it is master-state |
@@ -189,26 +190,31 @@ accidental is *which* repo answered. The same ambiguity bites a bare `#NNN` in p
 
 ## Before you investigate anything
 
-Do all six checks **before** forming a hypothesis, and say in your write-up what each returned -
-including "nothing". Prior art tells you the method that settled the last question of this shape,
+Do every check in this table **before** forming a hypothesis, and say in your write-up what each
+returned - including "nothing", and including the size of the corpus that "nothing" covered. Prior art tells you the method that settled the last question of this shape,
 and the traps that voided earlier experiments.
 
 | Check | Command |
 |---|---|
-| Prior investigations | `ls docs/plans/`, then grep them |
-| Solved problems | `grep -rl <mechanism> docs/solutions/` |
-| In-flight state | `ls docs/inflight/`, `grep -rl <mechanism> docs/inflight/` |
+| Plans, solutions and in-flight notes, **on every branch** | `node bin/inflight.mjs prior-art <mechanism> [<mechanism>...]` |
 | Open PRs (collision check) | `gh pr list -R astubbs/parallel-consumer`, then `gh pr diff <n> -R astubbs/parallel-consumer --name-only` |
 | **Merged** PRs, by file | `gh pr list -R astubbs/parallel-consumer --state merged --limit 100 --json number,title,files --jq '.[] \| select(.files[]?.path \| test("<ClassName>")) \| "\(.number) \(.title)"'` |
 | Issues, `--state all` | `gh issue list -R astubbs/parallel-consumer --state all --limit 300` - fork issues *and* `upstream-mirror` ones; read the upstream original, not the mirror's summary |
 | **The javadoc of the thing you are about to run or change** | `grep -rn "Calibration status" --include=*.java .` - chaos scenarios record their prior experiments, seeds and verdicts in the class javadoc, nowhere else |
 
+- **`grep` and `find` read the working tree, and most of this repo's docs are not in it.** Roughly
+  two thirds of everything under `docs/` exists only on branches that have not merged, so a
+  working-tree search answers a narrower question than the table asks and returns a *false negative
+  carrying the authority of a completed check*. `bin/inflight.mjs prior-art` searches every ref and flags
+  each hit that is missing from `origin/master`; `bin/lib/prior-art.mjs`'s header explains the rest. Worked incident:
+  [`docs/solutions/workflow-issues/prior-art-lives-on-branches-2026-09-01.md`](docs/solutions/workflow-issues/prior-art-lives-on-branches-2026-09-01.md).
 - **The titles are already in your context**, injected at session start by
   `.claude/hooks/inject-recorded-knowledge.sh` - so "I did not know it existed" is not available as
-  an excuse, and the check costs one grep against a list you have been handed.
+  an excuse. **That index is branch-scoped too**, and says so along with the count it cannot show
+  you; it narrows the search, it does not complete it.
 - **Grep the mechanism, not the symptom.** The failing test's name is the weakest search term
   available. Search the class, the lock, the option, the exception, the log line.
-- **A test's own javadoc is prior art, and the six commands above will not find it.** The chaos
+- **A test's own javadoc is prior art, and the commands above will not find it.** The chaos
   scenarios carry a `Calibration status` block naming the shapes already tried, the seeds, and what
   each run established - including experiments that were run and are worth not repeating. Running
   `ChaosRevokeUnderWorkIT`'s recovery diagnostic in August 2026 re-derived a result its own javadoc

README.adoc

@@ -1698,6 +1698,31 @@ docker container ls --filter 'label=org.testcontainers=true'
 
 See https://github.com/testcontainers/testcontainers-java/pull/1781[this testcontainers PR] for details on the reusable containers feature.
 
+=== Searching the repository across every branch
+
+Most of what this project knows about itself is not on `master`.
+Measured 2026-09-01: **580 of the 901 documents under `docs/` exist only on branches that have not merged**, because a note travels with the work that produced it and many of those branches never land.
+
+So `grep` in your checkout answers a narrower question than the one you asked, and returns a false negative carrying the authority of a completed check.
+
+`bin/inflight.mjs` is the front door for asking across every ref instead:
+
+[source,bash]
+----
+node bin/inflight.mjs help                                  # every command, and when to reach for it
+node bin/inflight.mjs prior-art --headings <term>           # before forming any hypothesis
+node bin/inflight.mjs note find <fuzzy-name>                # which note is this, and who carries it
+node bin/inflight.mjs note drift <path>                     # what other branches have that master does not
+node bin/inflight.mjs branch <ref>                          # what a branch is, and whether anything tracks it
+node bin/inflight.mjs stranded                              # work that will be lost if nobody acts
+----
+
+Every command exits `0` when it *ran* — whatever it found — and `2` when it could not run.
+That distinction is the point: "nothing, across 436 refs" is a result, and a search that never happened is not.
+
+Worked examples, including the CI failure that this tool diagnosed on its own pull request, are in link:docs/inflight-tool.md[`docs/inflight-tool.md`].
+It reads the repository only; it is not a task tracker and owns no schema of its own.
+
 == Implementation Details
 
 === Core Architecture