state-hub/docs/decision-contest-convention.md

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:

   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.