From 3c4894a966a70cc6df26042b9070f3e4fc5b9441 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hartmut=20N=C3=B6renberg?= Date: Mon, 30 Mar 2026 12:25:56 +0200 Subject: [PATCH] docs(scope): refresh backlog status after hardening batch --- docs/audience-scoping-backlog.md | 116 ++++++------------------------- 1 file changed, 23 insertions(+), 93 deletions(-) diff --git a/docs/audience-scoping-backlog.md b/docs/audience-scoping-backlog.md index 87be0ba..c802dc5 100644 --- a/docs/audience-scoping-backlog.md +++ b/docs/audience-scoping-backlog.md @@ -8,107 +8,41 @@ ### 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. -## Batch Categories +## Remaining Categories -### Ready Now +### Completed In This Batch -These are small, well-bounded slices that should fit the existing hardening pattern: narrow the procedure, add router authorization tests, update docs, and commit separately. +- `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` -#### 1. `packages/api/src/router/blueprint.ts` -> `getGlobalFieldDefs` +### No Further Small Slices Currently Ready -- Current state: `protectedProcedure` -- Likely target: `planning-read` -- Why it is ready: - - the route returns global blueprint field definitions across active blueprints - - that is broader than a low-risk lookup and belongs with other blueprint configuration reads - - the audience class already exists in [route-access-matrix.md](/home/hartmut/Documents/Copilot/capakraken/docs/route-access-matrix.md) -- Expected work: - - switch to `planningReadProcedure` - - add a focused auth test covering unauthenticated, plain user, and planning-enabled caller - - update matrix wording if needed - -#### 2. `packages/api/src/router/resource.ts` -> `chapters` - -- Current state: `protectedProcedure` -- Likely target: `authenticated-safe-lookup` -- Why it is ready: - - the route only returns distinct active `chapter` strings - - it does not expose resource records, counts, hierarchy, or staffing data - - it looks more like a shared filter/lookup helper than a resource-overview read -- Expected work: - - keep implementation shape, but make the intended audience explicit in docs - - add auth coverage proving normal authenticated access is allowed while unauthenticated access is blocked - - only tighten further if a concrete leak is found - -#### 3. `packages/api/src/router/project.ts` -> `isImageGenConfigured`, `isDalleConfigured` - -- Current state: `protectedProcedure` -- Likely target: keep as authenticated low-risk checks -- Why it is ready: - - these are explicit boolean readiness/configuration checks already called out in the matrix - - the main gap is CI-enforced audience intent, not router logic -- Expected work: - - add auth tests for authenticated vs unauthenticated callers - - assert the result shape stays narrow (`configured`, optional provider) - - document them explicitly in the backlog as `tests/docs only` - -#### 4. `packages/api/src/router/assistant.ts` -> `listPendingApprovals` - -- Current state: `protectedProcedure` -- Likely target: keep as self-service -- Why it is ready: - - the implementation reads approvals by `ctx.dbUser!.id` - - it is already effectively scoped to the current user - - this can be locked down by tests without touching dirty assistant tool files -- Expected work: - - add router-level auth coverage for self-only behavior - - document the route in the access matrix - -### Tests Or Docs Only - -These routes look conceptually acceptable already, but the classification is not yet enforced clearly enough. - -#### `packages/api/src/router/assistant.ts` -> `chat` - -- Current state: `protectedProcedure` -- Working model: - - chat session itself is authenticated - - actual tool visibility is permission-gated inside assistant selection -- Remaining gap: - - the matrix does not yet document this route explicitly - - parity expectations should remain in `assistant.ts` tests until `assistant-tools.ts` is safe to touch -- Follow-up: - - add matrix entry describing chat as an authenticated shell with tool-level audience enforcement - - avoid deeper changes until dirty assistant-tool files are clear - -#### `packages/api/src/router/resource.ts` -> `importSkillMatrix` - -- Current state: `protectedProcedure` -- Working model: - - the mutation resolves the linked resource from the current user and writes only to that resource -- Remaining gap: - - no explicit self-service classification in the matrix - - auth regression coverage should be verified -- Follow-up: - - document as self-service - - add or tighten tests only if coverage is missing - -#### `packages/api/src/router/project.ts` -> `isImageGenConfigured`, `isDalleConfigured` - -- The likely outcome is to keep the current procedure and add explicit tests/docs rather than re-architecting the route. +- 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 @@ -147,15 +81,11 @@ These routes should not be batch-edited as “small safe slices” until a visib - Interim rule: - do not mix notification hardening into this batch unless the other worker clears the file first -## Recommended Batch Order +## Recommended Next Order -1. `blueprint.getGlobalFieldDefs` -2. `assistant.listPendingApprovals` plus matrix entry -3. `resource.chapters` classification and auth test -4. `project.isImageGenConfigured` and `project.isDalleConfigured` auth tests -5. `resource.importSkillMatrix` docs/test verification -6. `assistant.chat` matrix clarification and parity review -7. `comment` architecture design ticket +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 @@ -171,6 +101,6 @@ Each “ready now” slice should follow the same template: ## 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 `ready now` route has router-level authorization coverage +- 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