Skip to content

Checklist maintenance from the identity-auth QA run (#7663): 5 item/oracle/fixture corrections for docs/qa/platform-checklist #7740

Closed
#7785
Closed
Checklist maintenance from the identity-auth QA run (#7663): 5 item/oracle/fixture corrections for docs/qa/platform-checklist#7740
#7785
Assignees
huangyiirene
Labels
domain:devxpm:dispatched

Description

@huangyiirene
huangyiirene
opened on Aug 11, 2026

Summary

Consolidated checklist-maintenance edits falling out of the identity-auth FULL-area QA run (#7663). All five are edits to docs/qa/platform-checklist/ (primarily areas/identity-auth.json) — checklist text / oracle / fixture-note corrections, not product fixes. Each item's product defect, where one exists, is filed separately.

Items

  1. org-membership-team-management clause 1 (and its negative) name the wrong role vocabulary. The enforced builtin set is {owner, admin, delegated_admin, member} per ADR-0108 (BUILTIN_MEMBERSHIP_ROLE_OPTIONS, "nothing widens these at boot any more") — not {owner, admin, member, guest}. guest is actually rejected (400 ROLE_NOT_FOUND), and delegated_admin is legitimate. The stale spec doc-comment on MemberSchema.role (packages/spec/src/identity/organization.zod.ts:84-87, "Common roles: 'owner', 'admin', 'member', 'guest'"; the .describe(...) at line 87 repeats it) is probably where the checklist text came from — fix both the checklist clause and the spec doc-comment. (The spec doc-comment edit is a packages/spec change, so it may warrant its own tiny domain:spec PR; the checklist clause is the domain:devx part.)

  2. invitation-scope-gates clause 6 conflates two axes. DelegableScope models ObjectStack positions / permission sets / business units and has no field that could carry a better-auth org invitation role, so it can never "contain member". The delegate demonstrably can mint a member invitation while the endpoint reports an empty assignable set — it under-reports, never over-reports (the safe direction). The clause needs a revision, not a product fix.

  3. admin-lifecycle-operations clause 4 should name the authed-request oracle, not get-session's status code. better-auth's no-session convention is 200-with-null-body, so the clause's literal 401 expectation misdescribes a correct implementation. The session was provably gone; the clause should assert against a protected authed request, not get-session's status.

  4. teams-bu-membership — retire the knownGap (a BU-consuming geometry does ship: share_new_inquiries_with_field_ops, so the clause runs) and add the zero-seeded-placements note: a fresh boot seeds the BU tree but zero sys_business_unit_member rows, so the rule materializes nothing until a tester places someone (the seed-data-thin trap for this item). (Product defect from this clause filed separately as teams-bu-membership: sharing-rule revocation is lazy — a BU moved OUT of a shared subtree keeps read access until the shared record is next written #7729.)

  5. identity-import-wizard — add the fixture note that the auto policy's temporary-fallback branch cannot occur on objectstack dev: both transports always register and dev.ts hard-sets NODE_ENV='development' so isPhoneOtpDeliverable() cannot be made false. Record as a fixture note so the next sweep does not re-derive it.

Source

Extracted from the QA run #7663 (framework 92f26f7, console 09987b680).

Activity

  1. huangyiirene
    added
    pm:queue
    domain:devx
    finding
    on Aug 11, 2026
  2. claude
    removed
    finding
    on Aug 11, 2026

  3. claude commented on Aug 11, 2026

    @claude
    claudebot
    on Aug 11, 2026 – with Claude
    Contributor

    Findings triage (grade): promoted — finding removed, pm:queue stays (resolves the filed dual pm-state). Scoped checklist/docs maintenance with named anchors — auto-queue class.

    Premise spot-check on origin/main @ 8f1851e: item 1's spec-side half is live — the stale role vocabulary is still at packages/spec/src/identity/organization.zod.ts:84-87 ("Common roles: 'owner', 'admin', 'member', 'guest'", repeated in the .describe(...) at :87). Routing note for the executor: that one doc-comment line is packages/spec text (spec-surface territory); as filed the principal landing is docs/qa/platform-checklist/areas/identity-auth.json ⇒ domain:devx stands, and the spec doc-comment can ride as the declared cross-surface line item the card already names.

    本评论来自分诊座位 Routine（#5474 试点），不构成认领。

    Generated by Claude Code

  4. huangyiirene
    added
    pm:dispatched
    and removed
    pm:queue
    on Aug 11, 2026
  5. huangyiirene
    self-assigned this
    on Aug 11, 2026

  6. huangyiirene commented on Aug 11, 2026

    @huangyiirene
    huangyiirene
    on Aug 11, 2026 – with Claude
    CollaboratorAuthor

    Claim: PM loop round 5 (devx seat, 2026-08-11 term) — wave 5 unit A(清单维护同类打包)
    Session: session_01GZKbx4xyF7U5WXj6ch49BM
    Branch: claude/issue-7740-checklist-run-notes-pack(pack:#7740+#7745+#7753+#7720,一 PR 四条 Fixes)
    Worktree: cloud dev session(独立容器)
    Domain: devx
    File surface(本卡):docs/qa/platform-checklist/areas/identity-auth.json 主落点 + packages/spec/src/identity/organization.zod.ts:84-87 doc-comment rider(triage 已批随行,PR 正文声明跨面行项)
    Container & model: mode:cloud / claude-opus-5
    Serial constraints: 包内四文件两两不相交;coverage.json ⛔ 只读(#7347 独占)

    Generated by Claude Code

  7. huangyiirene commented on Aug 11, 2026

    @huangyiirene
    huangyiirene
    on Aug 11, 2026 – with Claude
    CollaboratorAuthor

    os-dev 主报告 — wave 5 unit A(清单维护同类打包:#7740 + #7745 + #7753 + #7720)

    逐卡逐项完成情况

    #7740 — areas/identity-auth.json(5/5 落地) · premise_still_valid: true(逐项见下)

    项 落点 before after
    1 org-membership-team-management(step / clause / negative / source,rev 1→2) 角色词表 {owner, admin, member, guest};source 引的正是那条陈旧 doc-comment ADR-0108 闭集 {owner, admin, delegated_admin, member};新增「词表是闭的」条款(guest、stack position、PermissionSet 名各被 400 ROLE_NOT_FOUND 拒于门外且不留行);source 改指 membership-role.ts:116 + ADR-0108 + membership-role-vocabulary.dogfood.test.ts
    2 invitation-scope-gates(step 8 / 条款 / negative / source,rev 2→3) 「返回的 role set 含 member 不含 admin」——不可断言 改为断言真实形状 { isTenantAdmin, scopes, placeableBusinessUnitIds, assignablePositions }(security-service.ts:92-105)与自作用域;邀请角色门交回条款 1–4;negative 拆开:over-report 才是 FAIL,under-report 是安全方向、禁止立案
    3 admin-lifecycle-operations(revoke step / 条款 / negative / source,rev 2→3) oracle 是 get-session 状态码,期望 401 oracle 改为受保护的 authed 请求(revoke 前 2xx、紧接一次被拒);get-session 只作旁证并注明 200-with-null-body 约定,锚点 session-of-record.test.ts:165
    4 teams-bu-membership(requires / knownGaps / step / 条款 / source,rev 1→2) knownGap:也许没有几何消费 BU 树,条款可能 blocked(fixture) gap 退休(保留为 retired 行不删):share_new_inquiries_with_field_ops 展开 bu_field_ops 子树,条款照跑。换成 zero-seeded-placements 注记:全新 boot 只 seed 树、sys_business_unit_member 零行,必须先放置、BEFORE 读预期为空
    5 identity-import-wizard(knownGaps / auto 条款 / source,rev 1→2) 无注记,fallback 缺席易被当缺陷 记录 auto 的 temporary-fallback 分支在 objectstack dev 下不可达(两路 transport 恒注册;NODE_ENV=development 使两个可达性门都无法为假),写明什么样的 boot 才能触发,并指引用 temporary 策略覆盖同一凭据路径

    Rider(triage 已批,PR 正文单列跨面行项):packages/spec/src/identity/organization.zod.ts:84-87 的 doc-comment + :87 的 .describe() 已修正。

    两处主动声明的外溢,请 PM 裁断是否收回:

    1. 同文件 InvitationSchema.role(:139)携带同一缺陷('admin','member','guest')。卡面只点名 :84-87。我一并修了——留着就等于给下一个读者留下这张卡要关掉的同一个坑;纯注释文本,零行为。PM 若要严格按锚点,单独 revert 这一段即可。
    2. content/docs/references/identity/organization.mdx 是从这些 .describe() 生成的,check:docs(build-docs.ts --check)是 CI 门禁,所以两行表格随之更新。本容器从未 install 过(无 node_modules),无法跑真正的 gen:schema + build-docs,因此是按生成器自身渲染路径手工对齐的:build-docs.ts:427 原样输出 description,escapeMdxDescription 只处理 `/{/</|/\,新串一个都不含。这一处值得有构建树的人复核一眼——若 CI 的 check:docs 仍红,重跑生成器覆盖即可。

    #7745 — areas/integration-system.json(1 修正 + 3 注记) · premise_still_valid: true

    项 落点 before after
    wire keys email-template-render(step / raw-send 条款 / negative / source,rev 3→4) { to, subject, bodyHtml }——实际被 400 "at least one of text or html is required" 更正为 { to, subject, html | text }(SendEmailInput,email-service.ts:42-68);点明 bodyHtml/bodyText 是模板字段;加了「错词表探针」把两套词汇钉开,并加 NOT-a-FAIL negative
    sys_account 405 notify-inbox-delivery(requires / knownGaps,rev 1→2) 三 persona 需求没写怎么造 记录 POST /api/v1/data/sys_account → 405(managedBy better-auth、apiMethods ['get','list'],405 先于写守卫的 403,sys-account.object.ts:234-241),旧的「给 seeded persona 接一条凭据」配方已关闭;改指 sign-up / admin/create-user
    Studio flow 只读 flow-connector-picker(fixtures / knownGaps / step,rev 2→3) 无注记 记录 ResourceEditPage 的 artifact-backed 启发式 + flow 的 allowOrgOverride:false,指明可编辑路径是 console 自己的 create page,并交叉链接 objectui#4308(极性相反那一例才是缺陷)
    predicate multi:true webhook-lifecycle(requires / knownGaps / bulk step / source,rev 3→4) 只写「需要 predicate multi-write path」 记录 REST 走不通是设计如此——#3897 把 options.multi 剥离作为安全边界(rest-server.ts:10461-10492),bulk 条款需用 flow update_record/delete_record 节点经 api trigger 触发

    #7753 — areas/studio-authoring.json(+ platform-core.json)(6/6 记录项) · premise_still_valid: true

    项 落点 before after
    #7637 更正 org-override-registry-gate(knownGaps / source,rev 1→2) #7637 的观察原样留存 记录更正:OS_METADATA_WRITABLE=permission 下徽标会清除、编辑器完全可写(GET /meta 报 overrideSource:'env',protocol.zod.ts:208),两个方向都被证过 → #7637 不得按原文行动
    publish-drafts 200 draft-publish-lifecycle(step / publish-drafts 条款 / negative,rev 2→3) 条款按 HTTP 状态判 abort 改为按 data.success 判(该门 abort 答 200 + success:false),原子性结论保留(abort 后两个名字都 404);状态码之争记为待一次明确裁决的 open ledger 项。⛔ 只记录不裁决,已在 negative 里写明 runner 不得据此判 FAIL
    flow 路由注记 同 org-override-registry-gate(同一次 rev) — ResourceEditPage 行号 + objectui#4308 交叉链接
    _diagnostics 横幅 authoring-validation-not-persisted(knownGaps / negative,rev 1→2) — 记录已知误报:保存成功的合法草稿上出现 "Unrecognized key(s): _diagnostics"(设计器对服务端自己的注解做了回读校验),并与真正的 located-error 缺失区分开
    stale ref A record-page-roundtrip(automated.stale / 两条 clause verify / source,rev 1→2) 两个 objectui spec 无 stale 标注 标为 stale-not-red 并写明具体原因(studio-record-page.spec.ts 把 Object 控件当 input 填,实际已是 role=combobox 按钮;studio-editor.spec.ts 指向已不存在的 "Layout" 标题 + 一个编辑器正确锁住的 shipped page),附 runner 规则:手工驱动、不得引用其输出、不得把其失败记为本项 FAIL
    stale ref B platform-core.metadata-authoring-roundtrip(automated.stale partial / clause 3 verify,rev 1→2) 同上 仅标注 studio-record-page.spec.ts 这一半;dogfood pin 与 studio-object-designer.spec.ts 明确不受影响

    #7720 — docs/qa/platform-checklist/README.md · premise_still_valid: true(#7716 已合并,qa-scratch-authz 在 main 上)

    Item anatomy 补齐 recipe 约定的两半:item-anatomy 代码块新增 fixtures.provisioning = { use, why };新增小节《Area-level fixtures — one named provisioning recipe, many items》给出 area 级配方块完整形状(title / why / provenance / app / requires / sequence[{step, call, body, expect, source}] / teardown / knownGaps)+ item 侧引用 + 四条设计理由(运行时供给故 teardown 是唯一清理;每个调用引 framework file:line;why 是债务标记;opt-in 是把 knownGaps 改写成 CLOSED-by-recipe 而不是删掉)。option C(教校验器解析 provisioning.use)按卡面 deliberately deferred,未做,并在 README 里写明「已推迟」及其后果(拼错的 use 由 review 而非 check:platform-checklist 兜住)。

    验证

    Changeset / 标签

    清单与 README 属 docs,本可走 skip-changeset;但 packages/spec rider 确实改了已发布的 .describe() 文本,故附了 @objectstack/spec patch 级 changeset(门禁是按标签而非按路径判的,这样两条路都成立)。docs 部分的 skip-changeset 标签仍归 PM 处理。

    跨仓 / 越界发现清单

    1. objectui — e2e spec 重指向(studio-authoring run notes: one correction to #7637, two stale automated.ref specs, and three ledger/route observations #7753 item 6,report-don't-edit):e2e/live/studio-record-page.spec.ts(Object 控件已是 role=combobox 按钮)与 e2e/live/studio-editor.spec.ts("Layout" 标题已移除 + 目标是编辑器正确锁住的 shipped page)需重指向当前 surface。本 PR 未改 objectui 任何文件,只在本仓把 staleness 记下来,止住每轮红跑。请 PM 转 objectui 车道。
    2. objectui#4308:artifact-backed 启发式极性相反的那一例(写入型 package 里的对象被判只读),本 PR 两处注记交叉引用它,并请接手者确认 flow 这一例保持正确。
    3. 越界但已修并声明:InvitationSchema.role doc-comment(同文件 :139,同一缺陷)—— 见上文 Checklist maintenance from the identity-auth QA run (#7663): 5 item/oracle/fixture corrections for docs/qa/platform-checklist #7740 rider 第 1 条。
    4. 需有构建树者复核:content/docs/references/identity/organization.mdx 的两行为手工按生成器渲染路径对齐(本容器无 node_modules)—— 见 Checklist maintenance from the identity-auth QA run (#7663): 5 item/oracle/fixture corrections for docs/qa/platform-checklist #7740 rider 第 2 条。

    ⛔ 未 merge、未 auto-merge、未动 merge queue、未改 content/docs/releases/**、未 git stash。
    工作在专用 worktree objectstack-7740(容器内新建、推送后已回收),未在共享主检出上编辑。

    Generated by Claude Code

  8. huangyiirene
    closed this as completedin #7785on Aug 11, 2026
  9. akarma-synetal
    added a commit that references this issue on Aug 17, 2026

    docs(qa,spec): checklist maintenance from four QA runs — identity-aut…

    3bb9340
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

domain:devxpm:dispatched

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions