feat: guard M365 pilot scopes

[namastex888]

Summary\n- add Workit M365 pilot scope guard with explicit read-only allowlist\n- document and link the M365 write-gate implementation/approval contract\n- reject write/unknown Microsoft Graph scopes fail-closed\n\n## Tests\n- /tmp/go1.25.10/bin/go test ./...

Summary by CodeRabbit

• Documentation
  • Added architecture and implementation plans for making Workit a canonical KHAW plugin and for an M365 write-approval gate with fail-closed behavior and 30-minute approval TTL.
• New Features
  • Introduced pilot-mode Microsoft 365 scope controls to restrict operations to a read-only allowlist.
• Tests
  • Added unit tests validating pilot scope normalization, defaults, and rejection behavior.
• Chores
  • Updated dead-code baseline entries.

[coderabbitai]

Warning

Review limit reached

@namastex888, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 53 minutes and 30 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a3c89b14-07b9-45d6-9b5a-15f80020eacc

📥 Commits

Reviewing files that changed from the base of the PR and between d7e9c29 and c0c18e0.

📒 Files selected for processing (3)

• .deadcode-baseline.txt
• internal/msauth/scopes.go
• internal/msauth/scopes_test.go

📝 Walkthrough

Walkthrough

This PR adds three planning documents describing Workit as a KHAW canonical plugin with Hermes approval for M365 writes, and implements a Go pilot scope guard (internal/msauth) enforcing an ordered read-only allowlist with normalization and fail-closed rejection.

Changes

M365 Write Approval & Pilot Scope Validation

Layer / File(s)	Summary
Integration vision and enforcement contract docs/plans/2026-05-30-khaw-workit-canonical-plugin-plan.md, docs/plans/2026-05-30-workit-m365-write-approval-contract.md	Canonical plugin plan and written approval contract: ownership boundaries, Hermes approval posture for M365 writes, read-only pilot law, fail-closed enforcement, structured approval payloads with 30-minute TTL, Telegram UI template, Hermes harness behavior, audit/redaction contract, comprehensive test matrix, and pitfalls.
Implementation task breakdown docs/plans/2026-05-30-workit-m365-write-gate-implementation-plan.md	End-to-end implementation roadmap enumerating tasks: classifier, deterministic payload hashing, structured approval request builder, fail-closed execution wrapper, pilot-mode gate, Hermes structured approval adapter integration, Telegram rendering, redacted audit ledger, M365 pilot scope guarding, verification commands, and manual smoke procedures.
Pilot scope guard implementation and tests internal/msauth/scopes.go, internal/msauth/scopes_test.go, .deadcode-baseline.txt	Go implementation of pilot scope guard with ordered allowlist (User.Read, Mail.Read, Calendars.Read), exported ErrPilotScopeNotAllowed, PilotAllowedScopes() defensive accessor, GuardPilotScopes() normalization/validation/deduplication preserving allowlist order and fail-closed rejection of unallowlisted scopes. Unit tests validate order, defaulting, normalization, explicit rejection of write/unknown scopes, and immutability; deadcode baseline updated for new functions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A write-gate stands where risky calls might tread,
Pilot scopes whisper "read-first" instead,
Fail-closed the gate until approval's found,
Hermes and Workit listen to the sound,
Safe commands hop forward — cautious, proud, and sound.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 22.22% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: guard M365 pilot scopes' directly and specifically summarizes the main change in the changeset, which introduces M365 pilot scope controls and enforcement.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/m365-pilot-scope-guard

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces integration plans, write approval contracts, and implementation plans for the Workit M365 integration, alongside a new msauth package that restricts Microsoft Graph scopes to a read-only baseline for the pilot. The review feedback suggests enhancing the scope guard's robustness and maintainability by dynamically initializing the allowed scope set to avoid duplication, supporting case-insensitive scope validation, and updating the unit tests to verify this behavior.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@internal/msauth/scopes.go`:
- Around line 49-50: There is a linter spacing issue: after calling
canonicalPilotScope and assigning canonical, allowed, add a single blank line
before the subsequent conditional `if !allowed` to satisfy golangci-lint; update
the block around the `canonical, allowed := canonicalPilotScope(trimmed)`
statement (in scopes.go) so there is an empty line separating that assignment
from the `if !allowed` check, preserving existing logic and variable names.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 14014bf9-ac63-4c34-9b71-05210010c6a7

📥 Commits

Reviewing files that changed from the base of the PR and between c4461d7 and d7e9c29.

📒 Files selected for processing (3)

• .deadcode-baseline.txt
• internal/msauth/scopes.go
• internal/msauth/scopes_test.go

✅ Files skipped from review due to trivial changes (1)

• .deadcode-baseline.txt

🚧 Files skipped from review as they are similar to previous changes (1)

• internal/msauth/scopes_test.go