Make department routing discoverable + add a clarifying turn to the editor

The conversational editor didn't scale: only one department (Product) was
demonstrable, nothing told the user which departments/conditions exist, and the
model accepted any department string — so "add a Finance review" created a gate
that never fired. Three changes fix that:

- Seed three departments (Product, Operations, Finance) on real POs, each mapping
  to a real org head, so a department-scoped gate is demonstrable.

- Discoverability in the editor: the org's REAL departments render as coloured
  chips ("Route by department") you can click to route on, and the condition
  fields (amount / department / variance / verdict) are listed in the "What can I
  change?" popover. The chips' departments are sent to the edit agent.

- A clarifying turn the model chooses ONLY when needed: a new `clarify` op lets
  the planner ask "which department?" (with the valid options) instead of guessing
  or inventing a dead gate, when an instruction is missing or names an unknown one.
  The agent short-circuits on it (workflow unchanged), the oRPC EditResult carries
  it, and the UI shows the same chips; picking one re-submits the completed
  instruction. A complete instruction still applies directly.

Verified live in the browser (e2e/edit-clarify.e2e.ts): "add a department review"
→ the agent asks which one → pick Finance → a Finance gate is proposed. The model
even omits a department the workflow already gates. Gate green, 194 tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: DylanMerigaud

components/onboarding.tsx

@@ -130,6 +130,7 @@ export const Onboarding = ({
               key={state.data.workflow.name + state.data.employeeCount}
               initial={state.data.workflow}
               suggestions={state.data.suggestions}
+              departments={departmentsOf(state.data.employees)}
               onCurrentChange={onWorkflowChange}
             />
           ) : (
@@ -244,12 +245,36 @@ const WhatCanIChange = () => {
               </li>
             ))}
           </ul>
+          {/* The levers a gate's condition can route on — so "what can I gate on?" is
+              answerable, not guesswork. Values come from the invoice in flight. */}
+          <div className="mt-1 border-t border-line px-2 pb-1 pt-2">
+            <span className="block text-[10px] font-medium uppercase tracking-wider text-faint">
+              Conditions you can route on
+            </span>
+            <span className="mt-1 block font-mono text-[10.5px] leading-relaxed text-muted">
+              amount &gt; $ · department == · variance ≥ % · verdict
+              (clean/exception)
+            </span>
+          </div>
         </div>
       )}
     </div>
   );
 };
 
+/** The distinct, non-empty departments in the org — the values a department gate can
+    route on, so the editor can offer them (and the agent only proposes real ones).
+    Sorted for a stable order; "Company" is the org root, not a buying team, so it's
+    dropped. */
+const departmentsOf = (employees: OrgEmployee[]): string[] => {
+  const set = new Set(
+    employees
+      .map((e) => e.department.trim())
+      .filter((d) => d.length > 0 && d !== "Company"),
+  );
+  return [...set].sort();
+};
+
 /** Initials for an avatar chip ("Riley Carter" → "RC"). */
 const initials = (name: string): string =>
   name

components/workflow-editor.tsx

@@ -37,11 +37,15 @@ type Proposal = {
 export const WorkflowEditor = ({
   initial,
   suggestions = [],
+  departments = [],
   onCurrentChange,
 }: {
   initial: ApprovalWorkflow;
   /** AI-generated next-edit suggestions for the initial workflow (may be empty). */
   suggestions?: string[];
+  /** The departments that exist in the org — shown as chips you can route on, and
+      sent to the edit agent so it only ever proposes a real one. */
+  departments?: string[];
   /** Called with the CURRENT (approved) workflow whenever it changes — the initial
       one, then each kept edit. Never the pending proposal (preview-only). Lets a
       parent (AppView) run the pipeline against exactly what's on screen here. */
@@ -51,6 +55,13 @@ export const WorkflowEditor = ({
   const [proposal, setProposal] = useState<Proposal | null>(null);
   const [instruction, setInstruction] = useState("");
   const [error, setError] = useState<string | null>(null);
+  // A pending clarification from the agent ("which department?") + the instruction
+  // that triggered it, so clicking an option can re-submit a completed instruction.
+  const [clarify, setClarify] = useState<{
+    question: string;
+    options: string[];
+    instruction: string;
+  } | null>(null);
   // Suggestions are consumable: once one produces a proposal it's removed, so a
   // chip never lingers after it's been used.
   const [chips, setChips] = useState<string[]>(suggestions);
@@ -77,7 +88,16 @@ export const WorkflowEditor = ({
       const data = await editMutation.mutateAsync({
         workflow: current,
         instruction: value,
+        departments,
       });
+      // The agent needs a missing piece (e.g. which department) — offer the options
+      // instead of an edit. Remember the instruction so a pick can complete it.
+      if (data.clarify) {
+        setClarify({ ...data.clarify, instruction: value });
+        setInstruction("");
+        return;
+      }
+      setClarify(null);
       const realChanges = data.changes.filter((c) => c.kind !== "unchanged");
       if (realChanges.length === 0) {
         // The agent declined (redundant / off-topic) — say so, don't offer a no-op.
@@ -97,6 +117,14 @@ export const WorkflowEditor = ({
     }
   };
 
+  /** The user picked a clarification option → re-submit the original instruction
+      completed with the choice (re-uses the whole edit flow). */
+  const pickClarifyOption = (option: string) => {
+    const base = clarify?.instruction ?? "";
+    setClarify(null);
+    void submit(`${base} for ${option}`);
+  };
+
   // Validate whatever's on screen (the proposal if pending, else the live one).
   // Errors block applying a proposal; warnings are surfaced but don't block.
   const shown = proposal?.proposed ?? current;
@@ -120,6 +148,7 @@ export const WorkflowEditor = ({
     setProposal(null);
     setChips(suggestions);
     setError(null);
+    setClarify(null);
   };
 
   const changedCount = proposal
@@ -176,11 +205,31 @@ export const WorkflowEditor = ({
             {error}
           </div>
         )}
+        {/* The agent asked for a missing piece (e.g. which department) — show its
+            question + the choices as chips. Clicking one re-submits the completed
+            instruction. Takes over the chip area while it's pending. */}
+        {!proposal && clarify && (
+          <div className="space-y-1.5 rounded-xl bg-accent-soft/40 px-3 py-2.5 ring-1 ring-inset ring-accent/15">
+            <p className="text-[12.5px] font-medium text-ink">
+              {clarify.question}
+            </p>
+            <div className="flex flex-wrap gap-1.5">
+              {clarify.options.map((o) => (
+                <DeptChip
+                  key={o}
+                  label={o}
+                  onClick={() => pickClarifyOption(o)}
+                  disabled={busy}
+                />
+              ))}
+            </div>
+          </div>
+        )}
         {/* AI-suggested next edits for this workflow. Only shown before a pending
             proposal, and only when the model returned some — no fixed chips, so a
             suggestion is always a real, applicable next step. A used chip is
             removed (consumed) once it produces a proposal. */}
-        {!proposal && chips.length > 0 && (
+        {!proposal && !clarify && chips.length > 0 && (
           <div className="space-y-1.5">
             <div className="flex items-center gap-1.5 text-[11px] font-medium uppercase tracking-wider text-faint">
               <SparkIcon />
@@ -201,6 +250,28 @@ export const WorkflowEditor = ({
             </div>
           </div>
         )}
+        {/* Route-by-department chips — the REAL departments from the org, so a user
+            sees what they can route on (and the agent only ever proposes a real one).
+            Clicking a chip asks for a review scoped to that department. Hidden while a
+            proposal or a clarification is pending. */}
+        {!proposal && !clarify && departments.length > 0 && (
+          <div className="space-y-1.5">
+            <div className="flex items-center gap-1.5 text-[11px] font-medium uppercase tracking-wider text-faint">
+              <BuildingIcon />
+              Route by department
+            </div>
+            <div className="flex flex-wrap gap-1.5">
+              {departments.map((d) => (
+                <DeptChip
+                  key={d}
+                  label={d}
+                  onClick={() => submit(`add a review for ${d} bills`)}
+                  disabled={busy}
+                />
+              ))}
+            </div>
+          </div>
+        )}
         <form
           onSubmit={(e) => {
             e.preventDefault();
@@ -303,3 +374,55 @@ const SparkIcon = () => {
     </svg>
   );
 };
+
+/** A small building glyph, marking the route-by-department chips. */
+const BuildingIcon = () => {
+  return (
+    <svg viewBox="0 0 12 12" className="size-3" fill="currentColor" aria-hidden>
+      <path d="M2 11V2.5A.5.5 0 0 1 2.5 2H7a.5.5 0 0 1 .5.5V5H10a.5.5 0 0 1 .5.5V11H2Zm1.5-1H5V8.5H3.5V10Zm0-2.5H5V6H3.5v1.5Zm0-2.5H5V3.5H3.5V5Zm5 5H9V8.5H8.5V10Zm-2 0H7V8.5h-.5V10Zm2-2.5H9V6h-.5v1.5Z" />
+    </svg>
+  );
+};
+
+/**
+ * Stable decorative hue from a label (not semantic — it must NOT reuse ok/danger
+ * tones, which carry meaning). Same name → same colour across renders, so the org's
+ * departments read as a consistent little palette.
+ */
+const hueFor = (label: string): number => {
+  let h = 0;
+  for (const ch of label) h = (h * 31 + ch.charCodeAt(0)) % 360;
+  return h;
+};
+
+/**
+ * A department / clarification chip: the app's interactive accent chip plus a small
+ * coloured dot keyed to the label, so a row of departments looks alive without
+ * inventing a semantic colour scale. Clicking submits the relevant instruction.
+ */
+const DeptChip = ({
+  label,
+  onClick,
+  disabled,
+}: {
+  label: string;
+  onClick: () => void;
+  disabled?: boolean;
+}) => {
+  const hue = hueFor(label);
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      className="inline-flex items-center gap-1.5 rounded-lg bg-subtle px-2.5 py-1.5 text-[12px] font-medium text-muted ring-1 ring-inset ring-line-strong transition-colors hover:bg-accent-soft hover:text-accent hover:ring-accent/30 disabled:opacity-50"
+    >
+      <span
+        aria-hidden
+        className="size-2 rounded-full"
+        style={{ backgroundColor: `hsl(${hue} 55% 55%)` }}
+      />
+      {label}
+    </button>
+  );
+};

db/seed-data.test.ts

@@ -39,6 +39,16 @@ const byId = (id: string): SeedBundle => {
   return b;
 };
 
+test("the demo's department POs carry their buying department", () => {
+  // Three distinct departments are seeded so a department-scoped gate is demonstrable
+  // (and each maps to a real org head). If a future edit drops one, the
+  // "route by department" demo would quietly stop firing.
+  const dept = (id: string) => byId(id).purchaseOrder?.department;
+  assert.equal(dept("INV-2044"), "Product"); // PO-7744
+  assert.equal(dept("INV-2042"), "Operations"); // PO-7742
+  assert.equal(dept("INV-2047"), "Finance"); // PO-7747
+});
+
 test("every seeded document validates against the Zod schema", () => {
   for (const b of SEED_BUNDLES) {
     assert.doesNotThrow(() => Invoice.parse(b.invoice), `${b.id} invoice`);

db/seed-data.ts

@@ -167,7 +167,8 @@ const priceMismatch: SeedBundle = {
     currency: "GBP",
     lineItems: poSteelLines,
     total: sum(poSteelLines),
-    department: "",
+    // Operational/facilities spend → the Operations team owns it (COO is the head).
+    department: "Operations",
   },
   goodsReceipt: {
     grNumber: "GR-5542",
@@ -373,7 +374,8 @@ const cleanChem: SeedBundle = {
     currency: "USD",
     lineItems: chemLines,
     total: sum(chemLines),
-    department: "",
+    // A Finance-controlled budget line → the Finance team reviews it (CFO is the head).
+    department: "Finance",
   },
   goodsReceipt: {
     grNumber: "GR-5547",

e2e/edit-clarify.e2e.ts

@@ -0,0 +1,46 @@
+import { test, expect } from "@playwright/test";
+
+/**
+ * The conversational editor's discoverability + clarifying turn, through the real
+ * browser + the live edit model.
+ *
+ * After discovery the editor shows the org's REAL departments as chips. An ambiguous
+ * instruction ("add a department review", no department named) makes the agent ask
+ * which one instead of inventing a dead gate — the clarifying turn the model chooses
+ * only when a slot is missing. Picking an option completes the instruction and the
+ * gate is proposed. Needs ANTHROPIC_API_KEY + DATABASE_URL (discovery + edit model),
+ * so it's local-only (`pnpm e2e`), recorded HRIS (BAMBOO_HR_API_KEY= unset) is fine.
+ */
+
+const DISCOVERY_TIMEOUT = 90_000;
+const EDIT_TIMEOUT = 45_000;
+
+test("an ambiguous department edit asks which one, then applies the pick", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.getByRole("button", { name: /Discover from BambooHR/ }).click();
+
+  // Discoverability: the real org departments show as chips you can route on.
+  await expect(page.getByText(/Route by department/)).toBeVisible({
+    timeout: DISCOVERY_TIMEOUT,
+  });
+
+  // Ambiguous instruction → the agent asks which department (it must NOT guess).
+  await page
+    .getByPlaceholder(/Describe a change/)
+    .fill("add a department review");
+  await page.getByRole("button", { name: /^Edit$/ }).click();
+  await expect(page.getByText(/which department/i)).toBeVisible({
+    timeout: EDIT_TIMEOUT,
+  });
+
+  // Pick Finance from the clarification options → it completes the instruction and
+  // proposes a Finance-scoped gate (the diff bar appears).
+  await page.getByRole("button", { name: "Finance" }).last().click();
+  await expect(page.getByText(/not applied yet/i)).toBeVisible({
+    timeout: EDIT_TIMEOUT,
+  });
+  // The proposed graph mentions Finance (the new gate's department scope).
+  await expect(page.getByText(/Finance/).first()).toBeVisible();
+});

eval/edit-agent-run.ts

@@ -26,6 +26,10 @@ import { validateWorkflow, isActivatable } from "@/lib/workflow-validate";
 
 const dryRun = process.argv.includes("--dry-run");
 
+/** The departments the agent may scope a gate to (the demo org's set). A live case
+    naming one outside this list should make the planner clarify, not invent. */
+const EVAL_DEPARTMENTS = ["Finance", "Operations", "Product", "Sales"];
+
 const loadEnv = (): void => {
   for (const f of [".env.local", ".env"]) {
     try {
@@ -89,7 +93,9 @@ const main = async (): Promise<void> => {
   const rows: Row[] = [];
   for (const c of AGENT_CASES) {
     const model = dryRun ? stubModel(c) : (liveModel ?? stubModel(c));
-    const result = await runEditAgent(model, EDIT_FIXTURE, c.instruction);
+    const result = await runEditAgent(model, EDIT_FIXTURE, c.instruction, {
+      departments: EVAL_DEPARTMENTS,
+    });
     const row = score(c, result);
     rows.push(row);
     console.log(

lib/orpc/router.ts

@@ -88,12 +88,13 @@ const editWorkflow = rateLimited
   .output(EditResult)
   .handler(async ({ input }) => {
     try {
-      const { proposed, changes, reason } = await runEditAgent(
+      const { proposed, changes, reason, clarify } = await runEditAgent(
         anthropicPlanModel,
         input.workflow,
         input.instruction,
+        { departments: input.departments },
       );
-      return { proposed, changes, reason };
+      return { proposed, changes, reason, clarify };
     } catch {
       throw new ORPCError("UNPROCESSABLE_CONTENT", {
         message:

lib/orpc/schemas.ts

@@ -67,10 +67,23 @@ const StepChangeSchema = z.discriminatedUnion("kind", [
 export const EditInput = z.object({
   workflow: ApprovalWorkflow,
   instruction: z.string().trim().min(1, "an instruction is required"),
+  /** The departments that exist in the client's org, so a department gate can only
+      target a real one (the agent returns a clarify when it can't). Optional —
+      defaults to none, in which case any department instruction is clarified. */
+  departments: z.array(z.string()).default([]),
+});
+
+/** The agent asks for a missing piece (e.g. which department) — the UI shows the
+    question + clickable options; the user's pick re-submits a completed instruction. */
+const ClarificationSchema = z.object({
+  question: z.string(),
+  options: z.array(z.string()),
 });
 
 export const EditResult = z.object({
   proposed: ApprovalWorkflow,
   changes: z.array(StepChangeSchema),
   reason: z.string().nullable(),
+  /** Set when the agent needs a clarification before editing (workflow unchanged). */
+  clarify: ClarificationSchema.nullable(),
 });