Documentation drift found while implementing #10230. Observation class — no behaviour is wrong, and no code needs to change.
The stale sentence
packages/spec/src/automation/approval.zod.ts, in the docblock above APPROVER_ORG_SCOPED:
team is org-agnostic too — sys_team_member carries no organization column and the engine never scoped it (unlike position / membership-tier / department, which all do).
Two clauses, and after #10230 they no longer agree:
- "
sys_team_member carries no organization column" — still true, and still the reason a team's members are not individually placed. - "the engine never scoped it" — no longer describes the engine.
expandTeamUsers now takes an organization and screens the team on sys_team.organization_id before expanding it, at both call sites.
Why the flag value itself is still correct
team: false is not wrong and should not be flipped. The table answers ADR-0105 D9 retargetability ("does an organization: declaration apply to this type"), and team still consults no org-scoped directory — a declaration on it would still have no effect and is still rightly refused by resolveApproverDirectoryOrg. Only the justification drifted, by citing an engine behaviour that has since changed.
The risk is the ordinary one for a load-bearing comment: the next reader deciding whether team needs a screen finds a spec docblock asserting the engine has none, and concludes the work is outstanding when it has landed — or, in the other direction, reads the pairing of team: false with manager: false as still marking "the unscreened types", which after #10153 and #10230 it no longer does.
Suggested repair
One-sentence rewrite of the justification, keeping the flag: say that team is org-agnostic for retargeting because it consults no directory, and note that the expansion is nonetheless screened to the request's organization on the team's own organization_id (#10230), so the flag is about targeting and not about tenancy.
Not fixed in #10230's PR: that lane holds zero packages/spec ownership by its dispatch fence.
Related
Filed unassigned for triage.
Generated by Claude Code
Documentation drift found while implementing #10230. Observation class — no behaviour is wrong, and no code needs to change.
The stale sentence
packages/spec/src/automation/approval.zod.ts, in the docblock aboveAPPROVER_ORG_SCOPED:Two clauses, and after #10230 they no longer agree:
sys_team_membercarries no organization column" — still true, and still the reason a team's members are not individually placed.expandTeamUsersnow takes an organization and screens the team onsys_team.organization_idbefore expanding it, at both call sites.Why the flag value itself is still correct
team: falseis not wrong and should not be flipped. The table answers ADR-0105 D9 retargetability ("does anorganization:declaration apply to this type"), andteamstill consults no org-scoped directory — a declaration on it would still have no effect and is still rightly refused byresolveApproverDirectoryOrg. Only the justification drifted, by citing an engine behaviour that has since changed.The risk is the ordinary one for a load-bearing comment: the next reader deciding whether
teamneeds a screen finds a spec docblock asserting the engine has none, and concludes the work is outstanding when it has landed — or, in the other direction, reads the pairing ofteam: falsewithmanager: falseas still marking "the unscreened types", which after #10153 and #10230 it no longer does.Suggested repair
One-sentence rewrite of the justification, keeping the flag: say that
teamis org-agnostic for retargeting because it consults no directory, and note that the expansion is nonetheless screened to the request's organization on the team's ownorganization_id(#10230), so the flag is about targeting and not about tenancy.Not fixed in #10230's PR: that lane holds zero
packages/specownership by its dispatch fence.Related
teamapprover expansion is not organization-screened either — a cross-org team resolves into a request's approver slate #10230 — the team approver organization screenmanagerapprover resolvessys_user.manager_idwith no organization screen, while every sibling approver expansion is org-scoped #10153 — the same formanager, which made the pairing stale in the first placeFiled unassigned for triage.
Generated by Claude Code