Document interim decision contest convention (STATE-WP-0097-T02)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 356991@bnt-lap001
Assistant-Session: 5d99ea69-ed55-4a1e-8d97-f4f312db247f

docs/decision-contest-convention.md

@@ -0,0 +1,65 @@
+# Contesting a resolved decision (interim convention)
+
+STATE-WP-0097-T02. This is the response to activity-core's suggestion
+ff7d2152-75dd-4a49-8dac-e0ebe7343039. State Hub has no `contested` decision
+status and no `/decisions/{id}/contest` route, and it will not add them. State
+Hub is in retirement. Decisions are file-first work records with repo-manager
+as writer (RMGR-WP-0008). Who may contest a decision is a governance rule.
+A first-class contest state belongs with the-custodian canon and repo-manager.
+Until they adopt one, contests use the existing decision fields.
+
+## When an owner may contest
+
+Only an agent that a resolved decision names as owner or as affected may
+contest it. The only grounds are its own checked-in charter: `INTENT.md`,
+`SCOPE.md` or an ADR that excludes the assigned work. Preference and workload
+are not grounds.
+
+## Steps
+
+1. **Contest.** The owner replies on the thread that relayed the decision:
+
+   ```text
+   CONTEST <decision_id>
+   Charter: <repo>/<file>#<section>[, ...]
+   Conflict: <one sentence>
+   Suggested owner: <agent>        (optional)
+   ```
+
+   The owner does not start the assigned work while the contest is open.
+2. **Re-resolve.** Only the founder or the original decider answers the
+   contest. There are two outcomes:
+   - *Confirm:* the decision stands. The owner amends its charter through an
+     ADR in its own repo, then takes up the work.
+   - *Re-assign:* the decider resolves a **new** decision. Its title or
+     rationale says `supersedes <old decision id>`.
+3. **Link.** The decider sets the old decision to `status: superseded` with
+   `superseded_by: <new decision id>` (`PATCH /decisions/{old_id}`). Without
+   this link the hub keeps showing the old decision as settled. Agents that
+   relay it would then pass on the overturned assignment.
+4. **Update work records.** Repos whose task blocks cite the old `decision_id`
+   update the reference in their files. Fix-consistency propagates the
+   change (C-41).
+
+## Detection
+
+C-43 (`decision-supersession-unlinked`, WARN) flags a resolved decision that
+says `supersedes <id>` when the cited decision is not `superseded` with
+`superseded_by` pointing back to it. The check reports to the repo that owns
+the superseding decision's workplan. It does not fix anything: setting the link
+stays a deliberate act of the decider.
+
+There is no automatic detection of an open contest that nobody has answered.
+A reply containing `CONTEST <id>` is an ordinary message until the decider acts
+on it.
+
+## Worked example (2026-10-13)
+
+- 1c9817ee assigned the publish-grant publisher and its push credentials to
+  activity-core.
+- activity-core declined on thread 25824c97 (reply 5961c59d). Its INTENT
+  excludes repository edits, execution and secret custody.
+- The founder resolved c6f23433, "supersedes 1c9817ee", which assigns the
+  publisher to rein-aharness.
+- The link from 1c9817ee to c6f23433 was missing until set by hand. C-43 now
+  catches this case.