docs(ledger): correct the DL-241 forge toolset count to twelve (RIG-3774)

[rigel-mintaka]

Fixes RIG-3774. In-place amendment per Matt.

The count was wrong in a row that says its count is load-bearing

DL-241 recorded ten tools and enumerated ten. createForgeTools in packages/compass-agent/src/forge.ts ships twelve — the two missing are forge_transition_issue_state and forge_transition_pull_request_state, which arrived with DL-342 / RIG-3331 (PR #981, my lane) without the row being refreshed.

That matters because of DL-241's own closing clause:

the tool-count claim is load-bearing for future toolset-refresh rows

A future refresh diffing against "ten" starts from a wrong base.

A stale caveat was shipping to agents at runtime

This is the part worth reviewing closely, because it is a behaviour change, not a doc edit. SUBSCRIBE_RULE is interpolated into both the forge_subscribe and forge_unsubscribe descriptions, and it read:

Change-notification subscriptions are NOT YET WIRED: the call returns unimplemented until the notification lane lands. The tool exists for surface stability and should not be relied on yet.

Both arms persist now: subscribeForge calls store.EnsureAgentForgeSubscription and returns a real subscription id, unsubscribeForge calls store.DeleteAgentForgeSubscription (both in go/server/forge.go). So every agent was being told in its tool schema not to rely on a working feature. SUBSCRIBE_RULE now describes what a subscription actually does.

No test pinned the old wording. Three forge.test.ts assertions contain "subscription writer not yet wired", but that is a server-returned error string the test injects to exercise the in-band error rendering — generic to the error path, unaffected.

Also corrected

• docs/designs/agent/compass-agent-forge-tools/design.md: Status: Active with both tasks unchecked despite T1 and T2 being fully built and tested — now checked; ten→twelve throughout, including the § heading the ledger anchor targets; the transition pair added to Decision 2's name list; a landed-since note appended under Decision 3 (the ratified Matt ruling text is preserved, not rewritten).
• The proposed-row quote in § Ledger-impact now matches the landed row.
• The ForgeCallRequest arm range: the record said "arms 2–11"; the oneof is 2–11 plus 14–15 (verified in proto/compass/v1/agent_gateway.proto).

Left alone deliberately: one "ten precise JSON Schemas" in a rejected alternative (a historical argument about a multiplexed tool, not a claim about what shipped), and apps/eng-docs/src/content/docs/designs/DECISIONS.md, which is gitignored build output per apps/eng-docs/.gitignore and regenerates.

Verification

design-ledger-gate:check OK (329 rows, 137 record headers valid); bun test packages/compass-agent/src/forge.test.ts 57 pass / 0 fail; biome clean on the changed file; union moon ci 31/31 (BASE fe5c401d, HEAD b5549c06), 0 failures.

[linear-code]

RIG-3774

[trunk-io]

😎 Merged successfully - details.

[github-actions]

Compass engineering docs preview: https://compass-forge-rig-3774-dl241.compass-eng-docs.pages.dev

Deployed from compass-forge/rig-3774-dl241-toolset-count at da58e57.

Changed pages:

• docs/designs/DECISIONS.md
• docs/designs/agent/compass-agent-forge-tools/design.md
• packages/compass-agent/AGENTS.md

[rigel-mintaka]

Review findings addressed — both mediums fixed, plus the two stale-count lows. Second commit 2c1d2594, additive.

The catch that mattered: my sweep missed the file I was editing

forge.ts's own header still read "ten native tools" (line 2) and "TWO SUBSCRIPTION TOOLS SHIP DORMANT ... CodeUnimplemented stubs" (lines 36-41) — directly contradicting the SUBSCRIBE_RULE I rewrote 500 lines below it in the same file. A maintainer reading top-to-bottom would have hit opposite claims about the same feature.

Root cause worth naming: my post-edit verification grepped my own phrasings (Ten tools, NOT YET WIRED) rather than the concepts, so it structurally could not see the original wording. Re-swept case-insensitively on the concepts (ten (native )?(forge )?(tools|arms), ship dormant, CodeUnimplemented stub, unimplemented.*until the poll-driver) and found 8 sites, not 2.

Fixed

• packages/compass-agent/src/forge.ts header: twelve tools; the subscription paragraph now describes both arms as live, keeping the design's point that the surface did not change shape when the writer landed.
• packages/compass-agent/AGENTS.md (medium feat: add SubscribeEvents stream and consolidate gRPC-Web transport into @compass/client #2) — the package contract forge.ts's header names as authoritative, stale on both things this PR set out to fix. Ten → twelve, both transition tools added under writes, and the "unimplemented until the writer lands" sentence retired. Their approval: "write" level was verified in forge.ts rather than assumed.
• packages/compass-agent/src/compassv1.ts barrel comment: ten → twelve forge arms.
• The prescriptive createForgeTools docstring inside the design record's T2 code block.

Left deliberately, with reasons

• One "ten precise JSON Schemas" in a rejected alternative — a historical argument about a multiplexed tool, not a claim about what shipped. Editing it would falsify the record's own reasoning.
• apps/eng-docs/src/content/docs/designs/DECISIONS.md: gitignored build output per apps/eng-docs/.gitignore, regenerates.

On the review's no-over-promise check

Confirmed independently before rewriting SUBSCRIBE_RULE: subscribeForge persists via EnsureAgentForgeSubscription and returns a real id, unsubscribeForge deletes via DeleteAgentForgeSubscription, neither is CodeUnimplemented. The old text told every agent a working feature "should not be relied on yet", which is the defect direction that actually costs something — an agent steered off a live capability.

Verification

bun test forge.test.ts cli.test.ts 164 pass / 0 fail; biome clean on both changed .ts files; design-ledger-gate:check OK (329 rows, 137 headers); union moon ci 31/31 at 2c1d2594.

One note on the submit: the gate log showed a compass-ui:visual-gate failure that was not from this PR — the diff contains zero UI files, and re-running compass-ui:visual-gate on the same tree passed 11/11. The actual submit blocker was a divergent jj change id (a jj describe twin), since abandoned; the stale log was left over from an earlier run.

[rigel-mintaka]

Rebased onto 865287cb — conflict resolved, rollup green at da58e574.

main moved under this branch and #1207 (RIG-3580, comment trimming) rewrote the exact two comment blocks I was editing — forge.ts's header and compassv1.ts's barrel note. Both of my hunks landed inside prose that no longer exists.

Resolution kept main's trimmed wording and re-applied only the semantic delta on top: ten → twelve, and dormant → live. Taking my side wholesale would have silently reverted RIG-3580's trim of those same comments — the conflict was a genuine two-sided one, not a stale-branch artifact.

Main still carries both stale claims in the new shorter text (ten native, TWO SUBSCRIPTION TOOLS SHIP DORMANT ... CodeUnimplemented stubs), so this PR is still needed — verified against origin/main after fetching, not assumed.

One more site the rebase surfaced

Re-sweeping post-rebase found a miss the earlier pass had not: the design record's prescriptive spec of the subscribe tool guidance still dictated the old string — "subscriptions are NOT YET WIRED ... should not be relied on yet". That is the spec for the very SUBSCRIBE_RULE this PR rewrote, so leaving it would have told the next implementer to put the wrong text back. Now describes what a subscription does, and why it carries no scope-discipline line (account-keyed row, not a repo artifact).

Left alone, deliberately

forge.test.ts's "surfaces the server's in-band unimplemented as a thrown failure" test. It reads stale, but the message is supplied by FakeTransport in the test body — it asserts in-band error rendering, which is still correct and still worth covering whatever the server arms do.

Gates at da58e574

bun test forge.test.ts cli.test.ts 164 pass / 0 fail; biome clean; design-ledger-gate:check OK (331 rows, 138 headers — main gained two while I was in review, no collision with mine); union moon ci 31/31 vs 865287cb; CI rollup=SUCCESS.

Mergeable, out of draft, awaiting approval + enqueue.