Merge: HRIS onboarding + conditional approval workflow + chat-edit + lint alignment

The product became two surfaces: onboarding (agent derives the approval workflow
from the HRIS, conversational edits with preview/approve/revert) and operations
(invoices run through that conditional workflow DAG). Plus a full code-quality pass
(typed env, ESLint aligned-and-stricter than the sibling repo, two evals).

All green on the branch: lint, typecheck, knip, 149 tests, build, sanity + both evals.

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

Author: DylanMerigaud

.github/workflows/ci.yml

@@ -8,7 +8,7 @@ on:
 
 jobs:
   check:
-    name: format · typecheck · knip · test · build · eval
+    name: format · typecheck · lint · knip · test · build · eval
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -29,6 +29,9 @@ jobs:
       - name: Typecheck
         run: pnpm typecheck
 
+      - name: Lint (ESLint — cast/any hygiene)
+        run: pnpm lint
+
       - name: Dead-code check (knip)
         run: pnpm knip
 
@@ -51,3 +54,9 @@ jobs:
       # scoring offline (a perfect score is expected). Run the real eval locally.
       - name: Investigator eval (dry-run, no API calls)
         run: pnpm eval --dry-run
+
+      # The conversational-edit eval scores whether the model maps an instruction
+      # to the right WorkflowEditOp. `--dry-run` exercises the corpus + scoring
+      # offline; the live run (real model, 8/8) is local.
+      - name: Workflow-edit eval (dry-run, no API calls)
+        run: pnpm eval:edit --dry-run

README.md

@@ -0,0 +1,82 @@
+import { defaultHris } from "@/lib/hris";
+import { deriveWorkflow } from "@/lib/onboarding";
+import { anthropicProposalModel } from "@/lib/onboarding-model";
+import { checkRateLimit, clientIpFrom } from "@/lib/ratelimit";
+
+/**
+ * POST /api/onboarding — the discovery step a forward-deployed engineer runs once
+ * per client. It reads the client's org from the HRIS (BambooHR, scoped to the
+ * demo client's division — or the recorded sample org when no key is set), then
+ * the onboarding agent derives a proposed approval workflow + flags the org's
+ * data-quality issues for a human to resolve.
+ *
+ * Returns the normalised org, the derived conditional workflow (the DAG the
+ * pipeline executes), and the issues — the payload the onboarding UI renders for
+ * validation. The result is a PROPOSAL: a human approves it before it goes live.
+ *
+ * Runtime: NODE (the HRIS adapter and the model SDK need it). Rate-limited like
+ * the run route — each call spends model tokens.
+ */
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+export const maxDuration = 60;
+
+export const POST = async (request: Request): Promise<Response> => {
+  const ip = clientIpFrom(request.headers);
+  const verdict = await checkRateLimit(ip);
+  if (!verdict.ok) {
+    return Response.json(
+      {
+        error: `You've hit the demo limit. Try again in about ${Math.max(
+          1,
+          Math.ceil(verdict.retryAfterSeconds / 60),
+        )} minute(s).`,
+      },
+      {
+        status: 429,
+        headers: { "retry-after": String(verdict.retryAfterSeconds) },
+      },
+    );
+  }
+
+  // 1. Read the client's org from the HRIS (live scoped, or recorded sample).
+  let org: Awaited<ReturnType<ReturnType<typeof defaultHris>["fetchOrg"]>>;
+  try {
+    org = await defaultHris().fetchOrg();
+  } catch {
+    return Response.json(
+      { error: "Could not read the org from the HRIS." },
+      { status: 502 },
+    );
+  }
+  if (org.employees.length === 0) {
+    return Response.json(
+      {
+        error:
+          "The HRIS returned no employees for this client (is the org seeded?).",
+      },
+      { status: 404 },
+    );
+  }
+
+  // 2. The onboarding agent derives the workflow + explains the issues.
+  try {
+    const { workflow, proposal, issues } = await deriveWorkflow(
+      anthropicProposalModel,
+      org,
+    );
+    return Response.json({
+      source: org.source,
+      employeeCount: org.employees.length,
+      employees: org.employees,
+      workflow,
+      proposal,
+      issues,
+    });
+  } catch {
+    return Response.json(
+      { error: "The onboarding model failed to derive a workflow." },
+      { status: 502 },
+    );
+  }
+};

app/api/onboarding/route.ts

@@ -21,10 +21,10 @@ import { renderInvoicePdf } from "@/lib/invoice-pdf";
 
 export const runtime = "nodejs";
 
-export async function GET(
+export const GET = async (
   _request: Request,
   { params }: { params: Promise<{ id: string }> },
-): Promise<Response> {
+): Promise<Response> => {
   const { id } = await params;
 
   let invoice: Awaited<ReturnType<typeof loadInvoiceById>>;
@@ -50,4 +50,4 @@ export async function GET(
       "cache-control": "public, max-age=3600, immutable",
     },
   });
