docs(38): research phase — admin tag management

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-19 22:05:22 +02:00
parent f0597ae6b1
commit 136772d80c
1 changed files with 640 additions and 0 deletions
--- a/.planning/phases/38-admin-tag-management/38-RESEARCH.md
+++ b/.planning/phases/38-admin-tag-management/38-RESEARCH.md
@@ -0,0 +1,640 @@
 # Phase 38: Admin — Tag Management - Research
 **Researched:** 2026-04-19
 **Domain:** Full-stack CRUD with hierarchical data (self-referential FK), admin panel patterns, cycle detection
 **Confidence:** HIGH
 ## Summary
 Phase 38 is entirely additive on top of well-established Phase 36/37 admin infrastructure. The codebase already has tags (`id`, `name`, `createdAt`), a service (`getAllTags`), a route (`GET /api/tags`), a hook (`useTags`), and a disabled "Tags" sidebar entry in the admin shell. The phase adds a `parentId` FK to the schema, builds admin CRUD routes under `/api/admin/tags`, and adds two client routes (`/admin/tags` list + `/admin/tags/$tagId` edit). Every pattern needed — service layer, Hono route module, React Query admin hooks, edit page structure, delete confirmation dialog — was established in Phase 37 for global items and can be followed directly.
 The only genuinely new technical concern is hierarchy management: building a flat-to-tree transformation for the list view, a recursive descendant collector for parent-picker filtering and cycle detection, and the server-side cycle guard. All of these are straightforward pure functions operating on the in-memory tag array — no recursive SQL CTEs are required because the tag count is small and the full list fits easily in a single query result.
 The `parentId` Drizzle self-referential FK uses a deferred lambda `() => tags.id` to handle the forward reference. Migration follows the same single-ALTER pattern as the `is_admin` migration from Phase 36. The `ON DELETE SET NULL` semantic is already supported by Drizzle's FK options and does not need custom code.
 **Primary recommendation:** Follow Phase 37 patterns exactly. The only new logic is tree flattening (list view) and cycle detection (service + client parent picker). Keep the tree component as pure local state — no Zustand needed.
 ---
 <user_constraints>
 ## User Constraints (from CONTEXT.md)
 ### Locked Decisions
 - **D-01:** Add `parentId integer REFERENCES tags(id) ON DELETE SET NULL NULLABLE` to the `tags` table via Drizzle migration. Self-referential FK — no depth limit at the schema level.
 - **D-02:** On parent deletion, `ON DELETE SET NULL` orphans children (they become top-level). No cascading child deletion.
 - **D-03:** Collapsible tree view (not a flat table). Parent tags render rows; children are indented below. All nodes start expanded on page load.
 - **D-04:** Columns: Name (with indent level visual) | Item Count | Actions.
 - **D-05:** Search/filter mode: filter in-tree — non-matching rows are hidden in place. Parents with matching children remain visible; non-matching leaf nodes are hidden.
 - **D-06:** No separate "Children Count" column — children are visible in the tree structure below each parent.
 - **D-07:** Quick-add form at the top of the tag list (not a separate page). Fields: name + optional parent picker. Submits inline without navigation.
 - **D-08:** Dedicated edit page at `/admin/tags/$tagId` — consistent with Phase 37 item edit pattern. Fields: name + parent picker.
 - **D-09:** Delete lives on the edit page (not the list), following Phase 37 D-05.
 - **D-10:** Arbitrary depth — any tag can be a parent of any other (no 1-level limit). Future-proofed for deep taxonomies.
 - **D-11:** Cycle prevention is dual-layer:
  - **Client**: Parent picker filters out the tag's own descendants from the dropdown options.
  - **Server**: API validates that the new parent is not a descendant of the tag being updated. Returns 400 with a clear error message if a cycle is detected.
 - **D-12:** Deleting a tag orphans its children — they become top-level tags (`parentId` SET NULL via FK cascade).
 - **D-13:** Delete confirmation dialog shows: item count + child count warning. Example: "Delete 'sleeping-bag'? 12 items use this tag. Its 3 child tags will become top-level. This cannot be undone."
 - **D-14:** If a tag has 0 items and 0 children, the confirmation is simplified: "Delete 'sleeping-bag'? This cannot be undone."
 ### Claude's Discretion
 - Exact visual styling of tree indentation (border-left line, chevron icon, or indent padding)
 - Whether to use a chevron toggle button or click-to-collapse on the row
 - Implementation of the collapsible tree (local component state vs. Zustand)
 - Exact error message copy for cycle detection rejection
 - Whether to add a "Move to top-level" shortcut on the edit page in addition to the parent picker
 ### Deferred Ideas (OUT OF SCOPE)
 - Drag-to-reparent
 - Bulk operations (bulk delete, bulk reparent)
 - Tag merge
 - Tag usage analytics
 </user_constraints>
 ---
 <phase_requirements>
 ## Phase Requirements
 | ID | Description | Research Support |
 |----|-------------|------------------|
 | ADMN-05 | Admin can browse all tags with item counts and parent/child relationships displayed | Tree list view with `getAdminTags` service returning `parentId`, `itemCount`, `childCount` |
 | ADMN-06 | Admin can create a new tag with a name | Quick-add form at top of list; `POST /api/admin/tags` → `createTag` service |
 | ADMN-07 | Admin can rename an existing tag | Edit page form; `PUT /api/admin/tags/:id` → `updateTag` service |
 | ADMN-08 | Admin can assign a parent tag to a tag (enabling sub-tag hierarchy) | Parent picker on edit page; `parentId` FK in schema; cycle detection in service |
 | ADMN-09 | Admin can remove a tag's parent assignment (making it top-level again) | Parent picker allows null selection; `PUT /api/admin/tags/:id` with `parentId: null` |
 | ADMN-10 | Admin can delete a tag, with a warning if items are currently using it | Delete button on edit page; confirmation dialog showing item count + child count |
 </phase_requirements>
 ---
 ## Architectural Responsibility Map
 | Capability | Primary Tier | Secondary Tier | Rationale |
 |------------|-------------|----------------|-----------|
 | Tag CRUD persistence | API / Backend (`tag.service.ts`) | Database (Drizzle) | Business logic and data validation live in the service layer |
 | Cycle detection (authoritative) | API / Backend (`tag.service.ts`) | — | Server is the authority; client filter is UX-only |
 | Tree data assembly (flat → tree) | API / Backend (optional) or Frontend | — | Tag count is small; flat array with parentId is sufficient; client transforms |
 | Collapsible tree rendering | Browser / Client | — | Pure UI state — local React state, no server involvement |
 | Parent picker descendant filtering | Browser / Client | — | Derived from full tag list already in React Query cache |
 | Admin auth guard | API / Backend (`requireAdmin` middleware) | Frontend (redirect in admin shell) | Server is authoritative; client redirect is UX convenience |
 ---
 ## Standard Stack
 ### Core (verified from codebase)
 | Library | Version | Purpose | Why Standard |
 |---------|---------|---------|--------------|
 | Drizzle ORM | (project version) | Schema definition + migrations + query builder | Already used throughout project |
 | Hono | (project version) | HTTP route handlers | Existing admin routes pattern |
 | `@hono/zod-validator` | (project version) | Request body validation | Used in `admin-items.ts` |
 | Zod | (project version) | Schema definitions | Used in all admin route validators |
 | TanStack React Query | (project version) | Server state, mutations, cache invalidation | Used in all admin hooks |
 | TanStack Router | (project version) | File-based routing, `createFileRoute` | Used for all client pages |
 | Tailwind CSS v4 | v4 | Styling | Project standard |
 | bun:test | Bun 1.3.9 | Test runner | Verified — `bun test` works |
 ### Supporting
 | Library | Version | Purpose | When to Use |
 |---------|---------|---------|-------------|
 | PGlite (`@electric-sql/pglite`) | (project version) | In-memory PostgreSQL for tests | `createTestDb()` in `tests/helpers/db.ts` |
 **Installation:** No new packages required — all dependencies exist in the project.
 ---
 ## Architecture Patterns
 ### System Architecture Diagram
 ```
 Admin browser
    │
    ├── GET /admin/tags  →  AdminTagsPage (list)
    │       │
    │       ├── useAdminTags()  →  GET /api/admin/tags
    │       │       └── getAdminTags(db)  →  SELECT tags + item counts
    │       │
    │       ├── flat array → buildTree() → TagTree component
    │       │       └── local expand/collapse state
    │       │
    │       └── QuickAddForm  →  useCreateAdminTag()  →  POST /api/admin/tags
    │
    └── GET /admin/tags/:tagId  →  AdminTagEditPage (edit)
            │
            ├── useAdminTag(id)  →  GET /api/admin/tags/:id
            │
            ├── Save form  →  useUpdateAdminTag()  →  PUT /api/admin/tags/:id
            │       └── server: isDescendant() cycle check → 400 if cycle
            │
            └── Delete  →  useDeleteAdminTag()  →  DELETE /api/admin/tags/:id
                    └── DB: parentId SET NULL (FK cascade) on children
 ```
 ### Recommended Project Structure
 New files to create:
 ```
 src/
 ├── server/
 │   ├── routes/
 │   │   └── admin-tags.ts          # CRUD handlers for /api/admin/tags
 │   └── services/
 │       └── tag.service.ts         # Extend existing file with CRUD + cycle detection
 ├── client/
 │   ├── hooks/
 │   │   └── useAdminTags.ts        # Admin tag hooks (mirrors useAdminGlobalItems pattern)
 │   └── routes/
 │       └── admin/
 │           ├── tags.tsx           # List page with tree view + quick-add
 │           └── tags.$tagId.tsx    # Edit page with rename + reparent + delete
 ```
 Files to modify:
 ```
 src/db/schema.ts                   # Add parentId to tags table
 src/server/routes/admin.ts         # Register adminTagRoutes
 src/client/routes/admin.tsx        # Enable "Tags" sidebar link
 ```
 ### Pattern 1: Self-Referential FK in Drizzle (PostgreSQL)
 **What:** The `tags` table references itself via `parentId`. Drizzle requires a deferred lambda to handle the forward reference.
 **When to use:** Any time a table references its own primary key.
 ```typescript
 // Source: [VERIFIED: existing codebase pattern at globalItemTags, onDelete cascade]
 // Adapted for self-referential nullable FK
 export const tags = pgTable("tags", {
  id: serial("id").primaryKey(),
  name: text("name").notNull().unique(),
  parentId: integer("parent_id").references(() => tags.id, { onDelete: "set null" }),
  createdAt: timestamp("created_at").defaultNow().notNull(),
 });
 ```
 **Migration generated:** Single ALTER statement, same as Phase 36's `is_admin` migration:
 ```sql
 ALTER TABLE "tags" ADD COLUMN "parent_id" integer REFERENCES "tags"("id") ON DELETE SET NULL;
 ```
 ### Pattern 2: Admin Service Functions (tag.service.ts extensions)
 **What:** Extend existing `tag.service.ts` with CRUD + aggregate queries.
 ```typescript
 // Source: [VERIFIED: adapted from global-item.service.ts pattern in codebase]
 // Returns flat array; client builds tree
 export async function getAdminTags(db: Db) {
  const result = await db
    .select({
      id: tags.id,
      name: tags.name,
      parentId: tags.parentId,
      itemCount: count(globalItemTags.globalItemId),
    })
    .from(tags)
    .leftJoin(globalItemTags, eq(globalItemTags.tagId, tags.id))
    .groupBy(tags.id, tags.name, tags.parentId)
    .orderBy(asc(tags.name));
  return result;
 }
 export async function getTagWithCounts(db: Db, id: number) {
  const [tag] = await db
    .select({
      id: tags.id,
      name: tags.name,
      parentId: tags.parentId,
      itemCount: count(globalItemTags.globalItemId),
    })
    .from(tags)
    .leftJoin(globalItemTags, eq(globalItemTags.tagId, tags.id))
    .where(eq(tags.id, id))
    .groupBy(tags.id, tags.name, tags.parentId);
  return tag ?? null;
 }
 // childCount is computed client-side from getAdminTags flat array
 // (cheaper than a correlated subquery for small tag sets)
 ```
 ### Pattern 3: Cycle Detection (Server)
 **What:** Before updating `parentId`, verify that the new parent is not a descendant of the tag being updated. Operates on the full flat tag array fetched from DB.
 ```typescript
 // Source: [ASSUMED — standard tree algorithm, not library-specific]
 function isDescendant(
  allTags: { id: number; parentId: number | null }[],
  candidateParentId: number,
  tagId: number
 ): boolean {
  // Walk up the ancestor chain of candidateParentId
  // If we encounter tagId, there's a cycle
  let current: number | null = candidateParentId;
  const visited = new Set<number>();
  while (current !== null) {
    if (current === tagId) return true;
    if (visited.has(current)) break; // safety: existing cycle in data
    visited.add(current);
    const node = allTags.find((t) => t.id === current);
    current = node?.parentId ?? null;
  }
  return false;
 }
 ```
 ### Pattern 4: Admin Route Module (admin-tags.ts)
 **What:** Hono route module following the same structure as `admin-items.ts`.
 ```typescript
 // Source: [VERIFIED: adapted from src/server/routes/admin-items.ts]
 import { zValidator } from "@hono/zod-validator";
 import { Hono } from "hono";
 import { z } from "zod";
 import { parseId } from "../lib/params.ts";
 import { createTag, deleteTag, getAdminTags, getTagWithCounts, updateTag } from "../services/tag.service.ts";
 type Env = { Variables: { db?: any; userId?: number } };
 const app = new Hono<Env>();
 const createTagSchema = z.object({
  name: z.string().min(1),
  parentId: z.number().int().positive().nullable().optional(),
 });
 const updateTagSchema = z.object({
  name: z.string().min(1).optional(),
  parentId: z.number().int().positive().nullable().optional(),
 });
 // GET /api/admin/tags — flat list with counts
 app.get("/", async (c) => { ... });
 // GET /api/admin/tags/:id — single tag with counts
 app.get("/:id", async (c) => { ... });
 // POST /api/admin/tags — create
 app.post("/", zValidator("json", createTagSchema), async (c) => { ... });
 // PUT /api/admin/tags/:id — update (with cycle check)
 app.put("/:id", zValidator("json", updateTagSchema), async (c) => { ... });
 // DELETE /api/admin/tags/:id
 app.delete("/:id", async (c) => { ... });
 export { app as adminTagRoutes };
 ```
 ### Pattern 5: Tree Building (Client)
 **What:** Pure function transforming flat `AdminTag[]` to a `TreeNode[]` for rendering. Keep in component or a `lib/treeUtils.ts` helper.
 ```typescript
 // Source: [ASSUMED — standard algorithm]
 interface AdminTag { id: number; name: string; parentId: number | null; itemCount: number; }
 interface TreeNode extends AdminTag { children: TreeNode[]; depth: number; }
 function buildTree(tags: AdminTag[]): TreeNode[] {
  const map = new Map<number, TreeNode>();
  tags.forEach(t => map.set(t.id, { ...t, children: [], depth: 0 }));
  const roots: TreeNode[] = [];
  map.forEach(node => {
    if (node.parentId === null) {
      roots.push(node);
    } else {
      const parent = map.get(node.parentId);
      if (parent) {
        node.depth = parent.depth + 1;
        parent.children.push(node);
      } else {
        roots.push(node); // orphan (parent deleted) → treat as top-level
      }
    }
  });
  return roots;
 }
 // Flatten tree to ordered rows for render
 function flattenTree(nodes: TreeNode[], result: TreeNode[] = []): TreeNode[] {
  for (const node of nodes) {
    result.push(node);
    flattenTree(node.children, result);
  }
  return result;
 }
 ```
 ### Pattern 6: Client Hooks (useAdminTags.ts)
 **What:** Mirrors `useAdminGlobalItems.ts` — typed interfaces, `useQuery`/`useMutation`, query key invalidation.
 ```typescript
 // Source: [VERIFIED: adapted from src/client/hooks/useAdminGlobalItems.ts]
 export interface AdminTag {
  id: number;
  name: string;
  parentId: number | null;
  itemCount: number;
 }
 export function useAdminTags() {
  return useQuery({
    queryKey: ["admin-tags"],
    queryFn: () => apiGet<AdminTag[]>("/api/admin/tags"),
  });
 }
 export function useCreateAdminTag() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (data: { name: string; parentId?: number | null }) =>
      apiPost<AdminTag>("/api/admin/tags", data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["admin-tags"] });
      queryClient.invalidateQueries({ queryKey: ["tags"] }); // invalidate public cache too
    },
  });
 }
 export function useUpdateAdminTag() { ... }
 export function useDeleteAdminTag() { ... }
 ```
 ### Anti-Patterns to Avoid
 - **Recursive SQL CTE for tree traversal:** Unnecessary complexity for a small tag set. Fetch flat, build tree in JS.
 - **Storing tree structure as nested JSON:** The `parentId` column is the canonical representation. Never denormalize.
 - **Cycle detection only on the client:** The client filter is UX convenience only. The server MUST validate independently.
 - **Infinite loop in `buildTree` if existing cycle in data:** Guard with a `visited` set in the ancestor walk.
 - **Forgetting to invalidate `["tags"]` query key on mutations:** The public `useTags` hook and admin `useAdminTags` share the same underlying data but different query keys — both must be invalidated on create/update/delete.
 ---
 ## Don't Hand-Roll
 | Problem | Don't Build | Use Instead | Why |
 |---------|-------------|-------------|-----|
 | Request body validation | Manual type checks | Zod + `@hono/zod-validator` | Already in project; handles error responses automatically |
 | Admin auth guard | Inline `isAdmin` checks per route | `requireAdmin` middleware (already exists) | `src/server/middleware/auth.ts` — one line: `app.use("/*", requireAuth, requireAdmin)` |
 | Server state / cache | `useState` + `useEffect` + `fetch` | TanStack React Query | Already in project; mutations auto-invalidate |
 | Delete confirmation modal | Custom overlay | Inline modal pattern from `items.$itemId.tsx` | Copy the fixed-inset-0 dialog pattern — 30 lines, zero deps |
 **Key insight:** This phase has no new external dependencies. The entire implementation is wiring existing infrastructure with new data.
 ---
 ## Common Pitfalls
 ### Pitfall 1: Self-Referential FK Forward Reference in Drizzle
 **What goes wrong:** Writing `references(() => tags.id)` where `tags` is the table being defined causes a TypeScript/runtime error if the variable isn't yet in scope.
 **Why it happens:** The table definition references itself before the `const tags = ...` assignment completes.
 **How to avoid:** Drizzle handles this correctly when using a lambda `() => tags.id` — it defers the reference lookup. Confirmed by the `globalItemTags` FK pattern already in the codebase (`references(() => tags.id, { onDelete: "cascade" })`). The self-referential case works the same way. [VERIFIED: codebase at `globalItemTags.tagId`]
 **Warning signs:** TypeScript complains about `tags` being used before assignment — only occurs if you use a direct reference `tags.id` instead of a lambda.
 ### Pitfall 2: Orphan Display After Parent Deletion
 **What goes wrong:** A tag's `parentId` points to a deleted parent. The tree builder crashes or silently omits the orphaned tag.
 **Why it happens:** `ON DELETE SET NULL` runs at DB level, but there's a window in tests or seed data where orphans could be created manually.
 **How to avoid:** In `buildTree`, when a node's `parentId` is non-null but no matching parent is found in the map, treat the node as a root (already shown in the Pattern 5 code above).
 **Warning signs:** Tags disappearing from the list after a parent deletion.
 ### Pitfall 3: Parent Picker Shows Tag's Own Descendants (Client Side)
 **What goes wrong:** An admin selects a child tag as the parent of its ancestor, creating a cycle.
 **Why it happens:** Parent picker renders all tags without filtering.
 **How to avoid:** The parent picker on the edit page must exclude: (1) the tag itself, (2) all its descendants. Compute the descendant set client-side from the full tag list. The server provides the safety net (D-11).
 **Warning signs:** 400 errors from the server on PUT requests with `{ error: "Cycle detected" }`.
 ### Pitfall 4: Missing `["tags"]` Query Invalidation
 **What goes wrong:** The admin creates/renames/deletes a tag, but the public `useTags()` hook (used in the admin items filter chips) still shows stale data.
 **Why it happens:** `useAdminTags` and `useTags` use different query keys (`["admin-tags"]` vs `["tags"]`). Invalidating only `["admin-tags"]` leaves the public cache stale.
 **How to avoid:** All mutations in `useAdminTags.ts` must invalidate both `["admin-tags"]` and `["tags"]`.
 ### Pitfall 5: TanStack Router Route Tree Not Regenerated
 **What goes wrong:** New route files `admin/tags.tsx` and `admin/tags.$tagId.tsx` are created but the auto-generated `routeTree.gen.ts` is not updated, causing 404s or build errors.
 **Why it happens:** The route tree is auto-generated by Vite during `bun run dev` or `bun run build`. In development the watcher updates it automatically. In CI it must be regenerated.
 **How to avoid:** Run `bun run dev` at least once after adding new route files so `routeTree.gen.ts` is regenerated. Never manually edit `routeTree.gen.ts`.
 ---
 ## Code Examples
 ### Registering Admin Tag Routes in admin.ts
 ```typescript
 // Source: [VERIFIED: src/server/routes/admin.ts pattern]
 import { adminTagRoutes } from "./admin-tags.ts";
 // Add after adminItemRoutes registration:
 app.route("/tags", adminTagRoutes);
 ```
 ### Enabling Tags Sidebar Link in admin.tsx
 ```typescript
 // Source: [VERIFIED: src/client/routes/admin.tsx — replace disabled div]
 // Replace:
 <div className="flex items-center gap-2 px-3 py-2 rounded-lg text-sm text-gray-300 cursor-not-allowed" ...>
 // With (same structure as Items link above it):
 <Link
  to="/admin/tags"
  activeProps={{ className: "bg-gray-100 text-gray-900 font-medium" }}
  inactiveProps={{ className: "text-gray-600 hover:bg-gray-50" }}
  className="flex items-center gap-2 px-3 py-2 rounded-lg text-sm transition-colors"
 >
  <LucideIcon name="tag" size={16} />
  <span>Tags</span>
 </Link>
 ```
 ### Delete Confirmation Text Logic (D-13/D-14)
 ```typescript
 // Source: [VERIFIED: adapted from items.$itemId.tsx dialog pattern]
 function getDeleteConfirmText(tag: AdminTagDetail): string {
  const parts: string[] = [];
  if (tag.itemCount > 0) {
    parts.push(`${tag.itemCount} ${tag.itemCount === 1 ? "item uses" : "items use"} this tag.`);
  }
  if (tag.childCount > 0) {
    parts.push(`Its ${tag.childCount} child ${tag.childCount === 1 ? "tag" : "tags"} will become top-level.`);
  }
  parts.push("This cannot be undone.");
  return parts.join(" ");
 }
 ```
 ---
 ## State of the Art
 | Old Approach | Current Approach | When Changed | Impact |
 |--------------|------------------|--------------|--------|
 | Flat tags (id, name only) | Hierarchical tags with `parentId` | Phase 38 | Enables sub-tag taxonomy (e.g. "down" under "sleeping-bag") |
 | Disabled "Tags" sidebar entry | Active link to `/admin/tags` | Phase 38 | Admins can navigate to tag management |
 **Deprecated/outdated:**
 - None in this phase — purely additive.
 ---
 ## Assumptions Log
 | # | Claim | Section | Risk if Wrong |
 |---|-------|---------|---------------|
 | A1 | `buildTree` and `flattenTree` pure JS functions are sufficient (no recursive SQL CTE needed) | Architecture Patterns | Low — tag count is small; even 10,000 tags would be fast in JS |
 | A2 | `childCount` is cheapest computed client-side from the flat array rather than via SQL subquery | Standard Stack | Low — trivially verifiable; a SQL subquery would also work |
 | A3 | `isDescendant` cycle check iterates ancestor chain of `candidateParentId` (not descendants of `tagId`) | Architecture Patterns | Medium — logic must be verified during implementation; wrong direction breaks cycle detection silently |
 | A4 | Drizzle self-referential FK with `onDelete: "set null"` generates correct SQL | Standard Stack | Low — Drizzle docs support this; existing `onDelete: "cascade"` FK in codebase confirms the option syntax |
 ---
 ## Open Questions
 1. **`childCount` on the single-tag GET endpoint (for edit page delete confirmation)**
   - What we know: `getAdminTags` (list endpoint) returns all tags; `childCount` is derivable client-side.
   - What's unclear: For the edit page, we need `childCount` for the specific tag being edited. We can either: (a) compute it client-side from the full `useAdminTags` list, or (b) add a correlated count to `getTagWithCounts`.
   - Recommendation: Use the full list from `useAdminTags` cache on the edit page as well (React Query keeps it cached). No separate correlated subquery needed.
 2. **`parentId` null on quick-add form submission**
   - What we know: Parent picker is optional (D-07). No parent selected = `parentId: null`.
   - What's unclear: Zod schema should accept `parentId: z.number().int().positive().nullable().optional()` — ensure `null` and `undefined` both result in DB `NULL`.
   - Recommendation: Use `.nullable().optional()` and explicitly pass `null` when no parent is selected.
 ---
 ## Environment Availability
 Step 2.6: SKIPPED (no external dependencies beyond existing project stack — no new tools, services, or runtimes introduced).
 ---
 ## Validation Architecture
 ### Test Framework
 | Property | Value |
 |----------|-------|
 | Framework | Bun test runner (bun:test) |
 | Config file | None — discovered automatically |
 | Quick run command | `bun test tests/services/tag.service.test.ts tests/routes/tags.test.ts` |
 | Full suite command | `bun test` |
 ### Phase Requirements → Test Map
 | Req ID | Behavior | Test Type | Automated Command | File Exists? |
 |--------|----------|-----------|-------------------|-------------|
 | ADMN-05 | `getAdminTags` returns tags with `parentId`, `itemCount`, ordered alphabetically | unit | `bun test tests/services/tag.service.test.ts` | Exists (extend) |
 | ADMN-06 | `POST /api/admin/tags` creates tag, returns 201 with tag object | integration | `bun test tests/routes/admin-tags.test.ts` | Wave 0 gap |
 | ADMN-07 | `PUT /api/admin/tags/:id` renames tag | integration | `bun test tests/routes/admin-tags.test.ts` | Wave 0 gap |
 | ADMN-08 | `PUT /api/admin/tags/:id` with valid `parentId` sets parent | integration | `bun test tests/routes/admin-tags.test.ts` | Wave 0 gap |
 | ADMN-09 | `PUT /api/admin/tags/:id` with `parentId: null` removes parent | integration | `bun test tests/routes/admin-tags.test.ts` | Wave 0 gap |
 | ADMN-10 | `DELETE /api/admin/tags/:id` deletes tag; children get `parentId = null` | integration | `bun test tests/routes/admin-tags.test.ts` | Wave 0 gap |
 | ADMN-11 (cycle) | `PUT /api/admin/tags/:id` with descendant as `parentId` returns 400 | unit | `bun test tests/services/tag.service.test.ts` | Exists (extend) |
 ### Sampling Rate
 - **Per task commit:** `bun test tests/services/tag.service.test.ts`
 - **Per wave merge:** `bun test`
 - **Phase gate:** Full suite green before `/gsd-verify-work`
 ### Wave 0 Gaps
 - [ ] `tests/routes/admin-tags.test.ts` — covers ADMN-06, ADMN-07, ADMN-08, ADMN-09, ADMN-10 route integration tests
 - Existing `tests/services/tag.service.test.ts` — extend (do not replace) for ADMN-05 and cycle detection
 ---
 ## Security Domain
 ### Applicable ASVS Categories
 | ASVS Category | Applies | Standard Control |
 |---------------|---------|-----------------|
 | V2 Authentication | yes | `requireAuth` middleware (existing) |
 | V3 Session Management | no | Handled by existing OIDC middleware |
 | V4 Access Control | yes | `requireAdmin` middleware (existing) — all `/api/admin/*` routes |
 | V5 Input Validation | yes | Zod schemas on all POST/PUT bodies via `zValidator` |
 | V6 Cryptography | no | No new cryptographic operations |
 ### Known Threat Patterns
 | Pattern | STRIDE | Standard Mitigation |
 |---------|--------|---------------------|
 | Unauthorized tag mutation (non-admin) | Elevation of Privilege | `requireAdmin` middleware on all admin tag routes (already pattern-established) |
 | Cycle injection via crafted `parentId` | Tampering | Server-side `isDescendant` check before update, returns 400 |
 | Mass tag deletion via unauthenticated request | Tampering | `requireAdmin` blocks unauthenticated and non-admin users |
 | Tag name injection (XSS) | Tampering | Zod `z.string().min(1)` + React renders as text (not innerHTML) |
 ---
 ## Sources
 ### Primary (HIGH confidence)
 - [VERIFIED: codebase] `src/server/services/tag.service.ts` — existing service functions and DB patterns
 - [VERIFIED: codebase] `src/server/routes/admin-items.ts` — admin route module pattern to replicate
 - [VERIFIED: codebase] `src/client/routes/admin/items.$itemId.tsx` — edit page and delete dialog pattern
 - [VERIFIED: codebase] `src/client/hooks/useAdminGlobalItems.ts` — React Query admin hook pattern
 - [VERIFIED: codebase] `src/db/schema.ts` — current tags table structure; FK syntax for `onDelete: "set null"`
 - [VERIFIED: codebase] `src/server/routes/admin.ts` — admin router structure; how to register new sub-router
 - [VERIFIED: codebase] `src/client/routes/admin.tsx` — disabled Tags entry to enable
 - [VERIFIED: codebase] `tests/helpers/db.ts` — PGlite test setup with migrations
 - [VERIFIED: codebase] `bun --version` → 1.3.9
 ### Secondary (MEDIUM confidence)
 - [ASSUMED] Drizzle self-referential FK with `() => tags.id` lambda + `onDelete: "set null"` — confirmed by existing `onDelete: "cascade"` FK syntax in codebase; "set null" is a standard Drizzle option
 ### Tertiary (LOW confidence)
 - None
 ---
 ## Metadata
 **Confidence breakdown:**
 - Standard stack: HIGH — all verified from codebase; no new packages
 - Architecture: HIGH — direct extension of Phase 37 patterns; only new logic is tree building and cycle detection
 - Pitfalls: HIGH — identified from direct code inspection and structural analysis
 **Research date:** 2026-04-19
 **Valid until:** 2026-05-19 (stable codebase; no fast-moving dependencies)