docs: correct RFC 0002 stale references and migration claims

[omarshahine]

Related: openclaw/openclaw#85954

What Problem This Solves

RFC 0002 is status: accepted, so it is the specification anyone implements
against. Scoping that implementation against current openclaw/openclaw main
turned up four places where the RFC no longer matches the code, one of which
would produce a user-visible regression if followed literally.

• It says the exec builder fences via buildFence. That helper was removed in
  refactor: consolidate markdown code fences, error coercion, and byte-identical helper pairs openclaw#99932. Core now uses formatFencedCodeBlock and
  formatInlineCodeSpan from src/shared/markdown-code.ts.
• Its inventory of approval text surfaces lists three builders and omits
  src/infra/exec-approval-forwarder.ts. That is the path every channel with
  an approval capability but no render adapter uses, which means the RFC omits
  the path actually carrying the problem it describes.
• It claims migration step 1 is behavior-neutral because "the downgrade
  reproduces today's plaintext." That holds only for channels that render
  nothing. Telegram, Matrix, Signal, WhatsApp, Slack, and Discord render the
  subset today, so defaulting them to plaintext would strip formatting they
  currently ship.
• Its step 2 describes moving iMessage to markdown as "wiring the approval
  path to skip the downgrade and reuse the existing converter." The existing
  converter handles bold, italic, underline, and strikethrough but ignores
  inline code and fences, so that step needs converter work first.

Why This Change Was Made

Corrects each of the four against current source and records two implementation
findings that belong in the spec rather than in a reviewer's head.

The migration section is rewritten so the channels that already render declare
approvalText: "markdown" in step 1 alongside the contract, instead of in a
later step. This is the substantive change: it is what keeps step 1 from
regressing six channels, and it is now stated plainly that step 1 is not
behavior-neutral rather than left as a claim a future implementer would
discover was false.

Two additions to the Proposal capture things that are easy to get wrong and
look correct in review:

• The mode must be read through resolveChannelApprovalCapability, not the
  resolveChannelApprovalAdapter projection, which copies a fixed field list
  and returns nothing for auth-only capabilities. Most channels this contract
  is meant to fix are auth-only.
• The downgrade helper wraps the existing IR-based stripMarkdown and pins
  mode: "plain-text" and linkStyle: "label-and-url". The first prevents the
  speech-mode punctuation cleanup from rewriting a shell command inside its own
  fence. The second keeps a link destination visible to the approver, which is
  a security property of an approval prompt rather than a formatting choice.

One question is reopened. Core can enforce the downgrade on the forwarder path,
but the native approval runtime path returns channel-specific payload types
with no shared text field, so channels there honor their declared mode
themselves and a conformance test can only prove a mode was declared, not that
it was obeyed. The alternative is threading an explicit text mode into the two
shared pending-prompt builders. The gap is currently unreachable because every
channel on that path renders markdown, so it does not block step 1, but it
should be settled before any channel on that path declares plaintext.

No change to the accepted design: the canonical subset, the approvalText
capability, the default, and the three previously resolved questions all stand.

User Impact

No user-visible impact. This is specification text.

For implementers, following the RFC as previously written would have regressed
approval prompt formatting on Telegram, Matrix, Signal, WhatsApp, Slack, and
Discord, and would have sent someone looking for a helper that no longer
exists.

Evidence

Every corrected reference verified by reading current openclaw/openclaw main
at 025e6ceee0a:

• src/shared/markdown-code.ts:22,29 — formatInlineCodeSpan,
  formatFencedCodeBlock. buildFence absent; removed in 49cc59b1e88.
• src/infra/exec-approval-forwarder.ts:230,293,299,406 — the omitted fallback
  builders and the buildApprovalRenderPayload dispatch.
• src/channels/plugins/approvals.ts:12,28-44 — the capability resolver versus
  the adapter projection that drops unknown fields and returns undefined for
  auth-only capabilities.
• src/shared/text/strip-markdown.ts:88-105,109 — cleanSpeechText gated to
  mode: "speech", and the stripMarkdown entry point.
• src/infra/approval-handler-runtime.ts:188 — the native runtime factory whose
  TPendingPayload generic prevents a core-side downgrade.
• extensions/imessage/src/markdown-format.ts:147 — extractMarkdownFormatRuns
  covering bold, italic, underline, and strikethrough only.
• Channel declarations counted directly from extensions/*/src/channel.ts:
  fifteen declare approvalCapability; only telegram carries a render
  adapter.

Prose-only change, so no tests or CI beyond the repo's markdown rendering.
Frontmatter keys and the required section set are unchanged, and all lines stay
within the 80-column wrap used by the rest of the document.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: docs: correct RFC 0002 stale references and migration claims This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.