feat(agent): forge state-transition tools (RIG-3331)

[rigel-mintaka]

This PR is part of a stack containing 6 PRs:

1. main
2. feat(forge): forge state-transition wire arms and provider methods (RIG-3331) #1017
3. feat(server): forge state-transition arms and actor memo (RIG-3331) #1018
4. "feat(agent): forge state-transition tools (RIG-3331)" (this PR)
5. feat(forge): carry the owner-qualified actor handle on the wire (RIG-3326) #1020
6. feat(tools): mint the live-oracle Linear token with app:assignable (RIG-3299) #1021
7. refactor(proto): standardize the PR-number wire field on pr_number (RIG-3561) #1037

Implements T6 of docs/designs/server/compass-forge-state-transition/design.md: the two agent tools. Stacked on #1018.

forge_transition_issue_state and forge_transition_pull_request_state, on the DL-241 single-purpose-tool pattern over the same ForgeBroker seam every existing forge tool uses.

The tool-facing parameter is pull_number, matching every other PR tool in the file, and maps to the proto's pr_number at the request boundary — agent-facing consistency over wire-name symmetry.

Schema semantics follow the record: repo required (<owner>/<name> on GitHub, team key on Linear), state is open or closed, close_reason GitHub-issues-only, workflow_state Linear-only. The PR tool takes no refinement fields — close_reason is a GitHub issue concept, and merge is a separate concern never expressed as a transition.

Tests

Broker round-trips asserting the request arm and its fields, and that the rendered result is the post-transition artifact. Plus schema-rejection tests pinning the portable state domain: merged and a Linear workflow-state name are both real forge states and neither is a legal target.

The three native-tool count tripwires in cli.test.ts move 20 → 22. That is what a tripwire is for — it caught the roster change rather than letting the tools land unnoticed.

Verified: compass-agent:test 684 pass / 0 fail; compass-agent:typecheck clean.

Ledger-impact: none — DL-342/DL-343 landed with the record's freeze in #981.

Review round 1 — resolved

Reviewed by the review agent over the whole stack (high 3, medium 7, low 6).
The core RIG-3331 mechanism (memo ordering, one-shot consume, tenant isolation,
provider methods, Linear resolution, error mapping, recorded-state choice) was
verified correct. All three highs were stack-integration regressions, now fixed:

• Stale base / three generated-file conflicts — rebased the line onto current
  main; every conflict resolved by regenerating (buf + sqlc), never by
  hand-merging a generated file.
• Silent RIG-2616 revert — the stack's generated code predated main's
  SessionError regen (45 -> 0 occurrences). The regen restores it: SessionError
  is back to 45 in go/gen/compass/v1/compass.pb.go and 14 in the agent TS,
  with ownerHandle and the transition arms additive on top.
• Deleted approval-mode assertions (feat(agent): forge state-transition tools (RIG-3331) #1019) — restored the full approvalOf
  loop over all twelve tools (3 reads + 9 writes) with its justification comment,
  rather than the two-tool assertion that replaced it.

Mediums fixed: updated_at/created_at + updated_at_tables entry for
forge_state_transitions (main's RIG-3495 convention, which landed after this
branched) plus a sqlc regen; the single-column FK divergence documented; the
memo coordinate contract documented on rememberTransition; the memo-failure
error now names the forge write that landed; the Linear retry gate narrowed to
the actual staleness signal; workflow-state page truncation now fails loud at
422; the two transition schemas routed through the compassv1 barrel.

Both new provider tests were mutation-proved: widening the retry gate reddens
TestLinearTransitionDoesNotRetryOnNonStaleness200, and removing the truncation
guard reddens TestLinearTransitionRejectsTruncatedWorkflowStatePage.

Gate: moon ci 70 actions, 0 failed against MOON_BASE=origin/main.

The initial forge live-oracle 401s were mint contention, not a defect: the
Linear client_credentials app holds one active token, so five concurrent CI
runs each revoked the previous one's (which is why the last-to-mint PR was
green). Re-run serially, the job passes on every head with no code change.

[linear-code]

RIG-3331

[github-actions]

Compass engineering docs preview: https://compass-forge-rig-3331-tools.compass-eng-docs.pages.dev

Deployed from compass-forge/rig-3331-tools at 54a0ef1.