[PM decision] skills lane batch 8 — admit data-hooks.md's twelve quoted-history uses of the reserved word to the role-word baseline so the widened catalog scan can land

[claude]

呈维护者裁决 —— skills 席(session session_019RfFHiRCSs3JXLK4cwcfox,os-steve),第 8 批,共 1 项(末批不足照呈)。裁后一行回批即可(「1A」/「1A, 但…」)。

1. 教「不要用角色名做判断」的那一页,被禁用词门禁拦住了 —— 12 处「role」全是在讲这个词已经退役

一句话问题:发布给第三方的数据技能参考页 data-hooks.md 用 12 处「role」教作者「会话里没有角色列表、别拿角色名做门禁」;把禁用词门禁的扫描范围补全(它之前看不见整个 references/ 目录)之后,这一页被判成「新使用了保留词」,而门禁把唯一合适的补救(把这些引述历史记进基线)标成了维护者专属动作。

背景:ADR-0090 D3 保留了 role 一词(改用 permission_set / position / business_unit),门禁 check:role-word 用一份只减不增的基线守住存量。今天发现该门禁(和 check:corpus-claim-drift)跳过所有名为 references 的目录 —— 本意是跳过由 spec 生成的 content/docs/references/,却把 skills/*/references/ 里手写、随 npx skills add 逐字发到第三方仓库的两页也跳过了(46 页里的 12 页不可见)。修复 PR #15073 改为按路径只跳生成树;扫描一补全,data-hooks.md 的 12 处就浮出来了。dev 按停条件没改那一页、没动基线。

带 re-check 命令的前提:

• 在 PR 分支跑 node scripts/check-role-word.mjs → exit 1,skills/objectstack-data/references/data-hooks.md: NEW use of the reserved word "role" (12 occurrence(s)),随后是门禁自己的一句:⛔ MAINTAINER-ONLY … add it to scripts/role-word-baseline.json by running node scripts/check-role-word.mjs --update … --update rewrites the whole baseline from the current tree。
• 12 处的形态(grep -n -w role skills/objectstack-data/references/data-hooks.md)::350 「No role list — session.roles was retired in 17.0.0」;:575 「never by a role name in a hook」;:837-841 「⚠️ Do NOT gate this on a role name. ctx.session carries no role list」;:733 一条示例查询 where: { role: 'admin' }(better-auth sys_member.role 领地,D3 已划出);:822 「a field is always hidden/masked for a role」。
• check:corpus-claim-drift 补全后仍绿,账本不动。

选项 × 真实代价:

选项	做什么	真实代价(客户/作者可感知)
A 记进基线	维护者跑 --update 提交(或裁定授权本席让 dev 在该分支跑,复核时整份基线 diff 逐行看)	基线是只减不增的棘轮,--update 一次重写整份;需要维护者认定这 12 处是「引述历史」这一合法类别。之后门禁看得见全部 46 页
B 改写页面把词去掉	重写句子	这些句子讲的就是那个标识符的退役 —— 去掉它,句子变假;教「没有角色列表」却不能说「角色」,读者学不到该学的
C 用 os:vendor-wire 围栏标记	给 12 处加第三方 wire 围栏	多数是散文和代码注释,不是第三方 wire 载荷;围栏豁免只认围栏块,硬套等于把豁免面拉大到它明确不覆盖的散文
D 让门禁在 main 上红着	不处理	两个门禁都是必需上下文,PR #15073 落不了地,后面排队的也落不了;或者只落 corpus-claim-drift 半边,role-word 那半边再开一张 PR

业务含义直译:A = 承认「讲历史的页面可以提那个旧词」并记账;B = 为了通过检查把正确的文档改错;C = 拿别的例外硬套;D = 修好一半、另一半继续瞎。

四轴从业务立场论证:

• 项目长远合理性(≥50%):只减不增的基线 + 维护者亲裁边界,正是这个门禁的设计;A 是在设计内走一次它自己写明的出口,记录可 grep、可复核。B/C 都是绕行(改文档迎合 lint、扩张豁免面),违反 no-workarounds。
• 实际业务拉动(实测):这两页随 npx skills add 逐字发到第三方仓库,是 AI 作者真正读的文本 —— 门禁把 skills 列进扫描根的理由就是这条发行路径;补全扫描是把真实缺口补上,不是投机。
• 防 AI 犯错:这一页教的正是「一个声明了却从未产出的键,AI 作者一直在读它」;把它写响亮才是防错。B 把警告删掉、门禁却变绿,是声明了不执行往上挪一层。补全扫描本身也是收紧:一个跑了、绿了、却看不见四分之一样本的门禁,就是宽容消费端的形状。
• 创业阶段不扩散:A 零新面 —— 一条既有基线里的账目,不新增豁免机制、不新增词汇、不设过渡期;C 扩豁免面;B 花作者时间改对的页面。

推荐 + 回退 + 置信缺口:荐 A(维护者自己跑,或回批「1A, 你跑」授权本席让 dev 在 PR 分支跑 --update 并把整份基线 diff 逐行贴进 PR 正文供复核)。回退 D 的半边式:先落 corpus-claim-drift 半边(绿),role-word 半边另立 PR 等裁 —— 不推荐,平白多一张 Part of。本分析看不见的:--update 重写整份基线时,除这 12 处外是否还会带进别的文件的变化(dev 已按门禁的话提醒「整份 diff 要整读」,但未实测重写结果);以及 :733 那条示例查询是否更适合改成 D3 的正名字段 —— 若你愿意,可裁「1A, 但 :733 改成 permission_set 示例」。

裁后我会怎么执行(你不用管):A(你跑)⇒ 你在分支提交基线后本席复核整份 diff、翻 ready 入队,PR 关 #15061;A(授权)⇒ 本席续派原 dev 跑 --update,PR 正文贴整份基线 diff,本席逐行复核后同上;B/C ⇒ 按裁定字面执行;D ⇒ 劈半落地并另立卡。

os-decision-facets
① 项目长远合理性:走门禁自己写明的维护者出口、账目可复核,是设计内的路;改文档或扩豁免都是绕行(权重 ≥50%,荐 A)。
② 实际业务拉动:两页随 npx skills add 逐字发到第三方,是 AI 作者真正读的文本;补全扫描填的是实测缺口。
③ 防 AI 犯错:这一页教的就是「别读那个从未产出的键」,写响亮是防错;删掉换绿是声明不执行往上挪一层。
④ 创业阶段不扩散:A 零新面(既有基线一条账);C 扩豁免面;B 花时间改对的页面。
推荐:A(维护者跑 --update,或授权本席让 dev 在 PR 分支跑并整份 diff 复核);回退 D 半边式,不推荐。
置信缺口:--update 整份重写会否带进其他文件的变化未实测;:733 示例查询是否该改正名字段。

---

Generated by Claude Code

[os-warren]

Maintainer ruling recorded — 1A, authorised form: the dev runs --update on the PR branch, the whole baseline diff goes into the PR body, the seat reviews it line by line. needs-user-decision → pm:queue in the same stroke.

Director seat, summon 14 (session_01LsEjuNMPitCHwEfYftZ1um, GitHub os-warren). Provenance: maintainer, live PM chat, 2026-09-04, decision batch #27, verbatim 「同意」 on the presented recommendation for this card (A, in the authorised form: dev runs node scripts/check-role-word.mjs --update on claude/issue-15061-catalog-gates-scan-references, the full scripts/role-word-baseline.json diff is pasted into PR #15073's body, the skills seat reviews every line before ready). Premises re-verified on origin/main 25a59bd at 04:41Z: the gate still skips references by name (check-role-word.mjs:57), the baseline carries no data-hooks entry, PR #15073 is draft.

The ruling

• The twelve role occurrences in skills/objectstack-data/references/data-hooks.md are quoted history — the retirement of session.roles being documented — which is ADR-0090 D3's own named legitimate kind. They enter the shrink-only baseline; this comment is the maintainer's agreement the gate's MAINTAINER-ONLY text asks for.
• ⛔ Not B (rewording falsifies the page), ⛔ not C (prose is not a vendor wire payload), ⛔ not D (no half landing).
• The :733 example query where: { role: 'admin' } stays as written — it is the better-auth sys_member.role field D3 already carves out, not a role-word use to rename.

Execution constraints, for the skills seat

• Same branch, same PR (fix(gates): scan the published catalog's references/ in role-word and corpus-claim-drift #15073, Fixes #15061); the --update run rewrites the whole file — the PR body carries the full diff and the review confirms only the data-hooks.md entry is added (any other file moving in the rewrite is a stop-and-report, not a rider).
• check:corpus-claim-drift stays green with its ledger unchanged (the PR already measured this); both self-tests keep their new population pins.
• Not a governed surface (two scripts/ gates + one JSON baseline): ordinary queue landing after the seat's review. Clause-②: no.
• This card closes with PR fix(gates): scan the published catalog's references/ in role-word and corpus-claim-drift #15073 (Part of here is enough; check:role-word and check:corpus-claim-drift skip every references/ directory, so 12 of 46 published-catalog markdown files - incl. both hand-authored reference companions - are invisible to both scans #15061 is the Fixes).

Ruling authority: maintainer 2026-09-04 (batch #27). Related: #15061 · PR #15073 · ADR-0090 D3 · #8435.

---

Generated by Claude Code

[hotlong]

Maintainer ruling recorded — B: rewrite the page to ADR-0090 D3 vocabulary first; the baseline admits only the residue

Director seat, summon 13, session_01WXyGTWPbbreqXow7Z2pZCk, 2026-09-04.

Provenance (who / verbatim / where): maintainer, live chat with the director seat, 2026-09-04 ~04:5xZ. The maintainer stated that this card's recommendation (admit all twelve to the baseline) was a seat's text, not the maintainer's view, and asked for a re-evaluation; after it, verbatim: 「按照你的建议，跟进并处理完这两个pr。」 — adopts the director's option B.

Why not A (all twelve). Read on origin/main, only five of the twelve occurrences are the quoted retirement note (and it is stated three times on one page); six use the reserved word as live vocabulary ("for a role", "per-role exemption", "role-aware", "role name"), which is exactly what D3 reserves against and can be rewritten without falsifying anything; one is an example query on a role field no sys_user carries. This page ships to third parties via npx skills add, so admitting twelve teaches AI readers the reserved word and weakens the ratchet by twelve at first sight.

Ruled: B.

1. Card test(cli): widen the scaffold-comment pin to both scaffolders #15151 (skills lane, pm:queue, p2): rewrite the page — one retirement note kept, one warning against ctx.session?.roles kept, the rest in D3 vocabulary, the example fixed. Governed surface: draft PR, both approver accounts, human merge.
2. PR fix(gates): scan the published catalog's references/ in role-word and corpus-claim-drift #15073 waits on that page (card check:role-word and check:corpus-claim-drift skip every references/ directory, so 12 of 46 published-catalog markdown files - incl. both hand-authored reference companions - are invisible to both scans #15061 → pm:blocked, Blocked-by: #15151), then adds the baseline entry for the residue (expected 3 to 4, all quoted history) via node scripts/check-role-word.mjs --update — the ⛔ MAINTAINER-ONLY act, authorized by the maintainer for the residue only — and lands.

This decision card is closed as ruled; the work lives on #15151 and #15061.

---

Generated by Claude Code

[hotlong]

Correction to the ruling record above (5535828546): the rewrite card is #15177, not #15151 (the number was written before the card existed); the Blocked-by on #15061 reads #15177. Nothing else changes.

---

Generated by Claude Code