feat(auth): carry the acting org's restoreRules entitlement from whoami

[theCodeDrift]

Stack (root → tip):

• ➡️ feat(auth): carry the acting org's restoreRules entitlement from whoami #433 (you are here)
  • feat(check): give git steps instead of rule restore on a plan that does not serve it #434
    • feat(rule): stop naming rule rollback on a plan that does not serve it #435

Stack 1 of 3, merging forward. It adds the OpenSpec proposal and reads the plan's restoreRules entitlement. Nothing uses the value yet, so no output changes.

The CLI suggests taskless rule restore and rule rollback on every plan. It only finds out a plan lacks them when the service refuses. v2 whoami now returns each organization's entitlements (taskless/taskless#254). This stack uses restoreRules to stop suggesting commands the plan won't serve.

What this PR does

• resolveOrgSubject becomes resolveActingOrg, which returns { subject, restoreRules? } from the same whoami call. No new request.
• restoreRules has three states. It is set only when an organization matched the repository and sent a boolean. It stays unknown when whoami fails, when entitlements is absent, or when the CLI fell back to the token's claim.
• Identity gets an optional restoreRules field.
• Adds the cli-plan-aware-recovery OpenSpec change: proposal, design, delta specs for cli-rule-recovery, cli-check and cli-rule-reconciliation, and tasks.

What to review

• packages/cli/src/auth/org.ts: the three states, and that only a matched organization's boolean is trusted.
• openspec/changes/cli-plan-aware-recovery/, especially the decision to treat the entitlement as a suggestion, never a gate. The schema calls entitlements "a hint for the client, never a gate", so restore and rollback still always call the service.

Stack

1. This PR: resolve the entitlement.
2. check gives git steps instead of rule restore when the plan excludes it.
3. rule revisions stops naming rule rollback, plus the recover-rule recipe and the archive.

No changeset here: nothing user-visible changes until unit 2, which adds it.

Refs GH-425

[theCodeDrift]

@claude /review

[claude]

Claude finished @theCodeDrift's task in 2m 48s —— View job

---

Review complete

• Read prior review data (.prior-review.json) — no prior threads, reviews, or comments other than the trigger; this is the first review of this PR.
• Fetch PR diff via gh pr diff
• Review packages/cli/src/auth/org.ts (core entitlement logic)
• Review packages/cli/src/auth/identity.ts
• Review packages/cli/src/rules/plan-check.ts
• Review test changes
• Review OpenSpec artifacts (including cross-checking MODIFIED spec deltas against the standing specs for dropped scenarios)
• Post final review

Review mode: incremental — read 0 prior review thread(s) before reviewing. .prior-review.json contained no reviewThreads, reviews, or top-level comments beyond the @claude /review trigger itself, so there is nothing previously raised to classify as addressed or still-open. Everything below is [New].

Summary

This is a small, well-scoped "unit 1 of 3" stacked PR: it plumbs restoreRules off the existing whoami call and onto Identity/ActingOrg, with nothing yet reading the value (as stated in the PR description). I read it end-to-end against packages/cli/src/auth/org.ts, identity.ts, plan-check.ts, both test files, and the new OpenSpec artifacts.

Correctness: No bugs found.

• resolveActingOrg's tri-state logic is correct: restoreRules is only ever set on the branch where an org actually matched the repo's remote (org.entitlements?.restoreRules narrowed with typeof === "boolean"), and left unset on every other path (no org list, no match, non-boolean/absent entitlements). This matches the vendored schema (entitlements optional; restoreRules required-boolean within it when present) at packages/cli/src/generated/api-v2.d.ts:49-57.
• The conditional spread in identity.ts (...(org.restoreRules === undefined ? {} : { restoreRules: org.restoreRules })) correctly keeps the key absent rather than undefined-valued, consistent with the "unknown" tri-state.
• All renamed call sites (resolveOrgSubject → resolveActingOrg) are updated together; no stale references remain anywhere in packages/cli or the tests.
• Identity's fields are always accessed individually downstream (identity.token, identity.orgSubject, identity.repositoryUrl in rules/recover.ts), never spread wholesale into a request body, so there's no risk of the new restoreRules field leaking into an API payload.
• I specifically checked the three OpenSpec ## MODIFIED Requirements blocks (cli-check, cli-rule-reconciliation, cli-rule-recovery) against the current openspec/specs/*/spec.md, since a MODIFIED block silently deletes any standing scenario it omits (per this repo's CLAUDE.md warning). Every prior scenario under each modified requirement is still present in the deltas, each with the new plan-aware scenario added alongside — nothing was dropped.

Minor observation (test coverage):

• packages/cli/src/auth/identity.ts:51-58 — the tri-state-to-optional-field mapping in resolveIdentity (the conditional spread) has no direct test. org.test.ts thoroughly covers resolveActingOrg itself, and error-envelope.test.ts's resolveIdentity tests only exercise error-code paths, not the restoreRules propagation. Low risk given how small the logic is, but a future regression in the spread (e.g. always including the key, or inverting the undefined check) wouldn't be caught by the existing suite. Not blocking — just worth a follow-up case (e.g. mocking fetchWhoami and asserting resolveIdentity(...).restoreRules is true/false/absent) when unit 2 starts exercising the field.

Conventions / delivery shape: Consistent with this repo's CLAUDE.md guidance — no changeset in this PR (correctly deferred to unit 2, since nothing user-visible changes yet), Refs GH-425 is a trailing reference rather than inline, and the proposal explicitly declares its delivery shape ("stacked, merging forward") with the safety argument for why unit 1 alone is safe in production.

No inline comments filed — nothing rose to the level of a concrete defect.

[theCodeDrift]

Re: @claude[bot] — "…the conditional spread in resolveIdentity that sets restoreRules … has no direct test on this branch"
#433 (comment)

Declined by the author. Nothing reads Identity.restoreRules on this branch. #435's rule-recovery.test.ts serves whoami with restoreRules true, false, or a failed lookup, and drives each through resolveIdentity end to end.

— AI Coding Agent