CapaKraken/docs/audience-scoping-backlog.md

Audience Scoping Backlog

Date: 2026-03-30 Purpose: Collect the remaining audience-scoping work into a single batch backlog so the small auth-hardening slices can be finished before broader architecture work starts.

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

Dirty Files To Avoid Mixing Into This Batch

• packages/api/src/router/assistant-tools.ts
• 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.

Remaining Categories

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 Currently Ready

• the previously identified small hardening and tests/docs candidates have been completed
• the remaining audience work is now either architectural (comment.ts) or blocked by dirty files owned elsewhere

Needs Architecture Or Policy Design

These routes should not be batch-edited as “small safe slices” until a visibility model exists.

packages/api/src/router/comment.ts

• Current state: all core routes are protectedProcedure
• Why this is not a small slice:
  • reads and writes are keyed by generic entityType and entityId
  • visibility depends on the backing entity, not on the comment record alone
  • the current author/admin checks for resolve/delete are not enough to decide who may list or create comments on each entity class
• Design work needed:
  • define which entity types can host comments
  • map each entity type to its audience source of truth
  • centralize entity visibility checks before any comment read/write
• Recommended path:
  • treat comments as a separate architecture ticket, not part of the quick hardening batch

Blocked By Dirty Files

packages/api/src/router/assistant-tools.ts

• Why blocked:
  • unrelated local edits are already present
  • tool gating changes would mix poorly with concurrent work
• Interim rule:
  • keep parity changes on the assistant.ts side where possible
  • defer tool-level cleanups until the file is stable

packages/api/src/router/notification.ts

• Why blocked:
  • unrelated local edits are already present
  • TypeScript verification currently also reports a foreign issue in this file
• Interim rule:
  • do not mix notification hardening into this batch unless the other worker clears the file first

Recommended Next Order

1. comment architecture design ticket
2. assistant-tools parity cleanup once the dirty files are free again
3. notification follow-up once the dirty files and foreign TypeScript issue are resolved

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