-}
+};

app/api/pdf/[id]/route.ts

@@ -1,14 +1,14 @@
-import { mastra } from "@/src/mastra";
 import { loadRunBundle } from "@/db/client";
 import { profileById } from "@/db/client-profiles";
-import { toTraceEvent, pipelineErrorEvent, type TraceEvent } from "@/lib/trace";
-import { ndjsonLine } from "@/lib/ndjson";
-import { checkRateLimit, clientIpFrom } from "@/lib/ratelimit";
 import {
   RunRequest,
   STREAM_CONTENT_TYPE,
   type StreamDone,
 } from "@/lib/api-types";
+import { ndjsonLine } from "@/lib/ndjson";
+import { checkRateLimit, clientIpFrom } from "@/lib/ratelimit";
+import { toTraceEvent, pipelineErrorEvent, type TraceEvent } from "@/lib/trace";
+import { mastra } from "@/src/mastra";
 
 /**
  * POST /api/run — execute the procure-to-pay pipeline for one seeded invoice and
@@ -37,11 +37,11 @@ export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 export const maxDuration = 60;
 
-function line(obj: unknown): Uint8Array {
+const line = (obj: unknown): Uint8Array => {
   return new TextEncoder().encode(ndjsonLine(obj));
-}
+};
 
-export async function POST(request: Request): Promise<Response> {
+export const POST = async (request: Request): Promise<Response> => {
   // 0. Rate-limit by IP first — before any work or model calls. The demo is
   //    public and each run spends Anthropic tokens, so this caps abuse. Fails
   //    open if Redis isn't configured (see lib/ratelimit.ts).
@@ -64,27 +64,29 @@ export async function POST(request: Request): Promise<Response> {
 
   // 1. Parse + validate the request body.
   let id: string;
-  let decision: "approve" | "reject" | undefined;
+  let decisions: Record<string, "approve" | "reject">;
   let profileId: string | undefined;
   try {
     const body: unknown = await request.json();
     const parsed = RunRequest.parse(body);
     id = parsed.id;
-    decision = parsed.decision;
+    decisions = parsed.decisions ?? {};
     profileId = parsed.profileId;
   } catch {
     return Response.json(
       {
-        error: 'Body must be { id: string, decision?: "approve" | "reject" }.',
+        error:
+          'Body must be { id: string, decisions?: { [stepId]: "approve" | "reject" } }.',
       },
       { status: 400 },
     );
   }
-  // The reviewer's decision maps to the workflow's humanApproval input. No
-  // decision → "pending" (an exception pauses for a human). "approve"/"reject"
-  // are phase-2 resumes. Recomputing the cheap deterministic prefix instead of
-  // restoring a persisted snapshot is what keeps the human-in-the-loop stateless.
-  const humanApproval = decision ?? "pending";
+  // The reviewer's per-step decisions drive the approval workflow. None → every
+  // active gate pauses as pending (phase 1). A resume sends decisions by step id
+  // (phase 2); the bill posts only once all active gates are approved. Recomputing
+  // the deterministic prefix from the decisions (not a persisted snapshot) is what
+  // keeps the human-in-the-loop stateless.
+  const hasDecisions = Object.keys(decisions).length > 0;
 
   // 2. Load the seeded document bundle (READ ONLY). Done before opening the
   //    stream so a missing invoice / missing DB config is a clean HTTP error
@@ -129,12 +131,12 @@ export async function POST(request: Request): Promise<Response> {
             purchaseOrder: bundle.purchaseOrder,
             goodsReceipt: bundle.goodsReceipt,
             priorInvoiceNumbers: bundle.priorInvoiceNumbers,
-            humanApproval,
-            // On a phase-2 resume (approve/reject) the workflow re-runs from the
+            decisions,
+            // On a phase-2 resume (decisions present) the workflow re-runs from the
             // top, but the document was already read — skip the (costly) vision
             // call the second time. The reveal from phase 1 still stands.
-            skipExtraction: decision !== undefined,
-            // Run under the requested client profile (tolerances + approval tiers);
+            skipExtraction: hasDecisions,
+            // Run under the requested client profile (tolerances + approval workflow);
             // defaults to the standard profile.
             profile: profileById(profileId),
           },
@@ -176,4 +178,4 @@ export async function POST(request: Request): Promise<Response> {
       "x-accel-buffering": "no",
     },
   });
-}
+};

app/api/run/route.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+
+import { ApprovalWorkflow } from "@/lib/approval-workflow";
+import { checkRateLimit, clientIpFrom } from "@/lib/ratelimit";
+import { proposeEdit } from "@/lib/workflow-edit";
+import { anthropicEditModel } from "@/lib/workflow-edit-model";
+
+/**
+ * POST /api/workflow/edit — propose a conversational edit to an approval workflow.
+ *
+ * Body: { workflow: ApprovalWorkflow, instruction: string }. Returns the PROPOSED
+ * workflow plus the diff vs the current one. Nothing is persisted or applied — the
+ * client shows the diff and the human approves (swaps it in) or reverts (discards).
+ * The pipeline only ever runs the workflow the human has approved.
+ */
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+export const maxDuration = 60;
+
+const EditRequest = z.object({
+  workflow: ApprovalWorkflow,
+  instruction: z.string().trim().min(1, "an instruction is required"),
+});
+
+export const POST = async (request: Request): Promise<Response> => {
+  const ip = clientIpFrom(request.headers);
+  const verdict = await checkRateLimit(ip);
+  if (!verdict.ok) {
+    return Response.json(
+      { error: "Rate limit hit — try again shortly." },
+      {
+        status: 429,
+        headers: { "retry-after": String(verdict.retryAfterSeconds) },
+      },
+    );
+  }
+
+  let workflow: z.infer<typeof EditRequest>["workflow"];
+  let instruction: string;
+  try {
+    const parsed = EditRequest.parse(await request.json());
+    workflow = parsed.workflow;
+    instruction = parsed.instruction;
+  } catch {
+    return Response.json(
+      { error: "Body must be { workflow, instruction }." },
+      { status: 400 },
+    );
+  }
+
+  try {
+    const { proposed, op, changes } = await proposeEdit(
+      anthropicEditModel,
+      workflow,
+      instruction,
+    );
+    // `op.reason` (only present on a `none`) explains why nothing changed.
+    const reason = op.op === "none" ? op.reason : null;
+    return Response.json({ proposed, changes, reason });
+  } catch {
+    // A validation failure (the model produced an invalid graph) or a model error
+    // both land here — the edit is simply not offered, the current workflow stands.
+    return Response.json(
+      {
+        error:
+          "Could not produce a valid edit for that instruction. The current workflow is unchanged — try rephrasing.",
+      },
+      { status: 422 },
+    );
+  }
+};

