fix(agentic-engineering): forbid transferring a gh --json field name from a REST or GraphQL surface

.claude-plugin/marketplace.json

@@ -27,7 +27,7 @@
     {
       "name": "agentic-engineering",
       "description": "The autonomous engineering system for repository portfolios — engineer, read-only surveyor, and meta-engineer agents; portfolio, product, spend, and improvement workflows; cross-tool instruction architecture and skill discovery; configured by the consumer AGENTS.md",
-      "version": "4.4.24",
+      "version": "4.4.25",
       "source": "./plugins/agentic-engineering"
     },
     {

.github/plugin/marketplace.json

@@ -27,7 +27,7 @@
     {
       "name": "agentic-engineering",
       "description": "The autonomous engineering system for repository portfolios — engineer, read-only surveyor, and meta-engineer agents; portfolio, product, spend, and improvement workflows; cross-tool instruction architecture and skill discovery; configured by the consumer AGENTS.md",
-      "version": "4.4.24",
+      "version": "4.4.25",
       "source": "./plugins/agentic-engineering"
     },
     {

plugins/agentic-engineering/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agentic-engineering",
   "description": "The autonomous engineering system for repository portfolios — engineer, read-only surveyor, and meta-engineer agents; portfolio, product, spend, and improvement workflows; cross-tool instruction architecture and skill discovery; configured by the consumer AGENTS.md",
-  "version": "4.4.24",
+  "version": "4.4.25",
   "author": {
     "name": "devantler-tech",
     "url": "https://github.com/devantler-tech"

plugins/agentic-engineering/agents/portfolio-surveyor.agent.md

@@ -55,10 +55,15 @@ prefix, or a repository.
 - **Every `gh --json` vocabulary is local to its subcommand.** Use the exact literal field lists
   prescribed by this definition. Before any ad hoc JSON read, run that same subcommand with bare
   `--json` and validate every requested field against the vocabulary it returns; never transfer a
-  field name between subcommands. The bare diagnostic intentionally exits nonzero after listing its
-  fields; treat a present vocabulary as successful discovery. If the vocabulary is missing or
-  malformed, or the validated read fails, mark the affected evidence `QUERY-UNKNOWN` and report the
-  query error — never translate it to an empty result.
+  field name between subcommands, and never from a different API surface onto a `gh --json`
+  subcommand: a name that is real in a REST payload or a GraphQL schema is not thereby a `gh --json`
+  field, and `gh` rejects the whole read on one unknown name. The default-branch classifier this
+  definition prescribes consumes the REST `actions/runs` payload, where `path` and `created_at` are
+  genuine — neither is a `gh run list --json` field, and that is exactly where the confusion
+  starts. The bare diagnostic intentionally exits nonzero after listing its fields; treat a present
+  vocabulary as successful discovery. If the vocabulary is missing or malformed, or the validated
+  read fails, mark the affected evidence `QUERY-UNKNOWN` and report the query error — never
+  translate it to an empty result.
 - **Every forge read is one command in one call.** The read-only guard refuses on shape before it
   ever inspects intent: output redirection, `;`, `&`, `&&`, a newline, command substitution, and any
   leading program that is neither a forge command nor a reviewed helper this definition names are all

plugins/agentic-engineering/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agentic-engineering",
   "description": "The autonomous engineering system for repository portfolios — engineer, read-only surveyor, and meta-engineer agents; portfolio, product, spend, and improvement workflows; cross-tool instruction architecture and skill discovery; configured by the consumer AGENTS.md",
-  "version": "4.4.24",
+  "version": "4.4.25",
   "author": {
     "name": "devantler-tech",
     "url": "https://github.com/devantler-tech"

plugins/agentic-engineering/resources/provider-neutral.desired-state.json

@@ -60,7 +60,7 @@
       "portfolio-surveyor": {
         "enabled": true,
         "mode": "delegated-read-only",
-        "definitionSha256": "1ba8c5008f05720134182363be645a3be0108cc9f4f1a8f9f42601a662c2dcfa"
+        "definitionSha256": "ca63b9eed7a9bea00d1acc70b0f6f883c8d9af916a555960d36e091028ebd0d7"
       },
       "agent-improver": {
         "enabledWhen": "Both optional consumer contract sections are present",

scripts/validate-manifests.sh

@@ -449,7 +449,7 @@ validate_desired_state_resources() {
   local improver_self_observation_contract="The Agent Improver is one of its own measured subjects. Keep the Agentic Engineer execution plane and every Agent Improver observation plane in separate scorecards; never average them together or let one hide the other's regression. Measure observer coverage, calibration, hypothesis discipline, verified intervention effectiveness, reliability, efficiency, and verified rollout throughput. Outcome throughput counts only verified terminal outcomes; productive sessions and work advanced are execution-flow indicators, never improvement verdicts. Observation-plane verdicts require independent computation from an immutable or read-only source, or verification by a separate eligible run or instance; the same Improver's unsupported assertion is UNKNOWN, never success. Activity such as PRs, metrics, reports, and memory writes is not improvement. A version-controlled self-referential change requires an independent green current-head review with all findings resolved. A runtime-local self-referential change requires an independently performed post-dispatch read-back against the recorded pre-change baseline through the consumer's declared runtime verification mechanism; the writer's immediate read-back is not independent verification. Both paths require unchanged companion floors for every applicable scorecard parameter and a later eligible evidence window."
   local improver_research_fallback_contract="No-change fallback is research, never idle. After scoring and diagnosis, when no telemetry-backed or direct-maintainer-directed improvement is actionable, run one bounded state-of-the-art research pass before reporting. Research is discovery evidence, never authorization or proof that the current system failed. Use current primary sources, compare the current baseline capability, and route a deduplicated product or operations opportunity as an ENGINEER-CANDIDATE and an agent-process or measurement opportunity as an IMPROVER-CANDIDATE. Research alone never authorizes or ships a change. A null result is RESEARCH-NO-CANDIDATE with the topic cursor advanced; research activity is not a terminal improvement outcome."
   local money_guardrail="Spend stewardship never moves money: prepare the financial decision, route it to the maintainer's declared private channel, and keep private financial data out of every public artifact."
-  local portfolio_survey_json_vocabulary_contract="**Every \`gh --json\` vocabulary is local to its subcommand.** Use the exact literal field lists prescribed by this definition. Before any ad hoc JSON read, run that same subcommand with bare \`--json\` and validate every requested field against the vocabulary it returns; never transfer a field name between subcommands. The bare diagnostic intentionally exits nonzero after listing its fields; treat a present vocabulary as successful discovery. If the vocabulary is missing or malformed, or the validated read fails, mark the affected evidence \`QUERY-UNKNOWN\` and report the query error — never translate it to an empty result."
+  local portfolio_survey_json_vocabulary_contract="**Every \`gh --json\` vocabulary is local to its subcommand.** Use the exact literal field lists prescribed by this definition. Before any ad hoc JSON read, run that same subcommand with bare \`--json\` and validate every requested field against the vocabulary it returns; never transfer a field name between subcommands, and never from a different API surface onto a \`gh --json\` subcommand: a name that is real in a REST payload or a GraphQL schema is not thereby a \`gh --json\` field, and \`gh\` rejects the whole read on one unknown name. The default-branch classifier this definition prescribes consumes the REST \`actions/runs\` payload, where \`path\` and \`created_at\` are genuine — neither is a \`gh run list --json\` field, and that is exactly where the confusion starts. The bare diagnostic intentionally exits nonzero after listing its fields; treat a present vocabulary as successful discovery. If the vocabulary is missing or malformed, or the validated read fails, mark the affected evidence \`QUERY-UNKNOWN\` and report the query error — never translate it to an empty result."
   local portfolio_survey_recovery_contract="**Mandatory-query recovery is bounded and resumable.** Process mandatory surfaces in deterministic batches of at most eight candidates. Treat every successful batch as an immutable checkpoint. On failure, partition only the failed batch into two deterministic contiguous halves (the first half gets the extra candidate when the count is odd), execute both halves, and recursively partition each failed half until only failed singleton candidates remain. Never re-run a successful half. Continue unaffected batches and mark only failed singleton candidates \`QUERY-UNKNOWN\`; never discard completed evidence or collapse it into portfolio-wide \`QUERY-UNKNOWN\`."
   local portfolio_survey_global_failure_contract="Known candidate-independent failures—exhausted query budget, invalid authentication, or a forge-wide transport failure—must fail the affected mandatory surface closed immediately without splitting. Partition only candidate-specific, shape-specific, or partial failures."
   local portfolio_survey_head_revalidation_contract="Before emitting any PR disposition, re-read every checkpointed candidate's current head OID. If it changed, discard only that candidate's stale checkpoint and refresh its mandatory evidence; if refresh fails, emit \`NEEDS-FIX\` with \`QUERY-UNKNOWN\`. Never emit \`CLEAR\`, \`REVIEW-READY\`, or \`MERGE-READY\` from evidence bound to a superseded head."

scripts/validate-manifests.test.sh

@@ -669,7 +669,7 @@ description: Fixture read-only surveyor.
 ---
 Fixture surveyor.
 
-**Every `gh --json` vocabulary is local to its subcommand.** Use the exact literal field lists prescribed by this definition. Before any ad hoc JSON read, run that same subcommand with bare `--json` and validate every requested field against the vocabulary it returns; never transfer a field name between subcommands. The bare diagnostic intentionally exits nonzero after listing its fields; treat a present vocabulary as successful discovery. If the vocabulary is missing or malformed, or the validated read fails, mark the affected evidence `QUERY-UNKNOWN` and report the query error — never translate it to an empty result.
+**Every `gh --json` vocabulary is local to its subcommand.** Use the exact literal field lists prescribed by this definition. Before any ad hoc JSON read, run that same subcommand with bare `--json` and validate every requested field against the vocabulary it returns; never transfer a field name between subcommands, and never from a different API surface onto a `gh --json` subcommand: a name that is real in a REST payload or a GraphQL schema is not thereby a `gh --json` field, and `gh` rejects the whole read on one unknown name. The default-branch classifier this definition prescribes consumes the REST `actions/runs` payload, where `path` and `created_at` are genuine — neither is a `gh run list --json` field, and that is exactly where the confusion starts. The bare diagnostic intentionally exits nonzero after listing its fields; treat a present vocabulary as successful discovery. If the vocabulary is missing or malformed, or the validated read fails, mark the affected evidence `QUERY-UNKNOWN` and report the query error — never translate it to an empty result.
 
 **Mandatory-query recovery is bounded and resumable.** Process mandatory surfaces in deterministic batches of at most eight candidates. Treat every successful batch as an immutable checkpoint. On failure, partition only the failed batch into two deterministic contiguous halves (the first half gets the extra candidate when the count is odd), execute both halves, and recursively partition each failed half until only failed singleton candidates remain. Never re-run a successful half. Continue unaffected batches and mark only failed singleton candidates `QUERY-UNKNOWN`; never discard completed evidence or collapse it into portfolio-wide `QUERY-UNKNOWN`.
 
@@ -959,6 +959,17 @@ sed 's/never transfer a field name between subcommands/field names may be reused
 check_fail "portfolio surveyor must forbid cross-subcommand JSON field reuse" \
   "portfolio-surveyor must validate ad hoc gh JSON fields against the same subcommand" "$d"
 
+# 22 of 25 measured `Unknown JSON field` failures came from a REST or GraphQL surface, not
+# from another subcommand (#190): `path` learned from the classifier's `actions/runs` payload
+# and spent on `gh run list --json`. The cross-surface clause is its own discriminator.
+d=$(fresh); make_desired_state "$d" alpha
+# shellcheck disable=SC2016  # the backticks are literal characters in the pattern
+sed 's/and never from a different API surface onto a `gh --json` subcommand/and freely from any other API surface onto a `gh --json` subcommand/' \
+  "$d/plugins/alpha/agents/portfolio-surveyor.agent.md" > "$d/tmp" \
+  && mv "$d/tmp" "$d/plugins/alpha/agents/portfolio-surveyor.agent.md"
+check_fail "portfolio surveyor must forbid transferring a field name from a REST or GraphQL surface" \
+  "portfolio-surveyor must validate ad hoc gh JSON fields against the same subcommand" "$d"
+
 d=$(fresh); make_desired_state "$d" alpha
 sed 's/never translate it to an empty result/report it as an empty result/' \
   "$d/plugins/alpha/agents/portfolio-surveyor.agent.md" > "$d/tmp" \