docs: scope the rollout gate to consumers below the floor (#510)

Rebasing onto main brought in #511, which drops a declaration whose phase sits
above every phase the evaluating binary can name instead of failing the whole
response. Two statements written before it were left false: docs/sbom.md said
Evaluate returns an error and no tasks whenever a consumer cannot represent the
phase, and docs/effective-inputs.md said such a phase fails the whole response
rather than being skipped.

Both are now scoped to the consumers the gate is actually about, and the reason
the floor does not move is stated: a core that cannot name phase 9 predates the
image_sbom capability field and therefore predates #511 as well, so it has no
skip; a core that can name the phase but carries the old validKey bound does not
qualify for skipping either, since the phase is not above what it knows, so it
takes the loud rejection. #511's protection is prospective — it covers phases
added after TASK_PHASE_IMAGE_SBOM, not this one.

The test this branch previously added is gone from its history as part of the
same rebase. It asserted the error #511 deliberately removed, and #511's
TestNewerPhaseKeepsDiscovery covers the surviving contract more thoroughly,
including the malformed and representable-but-unrequested cases that still fail
loudly.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: antoinetoussaint-byte

docs/effective-inputs.md

@@ -10,10 +10,12 @@ scheduling, evidence persistence and result storage are separate consumers.
 
 1. Obtain `AgentInformation.validation` and call `ciinputs.Required`. For legacy
    validation advertisements, retain the existing RPC capability probes and
-   supply their resulting phase/suite inventory explicitly. A capability whose
-   phase this core cannot represent fails the whole response rather than being
-   skipped, so advertising one carries a version floor on every evaluating
-   consumer: see [Advertising the capability](sbom.md#advertising-the-capability).
+   supply their resulting phase/suite inventory explicitly. A declaration whose
+   phase sits above every phase this core can name is dropped and the rest keep
+   discovery, but a phase it can name and does not accept still fails the whole
+   response, so advertising a capability carries a version floor on every
+   evaluating consumer: see
+   [Advertising the capability](sbom.md#advertising-the-capability).
 2. Bind a snapshot token to source state, the dependency graph, requested task
    invocation and resolved execution context. Call `ciinputs.Discover` for both
    reference and candidate snapshots. The agent inspects `revision`, or the

docs/sbom.md

@@ -208,20 +208,28 @@ agent only advertises over the wire; the consumer that calls
 `Agent.GetEffectiveInputs` and runs `ciinputs.Evaluate` is what has to
 understand the phase, and it can be running an older core than the agent does.
 
-A consumer rejects the phase whenever its own `validKey` bound sits below
-`TASK_PHASE_IMAGE_SBOM`. A core reaches that state two ways — it predates the
-`image_sbom` capability field, or it carries the field but predates the raised
-bound — and the difference does not change the outcome. `validKey` guards both
-the required-task inventory and every returned declaration, so the rejection
-lands on whichever side reaches it first. Neither is fixable from the request
-side: such a consumer cannot represent the phase at all.
-
-The outcome is not "image SBOM is skipped". `Evaluate` returns an error and no
-tasks, so the agent's whole response is discarded and every other phase — lint,
-compile, test — loses effective-input discovery with it. This is a hard error,
-distinct from the conservative fallback a consumer uses for an `Unimplemented`
-RPC or an unrecognized response: there, tasks come back marked conservative and
-uncacheable; here there is nothing to come back.
+A consumer below the floor rejects the phase because its own `validKey` bound
+sits below `TASK_PHASE_IMAGE_SBOM`. A core reaches that state two ways — it
+predates the `image_sbom` capability field, or it carries the field but predates
+the raised bound — and the difference does not change the outcome. `validKey`
+guards both the required-task inventory and every returned declaration, so the
+rejection lands on whichever side reaches it first. Neither is fixable from the
+request side: such a consumer cannot represent the phase at all.
+
+For those consumers the outcome is not "image SBOM is skipped". `Evaluate`
+returns an error and no tasks, so the agent's whole response is discarded and
+every other phase — lint, compile, test — loses effective-input discovery with
+it. That is a hard error, distinct from the conservative fallback used for an
+`Unimplemented` RPC or an unrecognized response: there, tasks come back marked
+conservative and uncacheable; here there is nothing to come back.
+
+Current core no longer fails that way, and the difference is prospective only.
+Since the fix for unrepresentable phases, a consumer drops a declaration whose
+phase sits above every phase it can name and keeps discovery for the rest. That
+protects consumers from phases added *after* `TASK_PHASE_IMAGE_SBOM`; it does
+nothing for this one, because every core that mishandles phase 9 predates that
+fix. A core that knows the phase but not the raised bound does not skip it
+either — it can name the phase, so it takes the loud rejection instead.
 
 An agent that serves image scope may therefore advertise `image_sbom` only once
 every consumer that evaluates it runs a core whose `validKey` accepts the phase: