[immakermatty]

Fixes #21.

Why

An Organization whose installation accepted Issues: Read and write has to declare issues: write in its policy, because the installation gate compares the accepted permissions exactly. 0.11.0 then adds issues: write to both tiers of every Workspace, so a Workspace whose Team holds only pull still gets a token that can open, edit, label, close, reopen and comment on issues. A Workspace that must write nothing on GitHub (the consumer in #21 is a shared visitor Environment of a public reference Organization) had no way to be read-only while the Organization keeps Issues for its other Workspaces.

What changes

Policy v3 gains one optional key per Workspace, permission_ceiling, whose only value is "read":

	Without the key (every existing policy)	permission_ceiling: "read"
push / maintain / admin grant	write tier, unchanged	read tier
pull / triage grant	read tier, unchanged	read tier
read tier permissions (Issues accepted)	actions/checks/contents/members/pull_requests: read, issues: write	the same with issues: read
read tier permissions (Issues not accepted)	unchanged	unchanged (plain read tier)
no grant, drifted Team, foreign owner	refused	refused exactly the same

Fail-closed rules, all enforced before GitHub is asked:

• mintToken(policy, workspace, repositoryId, access) and tokenPermissions(policy, access, workspace) now require a Workspace object of the parsed policy; a missing or foreign Workspace is refused (no default, like the tier).
• A write tier for a read-ceiling Workspace is refused, not silently lowered, so a gate that lost the ceiling cannot mint write.
• Any requested set that asks for a permission or level the installation has not accepted is refused. Parse rules already make this unreachable today; it is the explicit guard the ceiling relies on.
• Any other ceiling value, null included, rejects the policy (the Worker answers 503 configuration_unavailable).

Unchanged on purpose: the installation gate (still an exact comparison), the token response shape, the adapter, the probe, the request budget, and everything a policy without the key mints.

policy check prints the ceiling's set and a CEILING column only when a Workspace declares one, so other policies print exactly as before; --live rows show the live ROLE next to the capped ACCESS.

Version 0.12.0 (minor: additive optional policy key).

Proof that other Organizations behave identically

• All 88 existing tests pass with only the mint call signature threaded through; none of their expected permission sets, policy parses or policy check outputs changed.
• New: a Workspace without the key parses to exactly its previous shape; in a mixed policy the uncapped Workspace mints byte-identical write and read sets (issues: write, workflows: write included) while the capped one mints reads only.
• New end-to-end tests through the Node server and through the Worker with the real core client: a push grant mints access: read with issues: read for the capped Workspace and access: write for the other; cross-Workspace, cross-repository and foreign-owner refusals are unchanged.
• Mutation check: removing any one of the four rules (gate cap, read lowering, write refusal, installation guard) fails 1–3 of the new tests.

npm test (96 pass) and npm run check (license check, syntax, Wrangler dry run) pass locally.

Risks and rollout

• Older brokers ignore the key. A broker before 0.12.0 accepts a policy with a ceiling and mints the uncapped tiers. README states the order: deploy 0.12.0 with the unchanged policy, then add the ceiling; never roll such a Workspace's broker back below 0.12.0 while its credential is in use. A schema bump would make old brokers reject the policy, but it would force a policy migration on every Organization for one optional key, so this PR documents the order instead.
• issues: read is requested only where the Organization accepted Issues, so it is always within the installation's grant.
• The changelog entry is this squash commit's subject; the release workflow generates CHANGELOG.md from commit subjects.

Follow-ups

• Release v0.12.0 after merge, then roll out only to the first-ring broker that needs the ceiling. Other Organizations' brokers need no change and can take 0.12.0 in the next ring.

🤖 Generated with Claude Code

[agentrozjedemeai]

Independent exact-head QA on 6f8b010: APPROVED. The parsed ceiling is restricted to "read"; live Team grant still controls repository reachability, while the capped access tier and requested permission set both remain read-only. Mint rejects a write tier for the capped Workspace, foreign Workspace identity, and permission escalation before the scoped token request; the response is checked against the exact repository and permission set. Uncapped policies retain their prior requested sets and summary output. The README and architecture describe the old-broker rollback hazard and the deploy-before-policy rollout order. Independently ran npm test (96/96) and npm run check (license, syntax, Wrangler dry run), each under the host heavy-command lock; CI test and OCI image are green. Local Node was v22.22.3 (repository declares >=24), so CI remains the Node-24 validation source. No blocking findings. Review only; no merge.