CapaKraken/docs/audience-scoping-backlog.md

Audience Scoping Backlog

Date: 2026-03-30 Purpose: Historical record of the audience-scoping hardening batch and its exit state before larger architecture work begins.

Status Snapshot

Done

• blueprint.listSummaries: narrowed to planning-read
• blueprint.getGlobalFieldDefs: narrowed to planning-read with explicit auth coverage
• entitlement.getBalance, entitlement.getBalanceDetail: narrowed to self-service with elevated cross-resource access for controller, manager, and admin
• vacation.previewRequest: now enforces owned-resource access for normal users
• holidayCalendar.resolveResourceHolidays, holidayCalendar.resolveResourceHolidaysDetail: now enforce self-service ownership with elevated manager/admin reads
• assistant.listPendingApprovals: documented and covered as self-service
• assistant.chat: documented as an authenticated shell with tool-level audience enforcement
• resource.chapters: documented and covered as authenticated safe lookup
• resource.importSkillMatrix: documented as self-service and auth-verified
• project.isImageGenConfigured, project.isDalleConfigured: covered as authenticated low-risk configuration checks
• notification self-service and manager boundaries: auth-covered across list, unread counts, reminders, deletes, broadcasts, task creation, and assignment boundaries
• assistant-tools parity metadata: descriptions and parity assertions now match narrowed router audiences for resource overview, controller-only, self-service, and manager broadcast/task tools
• comment entity support now uses an explicit supported-entity registry with:
  • estimate visibility for controller, manager, and admin
  • resource visibility aligned to resource detail ownership and staff-access rules
  • entity-scoped mention candidate lookup instead of the narrower assignment user directory

Dirty Files To Avoid Mixing Into This Batch

• packages/api/src/__tests__/assistant-tools-advanced.test.ts
• packages/api/src/router/notification.ts
• packages/api/src/__tests__/assistant-tools-import-export.test.ts
• packages/api/src/__tests__/notification-router.test.ts

These files already have unrelated local edits. Audience parity work that would normally touch them should be deferred or handled through adjacent files and dedicated follow-up tests.

Final Batch Outcome

Completed In This Batch

• packages/api/src/router/blueprint.ts -> getGlobalFieldDefs
• packages/api/src/router/assistant.ts -> listPendingApprovals
• packages/api/src/router/assistant.ts -> chat matrix clarification
• packages/api/src/router/resource.ts -> chapters
• packages/api/src/router/resource.ts -> importSkillMatrix
• packages/api/src/router/project.ts -> isImageGenConfigured, isDalleConfigured

No Further Small Slices Remain In This Batch

• the previously identified small hardening and tests/docs candidates were completed, including the notification auth follow-up and assistant tool parity metadata cleanup
• the formerly architectural comment follow-up is also completed through explicit entity onboarding and mention-audience alignment
• no additional audience-scoping slice remains that is both small and isolated enough to justify another batch before larger architecture work

Next Major Themes

1. convert the still-open runtime secret model away from application-database centric storage
2. add broader authorization regression coverage and long-lived guardrails around the narrowed route audiences
3. reduce oversized routers and UI ownership surfaces so audience rules stay reviewable

Slice Definition

Each “ready now” slice should follow the same template:

1. change the router audience only if the current procedure is too broad
2. add focused auth tests for unauthenticated, plain authenticated, and elevated callers as applicable
3. update route-access-matrix.md
4. verify with targeted vitest
5. run git diff --check
6. commit in isolation

Exit Criteria For This Batch

• every route in this document is classified as either done, ready now, tests/docs only, needs architecture, or blocked
• every formerly ready now route now has router-level authorization coverage or explicit low-risk documentation
• the access matrix documents all low-risk exceptions explicitly
• larger architecture work starts only after this batch is either completed or intentionally deferred

Status:

• this batch is complete
• keep this file as a historical artifact, not as an active backlog