app/api/workflow/edit/route.ts

@@ -1,7 +1,7 @@
-import type { Metadata } from "next";
-import { GeistSans } from "geist/font/sans";
 import { GeistMono } from "geist/font/mono";
-import "./globals.css";
+import { GeistSans } from "geist/font/sans";
+import type { Metadata } from "next";
+import "@/app/globals.css";
 
 const SITE_URL = "https://ledgerloop-eta.vercel.app";
 const TITLE = "ledgerloop — agentic procure-to-pay";

app/layout.tsx

@@ -1,4 +1,4 @@
-import { Dashboard } from "@/components/dashboard";
+import { AppView } from "@/components/app-view";
 import { SocialLinks } from "@/components/social-links";
 import { listInvoiceQueue, type QueueItem } from "@/db/client";
 import { PIPELINE_MODEL } from "@/src/mastra/model";
@@ -40,15 +40,15 @@ export default async function Page() {
         ) : queue.length === 0 ? (
           <SetupNotice detail="The database is reachable but empty — run `pnpm db:seed` to load the demo invoices." />
         ) : (
-          <Dashboard queue={queue} />
+          <AppView queue={queue} />
         )}
       </div>
       <Footer />
     </main>
   );
 }
 
-function Header() {
+const Header = () => {
   return (
     <header className="mb-6">
       <div className="flex flex-wrap items-end justify-between gap-3">
@@ -77,9 +77,9 @@ function Header() {
       </div>
     </header>
   );
-}
+};
 
-function FlowChip({ n, label }: { n: number; label: string }) {
+const FlowChip = ({ n, label }: { n: number; label: string }) => {
   return (
     <span className="inline-flex items-center gap-1.5 rounded-full bg-surface px-2.5 py-1 ring-1 ring-inset ring-line">
       <span className="flex h-4 w-4 items-center justify-center rounded-full bg-accent-soft text-[9px] font-semibold text-accent">
@@ -88,17 +88,17 @@ function FlowChip({ n, label }: { n: number; label: string }) {
       {label}
     </span>
   );
-}
+};
 
-function Arrow() {
+const Arrow = () => {
   return (
     <span aria-hidden className="text-line">
       →
     </span>
   );
-}
+};
 
-function SetupNotice({ detail }: { detail: string }) {
+const SetupNotice = ({ detail }: { detail: string }) => {
   return (
     <div className="rounded-xl border border-warn-line bg-warn-soft/50 px-5 py-4 text-[13px] text-ink">
       <p className="font-medium">Almost there — the demo needs its database.</p>
@@ -120,9 +120,9 @@ function SetupNotice({ detail }: { detail: string }) {
       </p>
     </div>
   );
-}
+};
 
-function Footer() {
+const Footer = () => {
   return (
     <footer className="mt-8 flex flex-wrap items-center justify-between gap-3 border-t border-line pt-4 text-[12px] text-muted">
       <p>
@@ -137,4 +137,4 @@ function Footer() {
       </div>
     </footer>
   );
-}
+};