Approval groups + a User Management sub-agent for the V3 Config Agent

The V3 CPQ config agent can now create, edit, and delete approval groups (and their members) — live, name-resolved through a new read-only sub-agent, and guarded against orphaning rules or pending approvals.

1. Why this exists

Before this PR, the config agent could manage approval rules (the routing edges in the workflowSpec) but not the approval groups those rules pointed at. To add Jane to "Finance Leadership", a user had to leave the chat and open the V3 Admin UI.

2. The two persistence models, side by side

The most important conceptual rule in this PR — repeated in every sub-agent and orchestrator system prompt — is that rules and groups persist differently. Keep them straight when reviewing.

3. The end-to-end flow: "add Jane and the VP of Sales to Finance Leadership"

This is the new lifecycle: the orchestrator resolves names before delegating writes, optionally renders a prefilled card, and the approval-rule sub-agent commits live.

4. The User Management sub-agent

The simplest piece, but it's the one that prevents a whole class of bugs. It owns three read-only tools and returns a verdict the orchestrator is required to act on.

Matching, by the numbers

The pure logic in tools/userMatching.ts normalizes names (lowercase, strip accents/punct, collapse whitespace) and classifies each candidate as exact, strong, or fuzzy. Two subtleties from the test suite worth flagging:

5. The Approval Group tools

approvalGroupTools.ts is the bulk of the diff (+863 lines). It exposes seven tools to the approvalRule sub-agent, each writing live.

The guarded-hybrid persistence pattern

This is the most subtle part of the file. Group rows live in prisma.approvalGroup, but orgs that still have a V2 workflow config also have a workflow-graph node mirroring each group. The PR routes through the V2 controller only when needed, and only for the ops that actually touch the graph:

Validation invariants enforced by every write path

• USER members must be ACTIVE. findInvalidUserIds checks org + deletedAt: null + status: 'ACTIVE' for every newly-added userId.
• requiredApprovals ≤ member count. Otherwise the group "could never be approved" — refused with a specific error.
• Deduped assignees. Duplicate approvers would inflate count vs. the engine's uniqBy(userId) at execution time, making thresholds unsatisfiable.
• Case-insensitive unique name on create / rename.

6. The delete guard — reference-scanned and fail-closed

Deleting a group that anything still routes to would orphan rules and break live approvals. findGroupReferences scans five sources before allowing a delete:

// approvalGroupTools.ts — delete decision
const mustConfirm = referenced || Boolean(refs.scanError);
if (mustConfirm && !force) {
  const message = refs.scanError
    ? `Could not fully verify what references this group (failed to load: ${refs.scanError}). Refusing to delete without explicit confirmation...`
    : `This group is still referenced — approval rules: ${refs.rules.length}, V2 workflow edges: ${refs.v2Edges}, live PENDING approvals: ${refs.pendingApprovals}, ...`;
  return fail(message, { blocked: true, references: refs });
}

7. The config card

ApprovalGroupModal.tsx follows the existing ConfigAgent modal pattern: stateless input collector, never writes. On submit it forwards the payload back to the chat as a [Modal:approval_group] message; the orchestrator delegates the actual write to the approvalRule sub-agent's saveApprovalGroup.

Client-side guards in the card

• Submit disabled when requiredApprovals > members.length; inline error message.
• Searchable picker filters to status === 'ACTIVE' users.
• Manager-level chips are read-only (rendered with the manager badge variant) — managed elsewhere, preserved on save.
• Trimmed empty strings are forwarded as-is (so clearing a field actually clears it server-side; || undefined would make a cleared field a no-op).

8. Orchestrator prompt changes

The orchestrator system prompt grows a new "APPROVAL GROUP LIFECYCLE" section. The non-obvious nuance:

Also notable: the prompt corrects an older assumption baked into the step-4 approval ingestion logic. Previously it said createApprovalGroup "reuses existing groups by name automatically." It no longer does — there is no name-based reuse. The orchestrator must check listApprovalGroups first and only create if absent.

9. What it doesn't change

10. Risks & open questions