# Upgrade Guide — vNEXT

<!-- assembled-by: assemble-next-md -->
<!-- bump: patch -->

## What Changed

feat(permissions): **Slack organizational permission gate — Slice 0** (dark, observe-only). The first vertical slice of a conversational authority system for Slack: a verified-principal → role/tier → deterministic Layer-0 floor → relationship-anomaly step-up gate that returns `allow | clarify | refuse | step-up` with a conversational refusal. Ships **additive and dark-by-default** (config `slack.permissionGate.observeOnly`); when enabled it only *logs* verdicts and blocks nothing. Closes the long-standing defect that `UserManager.hasPermission()` had **zero callsites** — permissions were a context hint, not a code gate.

## What to Tell Your User

Nothing yet — this ships **dark / observe-only** (agent-only, experimental). No user-facing behavior changes until an operator explicitly turns it on, and even then it only watches and logs (does not block) so its false-positive rate can be measured before any enforcement.

## Summary of New Capabilities

- `src/permissions/`: RolePolicy (role→tier ceilings + enumerated floor), HeuristicIntentClassifier (deterministic, fail-closed floor), AnomalyScorer (Pillar-3 step-up hook), PermissionDecisionLedger (observe-only JSONL), SlackPermissionGate, SlackPrincipalResolver, SlackPermissionObserver + scenario harness.
- `UserProfile.slackUserId` / `orgRole` (additive, optional); `UserManager.resolveFromSlackUserId`.
- Observe-only `SlackAdapter` wiring + dark server-startup wiring (`SlackConfig.permissionGate`).
- Routes: `GET /permissions/decisions` (decision ledger), `GET /permissions/scenario-suite` (deterministic demonstration).

## Evidence

- 38 new tests green (35 unit + 3 integration); tsc + lint clean; 90-test no-regression across touched modules (slack adapter, user-manager, permissions).
- The six worked-example scenarios pass deterministically via `GET /permissions/scenario-suite`.
- Spec: `docs/specs/SLACK-ORG-INTEGRATION-SPEC.md` (approved); side-effects review: `upgrades/side-effects/slack-org-permission-gate.md`.
