Skip to content

orchestration: re-read a subagent's gating claim from the source before relaying it to a human #431

Description

@evanharmon1

Invariant

An orchestrator relaying a subagent's report to a human is making the claim its
own. Where that claim gates a decision — "checks pass", "the gate passed", "the
finding is fixed" — it must be re-read from the authoritative source before it
is repeated, because the human will act on it and cannot see the subagent's
context.

A subagent can be entirely truthful and still hand up a claim that means
something different one level out.

Current violation (observed 2026-08-11)

During a standardize-repo update run delegated to two subagents, one reported:

task verify, task sync:skills/verify:skills/verify:skills:offline,
assets/verify-applied.sh — all green

Every word was accurate about the agent's local gate. I relayed it to the
maintainer as the PR's verification status. At that moment the PR had three
required checks failing
in CI (e2e, security, verify). The maintainer
was told the work verified clean; it had not.

Nothing in the report was false. "Verified" simply means different things at the
two levels: locally it means one gate on one machine; at the PR it means the
required checks concluded on the pushed head. The orchestrator is the boundary
where that shift happens, and is the only party positioned to notice.

Two related shapes from the same session:

  • A subagent reported "readiness gate: PASS" for a PR whose mergeStateStatus
    was BEHIND — a condition the gate's own definition disqualifies. Relayed
    unchecked, it would have sent a maintainer to a PR that could not merge.
  • A subagent reported "all inline threads have per-thread replies". True — and
    the maintainer still found the PR showing three unresolved conversations
    rendering pre-fix code, because replied and resolved are different states.
    The relay dropped that distinction.

The cost is asymmetric: a wrong "green" spends the maintainer's trust and their
time, while re-reading the source costs one API call.

Verify

# What the orchestrator should re-read before repeating a gating claim:
gh pr checks <n> --repo <owner/repo>
gh pr view <n> --repo <owner/repo> --json headRefOid,isDraft,mergeStateStatus,reviewDecision

Expected failure mode: a subagent report saying "verify green" alongside a
gh pr checks listing with fail rows on the same head.

Acceptance criteria

  • The orchestration guidance states that a subagent claim of the form
    checks pass / gate passed / finding fixed is re-read from the source
    before being relayed to a human.
  • It names the specific substitution to watch for: a local gate result
    standing in for the PR's check status.
  • It notes that "replied" and "resolved" are distinct thread states and a
    relay must not collapse them.
  • The requirement is on the orchestrator, not the subagent — a truthful
    report is not the failure being addressed here.

Related: #429 (a brief that truncates the skill's requirements produces exactly
the report this issue is about) and #305 (the subagent-side obligation to finish
its gate in-turn). This issue is the boundary case neither covers: the agent did
finish its gate, reported it accurately, and the claim still changed meaning on
the way up.

Found while running standardize-repo update mode via subagents across
ponderousdev/omator and ponderousdev/lawnomator-site.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationdomain:platformCI, build, test infra, and tooling in this repo

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions