close_reason_required on create suggests only pm close, never the --resolution flag that fixes it #885

Summary

When governance.require_close_reason is enabled (the default), a pm create that
declares a terminal status fails with close_reason_required — but every remediation
example in the error tells the caller to run pm close, a different command against an
item that does not exist yet. The affordance that would actually fix the failing command,
pm create --resolution "<summary>", is never mentioned.

The fix is discoverability only: the behaviour is already correct.

Reproduction (pm-cli 2026.8.3)

pm --path .agents/pm init
pm --path .agents/pm --json create --title Probe --type Chore --status closed --description d

Error (abridged):

{
  "code": "close_reason_required",
  "why": "governance.require_close_reason is enabled, so tools must not invent immutable closure evidence.",
  "examples": [
    "pm close <id> \"Done: <what changed and why>\"",
    "pm close <id> --reason \"<closing summary>\"",
    "pm close <id> -m \"<closing summary>\"",
    "pm close <id> --duplicate-of <canonical-id>"
  ],
  "next_steps": [
    "Re-run the terminal transition with a closing summary.",
    "To stop requiring reasons, run: pm config set governance-require-close-reason --policy disabled"
  ],
  "recovery": { "attempted_command": ["...","create","--title","Probe","--type","Chore","--status","closed","--description","d"] }
}

All four examples are pm close <id> forms. There is no <id> yet — the create was
rejected. The two next_steps are "re-run with a closing summary" (with no indication of
which flag does that on create) and "disable the governance policy".

What actually works

pm create already accepts --resolution, and it satisfies the requirement cleanly:

pm --path .agents/pm --json create --title "Retro closed item" --type Chore \
   --status closed --description d --resolution "Work completed before the item was recorded."

{ "id": "pm-qxok", "status": "closed", "changed_field_count": 14,
  "close_reason": "Work completed before the item was recorded." }

Why this matters for agents

Recording already-completed work is a routine agent operation. The error object here is
otherwise excellent — why, required, next_steps, recovery.attempted_command and
provided_fields are exactly what an agent needs. But because the examples array is
keyed to the policy rather than to the command that failed, an agent that hits this on
create is steered away from its own command shape. In practice that costs an exploration
loop — pm close --help, pm create --help, or a two-command create-then-close workaround
— to rediscover a flag the CLI already has. --resolution is also not an obvious name to
search for when the error, the policy and the field are all called reason.

The generic "Re-run the terminal transition with a closing summary" compounds it: it is
true, but it does not name a flag, so it cannot be acted on without a lookup.

Note this is specific to create. On pm update <id> --status closed the pm close
examples are the correct advice, because update genuinely has no reason flag
(--reason there returns unknown_option).

Suggested change

Make the remediation examples context-sensitive to the failing command. When the rejected
command is create, lead with the form that repairs it:

pm create --title "<title>" --type <Type> --status closed --resolution "<closing summary>"

and correspondingly make next_steps[0] name the flag, e.g. "Re-run with --resolution "<closing summary>"" for create and "Close the item with pm close <id> --reason ..."
for a terminal update. The recovery.attempted_command field already carries everything
needed to tell the two cases apart.

A smaller, purely additive alternative: keep the examples as they are but append the
create --resolution form whenever recovery.attempted_command contains create.

Found while upgrading a 20-package extension fleet from 2026.7.29 to 2026.8.3.