chore(conventions): route unstamped upstream-fact carriers into upstream-drift, and record the gate deferral - #2318
Conversation
…eam-drift, and record the gate deferral Plugins restate upstream harness facts in bare prose — no source, no as-of date, no recheck trigger — so when the upstream behaviour changes nothing makes the stale claim surface. The convention already owned verification stamps, recheck triggers, and the rule that the name binds on touch; the gap was adoption, not design. Three changes, all additive guidance (1.3.0 -> 1.4.0): 1. The Adopters preamble read "Migrated at this contract's 1.0.0", which any appended row would have quietly falsified. It now separates the migrated rows from later on-touch adoptions, requires each later row to name the release that added it, and writes down the bar the third column already implied: a surface is tabled only once it CONFORMS, so a carrier known to be unstamped is a tracked issue rather than a row. That column is a promise to a reader. 2. A fleet sweep of plugins/** found 12 carriers across 11 plugins, filed at #2297 with quoted lines, the files checked and found conforming, and the sweep's own limitation stated (a file-level citation gate under-represents mixed files, so the list is a lower bound). None is tabled here, per the rule above. 3. A CI gate for adoption is deferred, recorded as a decision with a basis and an event trigger. The load-bearing finding: the check the doc already names — flag a `Verified <date>` with no trigger — would NOT have caught #2207, the case that prompted the question, because that surface carried no stamp at all for a stamp-anchored grep to match. The named check is shaped for a half-conforming record; the failure that ships is the zero-part one. Separating an upstream restatement from an in-repo fact is a judgment about meaning, reasoning-only under the tiers doc, and a harness-vocabulary grep would fire on every correct citation too. architecture is deliberately NOT added to the table: #2286 removed the false substitution claim but left an unstamped upstream specific in the same bullet ("even resolved it points at a plugin-global dir"), so the plugin does not yet conform. It is recorded in #2297 instead — which is exactly what change 1 says to do. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 78527a17b5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Claude finished @kyle-sexton's task in 5m 13s —— View job Review complete
SummaryDocs-only change to
One finding, not tied to a changed line so it goes here rather than inline: The Test Plan states "
This doesn't affect the shipped doc content — Not independently verified (no network/script execution available in this sandbox — flagging per review instructions rather than treating the PR's own Test Plan output as my verification): the No correctness issues found in the actual diff content — the Adopters-table preamble, the new tabling rule, and the Recorded-decision section are internally consistent with each other and with the doc's pre-existing four-part-record / recorded-decision definitions (§Required parts, README.md:56-59). |
|
Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count. |
1 participant
Summary
Plugins restate upstream harness facts in bare prose — no source URL, no as-of date, no recheck
trigger — so when the upstream behaviour changes, nothing makes the stale claim surface.
docs/conventions/upstream-drift/already owns exactly this concern and already says the namebinds on touch. The gap was adoption, not design, so nothing new is invented here.
Docs-only. No plugin, script, hook, or CI behaviour changes.
1. The Adopters table now says how a post-1.0.0 row gets there — and what disqualifies one
The preamble read "Migrated at this contract's 1.0.0", which any appended row would have quietly
falsified. It now separates the eight migrated rows from later on-touch adoptions and requires each
later row to name the release that added it.
It also writes down the bar the third column already implied but never stated: a surface is tabled
only once it actually conforms. That column is a promise to a reader about what they can rely on,
so a carrier known to be unstamped belongs in a tracked issue, never in a row — tabling it would
assert the very thing the reader would then not get, which is this batch's own recurring defect
class pointed at the convention meant to prevent it.
2. The fleet sweep — 12 carriers, filed rather than tabled
A sweep of
plugins/**for surfaces stating an upstream harness behaviour with no source, date, ortrigger found 12 carriers across 11 plugins, filed at #2297 with quoted lines and a per-plugin
tally. The issue also records the files checked and found conforming (so the sweep is not
one-sided) and states its own limitation plainly: the citation gate was file-level, so any file
containing a docs URL anywhere was dropped from the carrier pass, which structurally
under-represents mixed files — roughly 300 files were dropped that way. It is a lower bound, not a
census, and it says so.
None is tabled here, which is change 1 applied to its own findings.
3.
architectureis deliberately NOT added to the tableRow 1 of #2273 asks for exactly that row. It is not being added, and the reason is the point:
#2286 (merged while this was in flight) removed the false substitution claim, closing #2207. But the
surviving bullet on
mainstill reads:"Even resolved it points at a plugin-global dir" is an upstream-owned specific —
plugins-reference§Environment variables → §Persistent data directory, which resolves the token to~/.claude/plugins/data/{id}/. It carries no URL, no date, and no trigger. So A-F4 (the unstamped-prose row of #2207) is untouched and
architectureis still a carrier. Per change 1 it is recordedin #2297, not tabled.
4. Enforcement decided: deferred, as a recorded decision with its own trigger
Row 3 asks whether this repo's
*-gateCI pattern should enforce adoption. No gate is built,and the reason is a finding rather than a preference:
The candidate check §Enforceability already names — flag any
Verified <date>line or row whosesurface states no trigger — would not have caught #2207, the case that prompted the question.
That surface carried no stamp at all, so a stamp-anchored grep had nothing to match on. The named
check is shaped for a half-conforming record; the failure that actually ships is the
zero-part one. The existing named-not-built check and its own build trigger are left unchanged.
The zero-part shape has no deterministic check available: deciding whether a sentence restates an
upstream-owned specific — as against an in-repo fact or ordinary prose — is a judgment about
meaning, reasoning-only under the tiers doc. A harness-vocabulary grep (
PostToolUse,${CLAUDE_*},settings.json) fires on every correct citation and in-repo mention alike, and a gatewhose false-positive rate forces routine suppression trains authors to bypass it — worse than no
gate, because it converts a real signal into noise with an approved silencer.
Recorded as the doc's own second record kind with a basis and an event trigger — a third
unstamped carrier reaching
main, or a demonstrated detector needing no suppression list — so thedeferral expires on evidence rather than on a date.
Disposition of all three rows of #2273
architectureto Adoptersupstream-drift1.3.0 → 1.4.0 (minor: additive guidance, per the contract's own versioningrule — no required part, canonical name, or enforceability verdict changed).
Test plan
--check-orderand--check-bumpboth readdocs/conventions/*/CHANGELOG.md, so the conventionchangelog's
## 1.4.0 — 2026-08-12heading form and its ordering are exercised by the run above,not assumed.
The claim in §3 is quoted from
mainrather than recalled:The upstream basis for calling that an upstream-owned specific was re-fetched at rung 1 during this
work —
https://code.claude.com/docs/en/plugins-reference.md, 2026-08-12 UTC,200,text/markdown, 95,338 bytes / 1,314 lines, first heading# Plugins reference, slug confirmedcanonical against
llms.txt, SHA-256f6627de35a3f285d18cf22494843bb328d65e3b867fbc1856865caa47ea3ea64— line 709: "The${CLAUDE_PLUGIN_DATA}directory resolves to~/.claude/plugins/data/{id}/…".Related
architectureper §3)docs/conventions/upstream-drift/20260811-021645-plugin-audit-four-components-and-guard-deadlock-ownership(ledger
I9-021645-four-components.md§ Lane E end)