fix(docs): establish a verbatim fetch route so a truncated env-vars read stops reading as drift

docs/OFFICIAL-DOCS.md

@@ -15,7 +15,11 @@ training-data recall.
 > that date is the ceiling on how current the row still is, not a guarantee. A fetch that no longer
 > matches a row is that row's recheck trigger: update the row, refreshing its date with the
 > outcome. The [upstream-drift convention](conventions/upstream-drift/README.md) owns this
-> stamp-and-trigger discipline.
+> stamp-and-trigger discipline, and its
+> [fetch route](conventions/upstream-drift/README.md#reading-the-basis--the-fetch-route) owns how to
+> read the page you re-fetch: several of these pages are long enough that a summarizing fetch
+> truncates them and then reports what it never reached as absent. Read the `.md` channel verbatim
+> before recording any verdict, and record none at all from a truncated read.
 
 ## Plugin components → doc page
 
@@ -104,7 +108,7 @@ SDK-based host.
 | Permissions | <https://code.claude.com/docs/en/permissions> | 2026-08-06 |
 | Permission modes | <https://code.claude.com/docs/en/permission-modes> | 2026-08-06 |
 | Configure auto mode (`autoMode`, `claude auto-mode`) | <https://code.claude.com/docs/en/auto-mode-config> | 2026-08-09 |
-| Environment variables | <https://code.claude.com/docs/en/env-vars> | 2026-08-06 |
+| Environment variables | <https://code.claude.com/docs/en/env-vars> | 2026-08-10 |
 
 ## Prompting doctrine (platform docs)
 

docs/conventions/upstream-drift/CHANGELOG.md

@@ -4,6 +4,41 @@ Notable changes to the upstream-drift contract (SemVer). Changing a required par
 name, or an enforceability verdict is a major bump; additive guidance is a minor bump; docs-only
 clarification is a patch.
 
+## 1.2.0 — 2026-08-10
+
+Adds [§Reading the basis — the fetch route](README.md#reading-the-basis--the-fetch-route): a rung
+ladder for reading an upstream page the firing procedure already tells you to re-fetch. No required
+part, canonical name, or enforceability verdict changed — the four parts and the observability bar
+are untouched; this says how the basis is read, which every firing already depended on and no
+surface owned.
+
+- **The failure the rung ladder closes is a false negative, not a fetch error.** A summarizing fetch
+  of a long page truncates, and a summarizer then answers "what does this page contain" from the
+  truncated span — an answer indistinguishable from genuine absence. `env-vars` produced exactly
+  that on three independent fetches. Two rules bind every read regardless of rung: no verbatim
+  quote, no claim; and a truncated read supports no absence claim, ever.
+- **Rung 1 — `curl` the `.md` channel and search the file locally — is the default**, verified
+  against `env-vars` on 2026-08-10 (361,797 bytes, 458 lines, 315 variable rows including the
+  `CLAUDE_CODE_MAX_*` range that had truncated away three times; two fetches, identical SHA-256).
+  Rung 2 is a summarizing fetch, admissible only when the read shows the page arrived whole. Rung 3
+  is a verbatim mirror.
+- **The route is hoisted, not invented — from two surfaces that derived it independently.**
+  `claude-ops`'s `changelog` skill carried it page-scoped; `knowledge`'s `docpage-digest` publisher
+  profile carried it claim-scoped, binding absence-establishing fetches to `curl` on the raw `.md`
+  channel after two of its own runs asserted a false absence. Two independent derivations is the
+  signal a rule wants an owner, and the one-owner-per-concern rule puts the general form here while
+  leaving their scope-specific detail with them. The profile's warning that a raw-markdown channel
+  can 404 per page is carried across as the reason a run verifies the channel before trusting the
+  rung.
+- **The mirror rung keeps the freshness-corroboration protocol from
+  [#2182](https://github.com/melodic-software/claude-code-plugins/pull/2182)** and generalizes its
+  bar: corroborate against a fact the page's own content can only carry after a known upstream
+  change, never against the mirror's self-reported sync time. A mirror-based record says on its face
+  it is one rung below primary and states retirement of that basis in its trigger.
+- **Currency of a rung-1 read is fixed at what the docs actually support** — the fetch date and
+  nothing more, because the endpoints publish no per-page content date. The 2026-08-10 fetch
+  independently re-confirmed that 1.0.0 header finding: `Last-Modified` came back equal to `Date`.
+
 ## 1.1.0 — 2026-08-10
 
 Adopters registry gains a row for

docs/conventions/upstream-drift/README.md

@@ -110,6 +110,75 @@ current this way states divergence as its trigger — "a read-time re-fetch find
 longer matching the record" is an event decidable from evidence — so the divergence, never the
 lookup, is what fires, and only a firing invokes the maintenance procedure above.
 
+## Reading the basis — the fetch route
+
+Re-fetching a cited basis is the first step of every firing above, so **how** the page is read is
+part of the contract. A summarizing fetch of a long docs page is not a read of that page: it
+truncates, and a summarizer asked what the page contains then answers from the truncated span. That
+answer is indistinguishable from a genuine absence, so a truncated fetch does not merely fail — it
+manufactures drift that is not there. `env-vars` produced exactly that false negative on three
+independent fetches, each stopping before the `CLAUDE_CODE_MAX_*` range and each reporting those
+rows missing ([#2182](https://github.com/melodic-software/claude-code-plugins/pull/2182)).
+
+Two rules bind every read, whichever rung it comes from:
+
+- **No verbatim quote, no claim.** A record's basis is the text, not a paraphrase of it. A verdict
+  of "current" states the quoted span it matched.
+- **A truncated read supports no absence claim, ever.** If the fetch stops short, say so and mark
+  the item unverified. "Not in the response" is never "not on the page" — the reader cannot tell
+  those apart, which is the entire failure this rung ladder exists to prevent.
+
+### The rungs
+
+| Rung | Route | What it yields |
+|---|---|---|
+| 1 — primary | `curl` the raw-markdown channel: append `.md` to the page URL (`https://code.claude.com/docs/en/<slug>.md`), write to a file, and search the file locally | Verbatim bytes, no summarizer, no truncation |
+| 2 — primary, degraded | The `.md` channel fetched through a summarizing tool, or the rendered HTML page | Truncates on long pages; usable only for a page short enough to arrive whole, and the read must show it arrived whole |
+| 3 — mirror | A verbatim third-party mirror of the same docs, with the freshness step below | Verbatim text, **one rung below a primary read**; the record says so |
+
+Rung 1 is the default. It was verified against `env-vars` on 2026-08-10: `curl` returned
+`text/markdown`, 361,797 bytes over 458 lines carrying 315 variable rows including the full
+`CLAUDE_CODE_MAX_*` range, and two fetches seconds apart hashed identically
+(SHA-256 `43a805b4cfffd9aae5e36cec42f3a271dc92ddead26db76cd401d61ff4048584`). That same fetch
+re-confirmed the header finding below — `Last-Modified` came back equal to `Date`.
+
+The route is not new here; it is **hoisted from two surfaces that each derived it independently**.
+`plugins/claude-ops/skills/changelog/context/read-actions.md` carried it page-scoped ("`curl` the
+`.md` and slice locally … Never report a version 'absent from the changelog' on a truncated
+fetch"), and `/knowledge:docpage-digest`'s Anthropic publisher profile carried it claim-scoped,
+binding any absence-establishing fetch to the raw `.md` channel with `curl` plus a recorded length,
+on the asymmetry that "a truncated fetch cannot fabricate a PRESENCE, only an ABSENCE" — after two
+of its runs asserted a false absence exactly this way. Two independent derivations of one rule is
+the signal that it wants an owner. Per the
+[convention registry](../../PLUGIN-PHILOSOPHY.md#convention-registry)'s one-owner-per-concern rule,
+the general form belongs in this doc and those surfaces keep their page-specific detail.
+
+**The `.md` channel is per-page, not universal.** `docpage-digest`'s profile records that a
+raw-markdown channel working for one doc can 404 for another, so a run verifies the channel for the
+page it is reading and drops a rung when it does not resolve.
+
+### The mirror rung and its freshness step
+
+A mirror read is admissible only when it is **verbatim** and its currency is **corroborated against
+the page's own content** — never against the mirror's self-reported sync time alone, which is a
+claim by the party whose freshness is in question. The corroboration names a fact that only a sync
+later than some known upstream change could carry, and the record states it. The worked instance:
+`ericbuess/claude-code-docs` `docs/env-vars.md` was accepted because it carried the v2.1.224
+removal of the 200-subagent-per-session cap, which no pre-v2.1.224 sync can contain.
+
+A record resting on a mirror **says on its face that it is one rung below a primary read**, and
+states retirement of that basis as part of its trigger: a later primary read of the same range
+replaces the mirror basis and the record is refreshed to say so. That is not hypothetical — the
+`discipline` `sweep-all` record written this way on 2026-08-10 fired and was refreshed to a primary
+basis the same day, by the rung-1 fetch above.
+
+### Currency of a primary read
+
+The docs serve no per-page content date ([below](#drift-signal--content-hashing-deferred)), so the
+honest currency statement for a rung-1 read is the fetch itself: *fetched live from `<url>` on
+`<date>`; upstream publishes no per-page content date.* Nothing stronger is available, and a stamp
+that implies otherwise is the overclaim this doc's [first rule](#a-date-is-never-authority) forbids.
+
 ## Drift signal — content hashing, deferred
 
 There is no mechanical per-page change signal on the official Claude Code docs: the raw-markdown

plugins/claude-config/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "claude-config",
-  "version": "0.29.0",
+  "version": "0.29.1",
   "description": "Seven configuration-health skills (plus setup) for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), audit-instructions (locally-owned instruction surfaces vs current model capability — proposes removals/rewrites of instructions the model no longer needs, and detects cross-surface instruction conflicts), audit-prompting-postures (the additive lane — posture guidance the prompting guide says a component's purpose needs but the component does not carry), audit-pass (one coordinated, ordered, resumable pass over a named target — three-scope inventory, run-time-derived exclusion set, stable finding identity, suppression memory, resume, one human gate — delegating every check to the plugin that owns it), and unhobble (the empirical bare-baseline experiment: reversibly strip a repo's standing instructions, log real stumbles against the current model, re-add only what evidence earns).",
   "author": {
     "name": "Melodic Software",

plugins/claude-config/CHANGELOG.md

@@ -3,6 +3,44 @@
 All notable changes to the `claude-config` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.29.1]
+
+### Fixed
+
+- **`audit`: the MANDATORY env-var check told auditors to do the exact thing that fabricates
+  findings.** Category F required fetching `code.claude.com/docs/en/env-vars` and searching it for
+  each name, calling that page "the authoritative source" — with no word about how to read it. The
+  page carries 315 variable rows and truncates through a summarizing fetch, which then reports the
+  rows past the cutoff as absent; `env-vars` produced that false negative on three independent
+  fetches (#2182). An auditor following this row as written could flag a perfectly valid variable as
+  unrecognized and never know. The row now routes through the
+  [`.md` fetch route](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/upstream-drift/README.md#reading-the-basis--the-fetch-route)
+  — `curl` to a file, grep the file — and states that a truncated read supports no finding at all.
+- **`audit`: and the inverse error the same row invited.** "Authoritative source" plus "do not flag
+  as unrecognized without checking this page" reads as *absent here means not a real variable*.
+  It does not: `CLAUDE_CODE_ENTRYPOINT`, `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`, and
+  `CLAUDE_CODE_EXPERIMENTAL_OBSERVER_AGENTS` are each cited as real in this repo and each absent
+  from a full verbatim read of the page on 2026-08-10. The row now caps the strongest available
+  verdict at "not documented on `env-vars`" and names the sibling pages to check first.
+- **`audit-instructions`: the effort-audit reading list promised a release the page does not state.**
+  It sent auditors to `env-vars` for `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` "with the models **and
+  release** it reaches"; the row states the models — "Has no effect on Fable 5, Sonnet 5, or Opus
+  4.7 and later" — and no release at all (verbatim read, 2026-08-10). Sending a reader to look for
+  something that is not there invites them to invent it. The clause is corrected, and the entry
+  routes through the fetch route for the same truncation reason as Category F above.
+- **`audit-pass`: `DISABLE_DOCTOR_COMMAND` is documented, and the handoff said it was not.**
+  `reference/doctor-handoff.md` carried it as a design-phase channel "not documented on the current
+  official pages … does not appear in the environment variables list (checked 2026-07-24)". A live
+  verbatim read on 2026-08-10 found it, and found it describing this skill precisely: "Set to `1` to
+  hide the `/doctor` setup checkup skill and its `/checkup` alias … Doesn't affect the `claude
+  doctor` terminal command. Before v2.1.205, this variable hid the `/doctor` diagnostics screen
+  command" — which independently corroborates the v2.1.205 cutover the same section already states.
+  It moves up into the verified list with the scope the row actually draws (session skill, not the
+  terminal command). The pass still **detects** rather than predicts: a documented suppression lever
+  says an operator could have set it, never that they did. The `skillOverrides` half is untouched and
+  still says so — this run re-derived the `env-vars` basis only, and the recheck trigger now names
+  the settings fetch that would retire the stale half.
+
 ## [0.29.0]
 
 ### Removed

plugins/claude-config/skills/audit-instructions/reference/criteria.md

@@ -155,8 +155,10 @@ I15–I28 apply to all surfaces; I13 and I14 name narrower surface sets in their
   <https://code.claude.com/docs/en/model-config>
 - Settings (the `effortLevel` value set) — <https://code.claude.com/docs/en/settings>
 - Environment variables (`CLAUDE_CODE_EFFORT_LEVEL`, `MAX_THINKING_TOKENS`, and
-  `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` with the models and release it reaches) —
-  <https://code.claude.com/docs/en/env-vars>
+  `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` with the models it reaches) —
+  <https://code.claude.com/docs/en/env-vars>; read it verbatim per the
+  [fetch route](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/upstream-drift/README.md#reading-the-basis--the-fetch-route),
+  because a summarizing fetch truncates this page well before these rows
 - Prompt caching (what belongs to the cache key) — <https://code.claude.com/docs/en/prompt-caching>
 - CLI reference (`claude doctor` and the other terminal forms) —
   <https://code.claude.com/docs/en/cli-reference>

plugins/claude-config/skills/audit-pass/reference/doctor-handoff.md

@@ -30,7 +30,7 @@ Checking a version number alone is not a presence check. The pass reports **whic
 failed rather than a bare "unavailable" — and it distinguishes what official documentation confirms
 from what it does not.
 
-**Verified against current official docs (2026-07-24).**
+**Verified against official docs — items 1–2 on 2026-07-24, item 3 on 2026-08-10.**
 
 1. **Version floor — Claude Code v2.1.206 or later.** "The `CLAUDE.md` trim check requires Claude
    Code v2.1.206 or later" ([debug your configuration](https://code.claude.com/docs/en/debug-your-config);
@@ -39,22 +39,37 @@ from what it does not.
 2. **The v2.1.205 behavior cutover.** "Before v2.1.205, `/doctor` opened a read-only diagnostics
    screen and pressing `f` sent the report to Claude to fix" (same page). A pass that assumes the
    pre-cutover shape on a current install is checking for the wrong thing.
-
-**Suppression channels — treat as UNVERIFIED and probe, never assume.** Two further ways an install
-can lack `/doctor` were carried in from this skill's design phase and are **not documented on the
-current official pages** — `DISABLE_DOCTOR_COMMAND` does not appear in the
-[environment variables](https://code.claude.com/docs/en/env-vars) list, and no `skillOverrides` key
-appears in [settings](https://code.claude.com/docs/en/settings) (both checked 2026-07-24). They may
-be real but undocumented, or stale.
+3. **`DISABLE_DOCTOR_COMMAND` — documented, and it targets exactly this skill.** "Set to `1` to hide
+   the `/doctor` setup checkup skill and its `/checkup` alias. Useful for managed deployments where
+   users shouldn't run setup diagnostics from a session. Doesn't affect the `claude doctor` terminal
+   command. Before v2.1.205, this variable hid the `/doctor` diagnostics screen command"
+   ([environment variables](https://code.claude.com/docs/en/env-vars); fetched live 2026-08-10
+   through the [`.md` fetch route](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/upstream-drift/README.md#reading-the-basis--the-fetch-route),
+   which reads the page verbatim — upstream publishes no per-page content date). The 2026-07-24
+   entry claiming it "does not appear in the environment variables list" is **superseded**: it rested
+   on a read of a page long enough to truncate, and this row now confirms both the variable and the
+   v2.1.205 cutover the point above states. Note the scope the row draws: the variable hides the
+   session skill, **not** `claude doctor` in the terminal.
+
+**Suppression channels — one is now documented, one is still not.** Item 3 and a `skillOverrides`
+settings key were both carried in from this skill's design phase, and the 2026-07-24 read recorded
+both as absent from the official pages. Item 3 is no longer absent. `skillOverrides` still is: no
+such key appeared in [settings](https://code.claude.com/docs/en/settings) as of 2026-07-24, and that
+read has **not** been refreshed here — this pass re-derived the `env-vars` half only, so treat it as
+UNVERIFIED and probe. It may be real but undocumented, or stale.
 
 So the pass **detects absence rather than predicting it**: it checks whether `/doctor` actually
 resolves in this environment, and reports the outcome. If it does not resolve while the version floor
-is met, the run says so and names these two as the suspected — unconfirmed — causes, rather than
-asserting either as the reason.
+is met, the run says so and names these channels as the suspected causes — `DISABLE_DOCTOR_COMMAND`
+now with a documented basis, `skillOverrides` still unconfirmed — rather than asserting either as the
+reason. Detecting beats predicting either way: the variable's presence in the list says an operator
+*could* have set it, never that they did.
 
 **Recheck trigger:** any Claude Code minor release, or any change to how bundled skills are
-suppressed. Re-verify against current official documentation before treating a failed prerequisite as
-authoritative — a stale floor would report a present capability as missing.
+suppressed; and, for the `skillOverrides` line above, a `settings` fetch that reaches its key list,
+which would retire that item's stale basis. Re-verify against current official documentation before
+treating a failed prerequisite as authoritative — a stale floor would report a present capability as
+missing, and the entry corrected above shows a stale *absence* claim reads exactly like a fresh one.
 
 ## Absence classification: optional capability