shepherd: ticking deferred findings re-triggers edit-gated checks, so the gate can pass on a stale check read

[evanharmon1]

Invariant

The readiness gate's conditions must all hold for the same head at the
same moment. An action the gate requires must not invalidate a condition
the gate already checked.

Current violation (observed 2026-08-12)

Two gate conditions are in tension, and nothing in the procedure orders them:

• "Every ## Deferred findings entry is ticked with its disposition" — satisfied
  by editing the PR body.
• "Required CI checks have concluded successfully" — invalidated by editing the
  PR body, wherever a workflow is gated on pull_request types: [edited].

Editing the body fires pull_request edited, which re-runs any edit-gated
workflow. In evanharmon1/harmon-init that is release-content-guard.yml
(the guard check). So the very edit that satisfies the deferred-findings
condition puts the checks condition back to pending.

Observed on evanharmon1/harmon-init#808, in this order:

1. checks verified green — 11/11 SUCCESS
2. readiness-gate.sh check → fail: deferred-no-outcome
3. PR body edited to record the dispositions
4. readiness-gate.sh check → fail: checks-pending: guard

Step 4 is the gate working. The hazard is the ordering that avoids it by luck:
an agent that runs the gate, then ticks the body, then promotes on the
earlier pass would promote against a check read that its own edit invalidated.
Nothing in SKILL.md says which order to use, and the intuitive order — verify
everything, then tidy the body, then promote — is the unsafe one.

Promotion is a one-way door (it notifies CODEOWNERS and gh pr ready --undo
cannot unsend that), so this is worth ordering explicitly rather than leaving
to whichever sequence an agent happens to pick.

Distinct from #276, which is about promotions happening outside the gate's
control; this is a promotion that goes through the gate on a stale read.

Verify

grep -rn 'types:.*edited' .github/workflows/     # in the target repo
grep -n 'readiness gate' .claude/skills/shepherd/SKILL.md

Any edit-gated workflow plus a SKILL.md that does not order body edits before
the gate run means the hazard is live. Resolved when the procedure states the
ordering.

Acceptance criteria

• SKILL.md states that PR-body edits must settle before the readiness gate is run
• The reason is given — pull_request edited re-triggers edit-gated workflows — so the rule is not cargo-culted
• Any body edit made after a gate pass requires a fresh gate run before gh pr ready
• The guidance is consistent with the checks condition treating an unconcluded check as indeterminate, never a pass

Found while doing evanharmon1/harmon-init#808 — filed here because this repo
owns the shepherd skill and its readiness gate; harmon-init only vendors them.

[evanharmon1]

Second occurrence, and a stronger one: I hit this on the very next PR after
filing it (evanharmon1/harmon-init#816), having written the issue myself
hours earlier. Knowing about it did not prevent it.

Both halves of the issue fired, in sequence:

1. The per-line outcome requirement. The gate rejected three entries with
deferred-no-outcome, because ordinary markdown wrapping split the outcome
from its reference:

- [x] `session-end-archive.sh` (corrupt archive never repaired) — filed as
      evanharmon1/harmon-devkit#439. `gzip -l` on a corrupt archive fails …

Reads as complete to a human; matches nothing per-line. Fixed by joining:

- [x] `session-end-archive.sh` (corrupt archive never repaired) — filed as evanharmon1/harmon-devkit#439. …

This is the same failure I hit on evanharmon1/harmon-init#808 with
**fixed in\n 02125fd**, so it is not specific to filed as — any
outcome token can be separated from its argument by a line break.

2. The body edit re-triggered the edit-gated check. Editing the body to
fix (1) put guard back to pending, so the gate then had to wait on a check
that my own fix invalidated. Ordering the edits before the gate run avoids it,
which is what this issue asks for.

Worth noting the interaction: (1) forces a body edit late in the process,
which then triggers (2). They compound rather than being independent.

Suggests the fix has two parts:

• state the single-line constraint where entries are authored (the deferred-P2
  format in AGENTS.md / the shepherd skill), not only in the gate that
  rejects them
• have the gate's failure detail say why — "outcome must be on the same line
  as the tick" — rather than only listing the offending entries. The current
  message is accurate but gives no hint that wrapping is the cause; I had to
  infer it both times.