shepherd docs: "fix it, then settle" is impossible — settle takes only declined|filed, and a fix moves the head

[evanharmon1]

Invariant

The documented settle procedure describes only answers settle can actually
record. An agent following it end to end never reaches a command that cannot
accept the disposition it just chose.

Current violation (observed 2026-08-11)

Both AGENTS.md:327-331 and ai/skills/universal/shepherd/SKILL.md:703-704
say to answer the finding "(fix it, decline it with reasoning/evidence, or
file it), then record the disposition" with settle.

Two of those three answers work. Fixing does not:

• settle --disposition accepts only declined|filed; there is no value for
  a fix.
• A fix means a push, which moves the head, which invalidates the cycle the
  state file describes and starts a fresh current-head cycle. settle would
  refuse it anyway — its target must identify the state's own head.

So an agent that fixes a non-thread finding and follows the prose reaches a
command that cannot succeed, having been told it is the way to complete the
cycle. The correct behaviour after a fix is simply to push and let the new
head be reviewed on its own merits.

Found in harmon-init while writing its consumer-facing twin of this text; the
same correction is going into harmon-init's AGENTS.md (both layers).

Verify

rg -n 'fix it, decline it' AGENTS.md ai/skills/universal/shepherd/SKILL.md

Any hit that still leads into a settle invocation without separating the fix
path means this is open.

Acceptance criteria

• Both files separate the fix path (push, new cycle, no settle) from the two dispositions settle records.
• Neither file presents settle as the completion step for a finding that was fixed.