docs: name the canonical docs host in the governed protection examples

[claude]

Fixes #10656

Maintainer ruling, 2026-08-21, verbatim and untranslated:

这个仓的文档站规范 URL 是 https://objectstack.ai

Re-measurement vs the card

Re-grepped the whole tree for docs.objectstack.ai at my HEAD and worked from that, not
from the card's line numbers. The card's counts hold exactly — 5 occurrences across 3
governed paths, no drift, despite the data SKILL.md having been edited since the card was
filed. Only the SKILL.md line numbers moved (the card gave none for that file).

Site	Card	Measured	Disposition
skills/objectstack-data/SKILL.md	3	3 (L898, L916, L937)	fixed
docs/adr/0010-metadata-protection-model.md	1 (:565)	1 (:565)	fixed
docs/adr/0046-package-docs-as-metadata.md	1 (:85)	1 (:85)	kept unchanged — argued below

No other governed surface (docs/adr/**, .claude/**, skills/**, AGENTS.md,
CLAUDE.md) carries the spelling. The remaining tree hits are all outside the register —
CHANGELOG.md history, the three landed .changeset/ entries that describe this very
convergence, and scripts/check-published-readme-links.mjs, which must keep naming the
alias because it is the detector that classifies it.

The host was only half the defect

All four fixed occurrences are the same literal, and a pure host swap would have left
a dead URL behind. The landed changeset canonical-docs-host-in-runtime-strings.md states
the finding in full:

All 29 protection.docsUrl values on the platform's system objects and apps pointed at
/adr/0010-metadata-protection, and /adr/... is not a route on any host: the docs site
mounts content/docs under /docs, docs/adr/ is not published, and no redirect source
lives outside the /docs space. The slug was wrong too — the record is
0010-metadata-protection-model.md.

So the correct target is not a guess — it is pinned three ways by work that has already
landed: the 29 platform sources, the packages/spec/src/shared/protection.zod.ts docblock
example, and the changeset's own reasoning. Every changed line becomes:

docsUrl: 'https://objectstack.ai/docs/references/shared/protection',

Diff discipline held: 4 changed lines, each containing docs.objectstack.ai before and
objectstack.ai after. No prose reworded, no reflowing, no drive-by fixes.

Per-site disposition

1. skills/objectstack-data/SKILL.md ×3 — fixed (the propagating surface)

Three protection blocks in worked examples (sys_user, sys_role, setup.app) that
mirror three real platform files, all three of which already landed on the canonical
literal. This is the surface that travels: the published skill catalog lands in codebases
this repo cannot see, so the skill teaching /adr/0010-metadata-protection would keep
minting a 404 into AI-authored protection blocks long after the source was fixed.

2. docs/adr/0010-metadata-protection-model.md:565 — fixed (a stale quotation)

The card flagged this as possibly quoting the code that #10655 covered. It is: the fenced
ts block at §Phase 4.3 is a verbatim quotation of the SETUP_APP example in
packages/spec/src/shared/protection.zod.ts. Diffing the two blocks, the docsUrl line was
their only divergence — every other byte matched. #10655 closed 2026-08-21T23:57, so the
card's own condition ("it should move with the code, not ahead of it") is satisfied, and
this one line now restores byte-identity with the source it quotes.

This is not a rewording under PD #13: the recorded decision (a protection block carrying
docsUrl) is untouched. Only the illustration was stale, and a stale quotation makes the
ADR misdocument its own implementation.

3. docs/adr/0046-package-docs-as-metadata.md:85 — KEPT UNCHANGED

The card suspected this one describes a past state deliberately. Reading the surrounding
section confirms it. The line sits in §2 Goals & Non-goals → Non-goals:

• Standalone product doc sites (docs.objectstack.ai) — those are
  websites; content/docs/ remains their convention.

Two reasons to leave it:

1. It is not a URL. No scheme, no markdown link, no autolink — the hostname is an
   identifying parenthetical whose job is to say which category of thing is out of scope
   for doc metadata. Nobody follows it or copies it. The ruling governs the canonical docs
   URL; this is not one.

2. It is decision prose. A Non-goals bullet is the ADR's recorded scope boundary, dated
   2026-06-12 — more than two months before the canonical ruling. Prime Directive [WIP] Add Chinese version of the documentation #13:

   An accepted ADR binds until a superseding ADR says otherwise. Reversing a recorded
   decision is itself a decision: it needs a new ADR (or an amended status line on the
   old one), not a changeset that quietly does the opposite.

   Editing the sentence would be silently rewording a decision record for zero user-facing
   effect. The reference also remains unambiguous: the alias still redirects to the apex
   path-preservingly, per the landed changeset.

If the maintainer would rather this line track the canonical spelling too, that is an ADR
amendment and belongs in its own change — not smuggled in under a link fix.

Token budget — skills/** readings

The dispatch requires both readings for any skills/** diff, and this file sits under
check:skills-token-ratchet at ceiling 13817 with zero headroom.

The change is exactly byte-neutral — the two literals are both 56 bytes, so nothing was
spent and nothing was reclaimed:

Reading	Before	After	Net
skills/objectstack-data/SKILL.md (lines)	1210	1210	0
skills/objectstack-data/SKILL.md (bytes)	55265	55265	0
skills/objectstack-data/SKILL.md (tokens)	13817	13817	0
Whole published package, all 11 SKILL.md (bytes)	471666	471666	0
Whole published package (tokens)	117922	117922	0

No prose was deleted to pay for anything, and no ceiling was raised (maintainer-only).

Gates

Derived with node scripts/pm/dispatch-gates.mjs (no path arguments — it takes its own
change set from the merge base), then run. Union re-run on the final commit a85daa8742;
all green:

Gate	Verdict line
check-skills-token-ratchet	✓ check-skills-token-ratchet: 11 published SKILL.md within their ceilings. (objectstack-data 13817 / 13817 (+0))
check-skills-token-ratchet --self-test	✓ check-skills-token-ratchet self-test: 33 cases pass.
check-adr-links	✅ check-adr-links: 551 relative link destination(s) under docs/adr/ resolve
check-adr-anchors (+ self-test)	✓ check-adr-anchors --self-test: 74 assertions…
check-doc-authoring (+ self-test)	✓ doc authoring guard: 389 files clean — no bare metadata literals.
check:doc-formula-expressions (+ self-test)	✓ check:doc-formula-expressions: 22 record-scoped formula example(s) across 416 files / 1447 TS blocks judged clean
check-role-word (+ self-test)	check-role-word: OK, no new occurrences of the reserved word.
check-skill-frame-sync (+ self-test)	✓ check-skill-frame-sync: 4 copies of the decision frame are structurally isomorphic across 3 files
check-skill-compatibility-version (+ self-test)	✓ check-skill-compatibility-version: 11 SKILL.md file(s) reconciled against 78 workspace packages
check:pm-governed-merges	✓ check-governed-merges --self-test: 119 assertions…
check-nul-bytes	check-nul-bytes: OK (scanned 6487 text file(s) … no raw ASCII control bytes).

Governed verdict on the final file list

node scripts/pm/check-governed-merges.mjs --test docs/adr/0010-metadata-protection-model.md skills/objectstack-data/SKILL.md

governed-surface predicate: 2 of 2 path(s) hit the register (5 surfaces, repo-agnostic).
  ⛔  GOVERNED — a human merge is the review record for this PR (#9495 regime).
      No seat flips it ready, enqueues it, or arms auto-merge (AGENTS.md Prime Directive #14).
      One hit governs the whole PR — 「混合 diff 一条命中即整 PR 分叉」; proportion is not a question.
      docs/adr/** ×1 — architecture decision records
        - docs/adr/0010-metadata-protection-model.md
      skills/** ×1 — the published skills catalog
        - skills/objectstack-data/SKILL.md

This PR stays a draft and is merged by the maintainer by hand. Not flipped ready, not
enqueued, no auto-merge. Assigned to os-zhuang for review (review-request fails on a
self-authored PR).

Changeset

None, by the changeset gate's own prescription. pr-automation.yml lists the paths that
release nothing — .github/, .claude/, skills/, docs/, content/ — and its
error text says such a PR takes the label rather than a file:

This PR adds no changeset. If it releases nothing (including any skills/** change — see
#5947), apply the skip-changeset label

skills/ is not a workspace member and no package's files field ships it, so nothing here
publishes. The skip-changeset label is applied additively (POST, never a wholesale PUT)
and read back — the size labeler's PUT is documented to race it away.

---

Generated by Claude Code

[os-zhuang]

ACCEPT — session 757f0dc0-5dae-51d7-9053-c15c57ebfe3b(派发席,卡 #10656)。

全量 diff 复核:2 文件 4 行,全部是同一 protection.docsUrl 字面量 https://docs.objectstack.ai/adr/0010-metadata-protection → https://objectstack.ai/docs/references/shared/protection,零 prose 改动。三点验收判断:

1. 不止换 host 是对的:/adr/0010-metadata-protection 在任何 host 上都不是路由(docs 站只发布 content/docs 下挂 /docs;docs/adr/ 不发布)——纯换 host 会在传播面(published skill 教 AI 作者写 protection 块)留一个活样 404。新目标由三处已落地源三方钉死。
2. ADR-0010:565 是逐字引用:与 protection.zod.ts 的 SETUP_APP 示例 diff 后唯一分歧就是这行,改后恢复 byte-identity;Runtime and metadata strings still name docs.objectstack.ai — the CLI's release-notes URL, the Setup/Studio in-app text, and ~25 docsUrl: values (which also point at a non-/docs/ route) #10655 已关,「随代码移动」条件成立。ADR-0046:85 保留不改,历史记述论证成立(PD [WIP] Add Chinese version of the documentation #13)。
3. 字节中性:两字面量同为 56 字节,零余量 token ratchet 实测不动(13817/13817 前后一致),未提任何天花板。

门禁 15/15 绿、GOVERNED 判定已引用(2/2 命中)、skip-changeset 已读回。dev 声明的一处偏离(签名脚采用会话 URL 形式以在后续编辑中存活)采纳。留 draft、已 assign 维护者——合并即收。

---

Generated by Claude Code