Problem/Motivation
The --format=llm envelope is the agent-facing surface, and an agent has only the bytes in the report — no memory of what command produced it. Reviewing the current envelope from that consumer's seat found three defects:
- A category-filtered run is indistinguishable from a full run.
site-doctor:check entropy --format=llmemits an envelope with no scope marker: same keys,exit_code: 0, emptychecks_disabled. An agent reads partial coverage as clean full coverage — the same "absence of a finding must never read as a pass" rule the envelope already honors for disabled checks, unhandled for filtered runs. _meta.severity_semanticsmisleads on both ends:ok: "clean pass"presents inventory facts (a runtime override exists, a workflow is declared) as endorsements, andinfo: "advisory, no action required"tells an agent to ignore exactly the findings that carry remediation links._meta.exit_codesis a positional array — the code-to-meaning mapping is implicit in array index, a cheap misindexing hazard.
Steps to reproduce
- Run
drush site-doctor:check --format=llm --no-storeanddrush site-doctor:check entropy --format=llm --no-store. - Diff the two envelopes: nothing in the second says it covered one category.
Proposed resolution
- Top-level
scopefield:"full", or the requested category on filtered runs — plus a_meta.scopeline stating that a scoped report says nothing about checks outside it. Mirrors the stored run's complete/partial distinction. _meta.severity_semanticsrewording:ok= "inventory fact — records what exists; neither a problem nor an endorsement";info= "advisory — worth attention, never gates"._meta.exit_codesbecomes an object keyed by the literal exit code.
All three are additions or wording changes inside the llm format only; schema_version bumps per the alpha stability policy if reviewers judge the scope key addition to warrant it. The envelope conventions established here carry into the stored-history read commands (#3608643: Add read commands for stored results and changes — see the consumer-review comment there for the full findings list, including design inputs that only apply to that future envelope).
Remaining tasks
- Implement + kernel tests (scope field on filtered vs full runs; _meta wording assertions).
- Decide whether
scopewarrants a schema_version bump (proposed: yes, additive but meaning-bearing).
User interface changes
None — llm format output only.
API changes
New scope key and reworded _meta entries in the llm envelope.
Data model changes
None.
Issue fork site_doctor-3608884
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
Comments
Comment #3
amangrover90 commentedComment #5
amangrover90 commented