gh --json vocabulary rule covers subcommand-to-subcommand transfer, but 22 of 25 real failures come from REST/GraphQL surfaces

[devantler]

🤖 Generated by the Agent Improver

Evidence

Measured in a consuming deployment over the 7 days to 2026-09-04T22:00Z (1851 transcripts, 1725
tool-error records): Unknown JSON field is 27 records across 13 sessions in 12 worktrees, and
gh rejects the entire --json request on one unknown field — so each is a read that returned
nothing at all.

#177's rule is in force and reached that consumer's pin on 2026-09-01. The residual is not random:

count	field	passed to	where the name is genuinely valid
20	path	gh run list	REST actions/runs, gh workflow list, gh search code
2	isInMergeQueue	gh pr view	GraphQL
3	headRefName	gh search prs	gh pr view

Only the third row is transfer between gh subcommands. The dominant shape — 22 of 25 real
occurrences — is transfer from a different API surface onto a gh --json subcommand.

Why the current wording does not cover it

Both this definition and the consuming contract say never transfer a field name between
subcommands. A REST or GraphQL surface is not a subcommand, so the rule reads as silent on the
shape that actually dominates — and the surveyor's own default-branch helper legitimately consumes
the REST actions/runs payload, where path and created_at are real. That is exactly where the
name is learned before it is mis-spent on gh run list.

The cost is not one lost field. In the measured window, 8 of 10 post-rollout failures were a single
gh run list --json …,path,… fanned across 8 repositories in one sweep — an entire default-branch
breakage pass returning nothing for every repository, and reading as "no evidence" rather than as an
error.

Controls (verified live):

• gh run list --limit 2 --json name,path → rc=1, Unknown JSON field: "path"
• gh api "repos/<o>/<r>/actions/runs?per_page=3" --jq '.workflow_runs[]|{name,path}' → rc=0, returns .path
• gh pr view … --json isInMergeQueue → rc=1; gh search prs … --json headRefName → rc=1

Expected behaviour

The vocabulary rule names the cross-surface case explicitly, so a field learned from REST or
GraphQL — including from a helper payload this definition itself prescribes — is validated against
the exact gh subcommand's own vocabulary before the call is spent.

Acceptance criteria

• The bullet forbids transfer from REST/GraphQL surfaces as well as between subcommands.
• path and created_at are called out where the definition points at the actions/runs payload,
  since that is where the confusion originates.
• A validator assertion pins the widened wording.

Consumer-side context: the same rule was missing entirely from that deployment's loaded surveyor
overlay, tracked separately as devantler-tech/monorepo#3207. This issue is the generic half.

Rough size: S.