publish: classify capture and gh failures so callers stop retrying blind #151

Problem

Over 2026-11-03..08 the publish tool returned 106 gh-failed and 73 payload-unreadable errors, and in every case the next call repeated identical arguments (about half then succeeded). payload-unreadable covers missing file, directory, symlink, size, permission and wrong-cwd resolution alike; gh-failed gives no exit code or category. About 28 further calls failed schema validation without saying which fields the kind needs.

Scope

• Safe subcodes for capture failures: payload-not-found <resolved path>, payload-symlink, payload-not-file, payload-too-large, payload-permission.
• For gh failures: exit code and a whitelisted category from stderr (rate-limit, not-found, auth, validation, network), never raw stderr, plus the advice "retry once for rate-limit/network, otherwise fix the request".
• Validation errors list the required fields for the kind.

Supersedes the mechanism behind #129 (security-advisories failing with opaque gh-failed); that issue keeps its specific endpoint question.

Status

State: Done — Shipped in v2026.11.09
Branch: -
Scope: branch fix/publish-error-classes; planning, GPT implementer after limit lifts
Plan: Capture failures get whitelisted subcodes from error.code (not-found with resolved path, symlink, not-file, permission); gh failures add exit code, a closed-set category matched on bounded stderr and advice, never stderr text; validation errors list required fields.
Delivered: - #162
Remaining: To be confirmed.
Follow-ups: None.