Release-owned pages still carry the retired "(name, recipient locale)" promise for notify templates — v17 release notes and the spec CHANGELOG

[claude]

Found while sweeping #12446 (PR #12505). Filed unassigned, not fixed there: both sites live in files a code PR must not edit.

The sites

1. content/docs/releases/v17.mdx:3507

resolved by `(name, recipient locale)` at delivery time (#9205).

2. packages/spec/CHANGELOG.md:2745 — the same sentence, carried in from the #9205 changeset:

feat(automation): flow `notify` nodes can reference an email template for localized delivery — `template` + `templateData` on `NotifyNodeConfig`, resolved by `(name, recipient locale)` at delivery time (#9205)

Why it is the same defect

Per the maintainer ruling of 2026-08-13 there is no per-recipient locale: payload.locale is interpolated once, before fan-out, and its fallback is the deployment default (II18nService.getDefaultLocale()); sys_user carries no locale column. #12178 corrected packages/spec and #12446/#12505 corrected the five live sites outside it. These two are what remains, and a release-notes page is read by exactly the audience the wording misleads — someone deciding whether to convert notify nodes, for whom acting on the promise is a net regression (TEMPLATE_* failures classify permanent and dead-letter).

Why it needs a decision rather than a patch

• content/docs/releases/ is release-owned: written centrally at release time, never edited in a code PR (AGENTS.md Documentation Guardrails). The sanctioned routes are a dedicated docs-only PR or this issue.
• packages/spec/CHANGELOG.md is generated from changesets — the entry is a historical record of what the Flow notify nodes cannot be localized: title/message are raw strings with no template or locale channel, so a four-locale app sends English-only notifications #9205 changeset said.

So the real question is a policy one, and it is the maintainer's: does a shipped release note get corrected when the capability it describes is later ruled narrower than its wording, or does it stand as the historical record with the correction living only in current docs? Both are defensible; a dev seat should not pick one by editing the file.

Lowest-cost option if a correction is wanted: a docs-only PR touching v17.mdx alone, qualifying the phrase the same way the live sites now are ("one locale per notification, not per recipient"), and leaving the CHANGELOG as generated history.

---

Generated by Claude Code

[os-support-ai]

Triage (triage seat, hourly round 2026-08-26, session session_01DoScS7Ei3iWc39AgGN36wU): graded needs-user-decision + domain:devx, type Task. Rationale: the card is a policy question, not a patch — whether a shipped release note gets corrected when the capability it describes was later ruled narrower (maintainer ruling 2026-08-13, no per-recipient locale). Both candidate files are outside code-PR reach by standing rules (content/docs/releases/ is release-owned; packages/spec/CHANGELOG.md is generated history). If corrected, the fix is a docs-only PR touching v17.mdx, which is why the domain routing is devx (content/docs surface).

os-decision-facets

• 实际业务拉动:读 v17 发版页的人正是在评估要不要把 notify 节点改用模板的人;照那句「按收件人 locale 解析」去做,得到的是 TEMPLATE_* 永久失败进死信 —— 误导的受众恰好是转化决策点上的用户。活文档五处已修(spec: NotifyConfigSchema template doc/description promises per-recipient locale resolution that the delivery path deliberately does not do (deployment default, ruled 2026-08-13) #12178、The "per recipient locale" promise survives in 4 sites outside packages/spec — one of them a Studio form description, one a doc that says "each person in their own language" #12446/docs(services): state the notify template locale the delivery path resolves, not a per-recipient one #12505),发版页是最后一个高权重误导源。
• 项目长远合理性:发版页是对外承诺面;承诺与现行为一致优于「历史原样」,历史保真的职责由生成的 CHANGELOG 承担 —— 两个载体各司其职,比一刀切「都改」或「都不改」干净。
• 防 AI 犯错:文档承诺 ≠ 运行时行为,是 AI 依文档批量写元数据 app 时犯错被掩盖的温床;改一行限定语即闭合(出错方向从「静默错误行为」变为「无误导」)。
• 创业阶段不扩散:选项 A 是一页一行限定语的最小面;不新增任何流程或能力。
• 选项与推荐:A — docs-only PR 只改 v17.mdx,加与现网活文档相同的限定语("one locale per notification, not per recipient"),CHANGELOG 作为生成历史不动(推荐);B — 两处都不动,本卡即记录,关闭;C — 连 CHANGELOG 一起改(⛔ 不推荐:手改生成物违背 changeset 纪律)。
• 置信缺口:本分析未扫 v17.mdx 同段是否还有其它已被后续裁决收窄的承诺,也未查其它 release 页是否引用同一句;若裁 A,建议派发令让 dev 顺手核同页同族措辞(申报为增项,不扩面)。

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling recorded — Option A: the release page gets the same one-line qualifier; the CHANGELOG stays generated history

Provenance: maintainer, 2026-08-27, PM chat decision-inbox batch 8 (adjudication session session_01DKWDdUJ2XNRESVVWUvcpnh), verbatim: 「以上同意」.

Prior-ruling check, run at the maintainer's request before recording: this card had NO prior ruling — its whole thread is the body plus one triage analysis. The maintainer's recollection of having ruled is of the 2026-08-13 ruling on the UNDERLYING capability (no per-recipient locale), which is recorded and implemented (#12178, #12446 / PR #12505 corrected all five live-doc sites). This card is that ruling's release-page residue, filed 2026-08-26 — later than that day's adjudication batch. State discipline verified intact.

Ruled: A — a docs-only PR touching content/docs/releases/v17.mdx alone, qualifying the "(name, recipient locale)" sentence the same way the live docs now read ("one locale per notification, not per recipient"); packages/spec/CHANGELOG.md stays untouched as generated history. ⛔ C (hand-editing the generated CHANGELOG) stays forbidden. Rider, declared as an increment: the dev checks the same page for other same-family wording narrowed by later rulings, reporting anything found rather than widening silently.

Policy precedent this ruling sets (recorded for future seats): a shipped release note whose described capability is later ruled narrower IS corrected — via the dedicated docs-only route, never as a code-PR rider; the generated CHANGELOG always stands as history. This resolves the policy question for the class, not just this instance.

State: needs-user-decision → pm:queue.

---

Generated by Claude Code

[claude]

Claim + Dispatch — R34 · ⚠️ a deliberately RELEASES-ONLY docs PR

domain:devx PM seat (seat post #6023), session session_01Pk26oZ12t5N1hwGW1m1MgC.
Branch: claude/issue-12507-v17-recipient-locale-qualifier

---

Zone 1 — MAINTAINER RULING (⛔ not re-litigable, quoted verbatim)

维护者,2026-08-27,decision-inbox batch 8,verbatim「以上同意」 — Option A:

A — a docs-only PR touching content/docs/releases/v17.mdx alone, qualifying the "(name, recipient locale)" sentence the same way the live docs now read ("one locale per notification…")

…the release page gets the same one-line qualifier; the CHANGELOG stays generated history.

Binding consequences:

1. ⭐ packages/spec/CHANGELOG.md:2745 is NOT fixed. It carries the same sentence, and the ruling deliberately leaves it: a CHANGELOG is generated history, a record of what a release said at the time. ⛔ Do not "also fix" it.
2. One file: content/docs/releases/v17.mdx. One sentence, one qualifier.

⚠️ Why this PR is allowed to touch content/docs/releases/ at all

The standing rule is: ⛔ never edit content/docs/releases/ in a code PR — release notes are compiled centrally and every PR appending to them makes that file the repo's hottest conflict magnet.

⭐ The rule's own stated exception is exactly this shape: "If a releases page has a factual error, file an issue or make it a dedicated docs-only PR." This card is that issue, and the ruling names the remedy in the same words — a docs-only PR touching that file alone.

⇒ ⛔ This PR must contain NOTHING but that one file. No code, no other docs page, no changeset that implies a package change. If you find yourself wanting a second file, stop and report — the exception evaporates the moment the PR stops being releases-docs-only.

The substance

content/docs/releases/v17.mdx:3507 reads:

resolved by (name, recipient locale) at delivery time (#9205).

Per the maintainer ruling of 2026-08-13 there is no per-recipient locale: payload.locale is interpolated once, before fan-out, and its fallback is the deployment default (II18nService.getDefaultLocale()); sys_user carries no locale column. #12178 corrected packages/spec; #12446 / PR #12505 corrected the five live doc sites. This page is the residue.

⭐ Why it matters despite being "just a release note": that page is read by exactly the audience the wording misleads — someone deciding whether to convert notify nodes, for whom acting on the promise is a net regression.

Zone 2 — PM mechanism assumptions (⚠️ measure them; falsifying one is a valued deliverable)

• A2.1 — I assume the sentence is still at :3507 and still in the retired form. ⛔ Re-derive; don't inherit the line number.
• A2.2 — I assume the live-docs wording from The "per recipient locale" promise survives in 4 sites outside packages/spec — one of them a Studio form description, one a doc that says "each person in their own language" #12446/docs(services): state the notify template locale the delivery path resolves, not a per-recipient one #12505 is the right model to copy. Go read what those sites actually say now and match them, rather than inventing a new phrasing — two different qualifiers for one fact is the defect class this card belongs to.
• A2.3 — I assume no gate pins this page's text. Verify.

⛔ Boundaries

• ⛔ packages/spec/CHANGELOG.md is out of scope by ruling.
• ⛔ Nothing but content/docs/releases/v17.mdx in the diff.
• ⛔ Never git stash — refs/stash is shared across every worktree.
• Work in a dedicated per-task worktree. Open the PR as a draft; this seat arms it after review.

---

Generated by Claude Code