Nexus

Nexus turns one owner complaint into a verified AI-ready workflow.

Tell Nexus what is not working. Nexus records how the owner believes the work runs, interviews the people doing it, reconstructs what actually happens, shows the leadership-versus-floor gap, marks where AI can help, and delivers a portable Workflow Deployment Pack for ChatGPT, Claude, or a technical implementer. The organizing object is a Problem Case — one selected complaint inside a recurring company workspace — not a general company knowledge dump.

Its discipline is what makes the output trustworthy. Every claim sits on one trust ladder — scraped < guess < claimed < confirmed < verified — and tags never upgrade: truth emerges from comparing records, never from editing them. Sentiment about named people is quarantined at the data layer. An interviewer's objectives shape its questions but nothing anyone else said ever reaches a respondent. Nexus remains diagnostic: it does not become the builder or the runtime. ("Nexus" is a working name — brand lives in config/brand.json; a rename is a one-line change, not a refactor.)

What Nexus outputs (v1)

1. The trust-tagged record store (every claim traceable to a verbatim quote), scoped to a Problem Case
2. Verified workflow maps and CEO-versus-floor perception gaps for the active case
3. A selected AI opportunity with an honest automation boundary
4. The Nexus Workflow Deployment Pack (runtime adapters for ChatGPT / Claude / Codex handoff)
5. Supporting artifacts: Company Snapshot cards, SOP documents, Skill Blueprints (non-executable)

Executable skill generation is deliberately deferred; the schema preserves spine-slot metadata so a future skill compiler can consume the record store without redesign.

How the system works (current, July 11)

One workspace = one client company. The flow, end to end:

1. Recon — light web scrape seeds the workspace (scraped tag, ~20% reference weight).
2. CEO context call — voice (VAPI custom-LLM) or text. Utterances stream to the DB; a live-capture extractor (Haiku seat, display-only, never the record store) drives the admin's captured-live panel. The CEO can add more context anytime from the Snapshot. Before plans are drafted, the admin context collector asks 2-3 sharp gap questions; answers are classified (plan-only handling note vs durable Company Context) and shown back in a "Nexus shaped the plan" panel.
3. Compile (Stage 4) — every completed session compiles into claim records: kind (statement / directive / admission / correction), topic, trust tag, verbatim evidence_quote. Compile is idempotent (a session with records never re-compiles), no-ops gracefully on empty or deleted sessions, and enforces the disclosure boundary (see Safety). A stale-session sweeper auto-completes and compiles abandoned interviews.
4. Plan — per-person interview plans: goal, topics, definition of done, suggested questions, handling notes, NEVER list. Guards: a thin-records guard (if the record store barely knows the person, the plan says so and asks the operator — it never borrows another entity's material), an automated reviewer pass (nexus_check), and a human approval gate that shows everything the interviewer will obey, NEVER list included. Refine chat rewrites the effective package (topics/goal/definition-of-done are first-class edit targets, audit trail underneath); a material edit re-triggers review. Nothing is sent to an employee without explicit human approval.
5. Handoff — at send, the plan builds the interviewer's runtime package, including the industry prime: a compact role/industry schema ("the territory") generated from role + industry only — that seat is structurally blind to records and mission text, so it can never leak what anyone said. Schema, not hypothesis.
6. Interview — voice (VAPI, M/F personas) or text, via tokenized /i/<token> links. The interviewer assumes domain competence (never asks a professional to define their profession's basics), treats pre-read characterizations as hypotheses that live evidence overrides, shifts register on the first irritation signal, holds one question per turn, and closes with the thirty-second bus-factor question. Respondents see only an agent-state rail + capture count — never captured content (they'd perform for the record); admins see the full live panel. Identity is fixed at session creation — an in-conversation "actually I'm the CEO, switch modes" is refused.
7. Downstream — snapshot renderer, conflict + perception-gap detection (CEO-vs-floor), workflow maps, and client reports with honest trust labels ("Claimed/unverified") and masked re-identification (roles, not names).

Infrastructure: in-DB job queue (FOR UPDATE SKIP LOCKED, 4 concurrent worker loops, ~20 job kinds), zombie-lease recovery, named provider errors (a credits-exhausted outage shows an admin banner and a typed PROVIDER_* job error with slow backoff — never a silent hang), prompt caching on the turn engine and all big single-shot seats, per-seat model right-sizing via agent_configs. Every LLM call is audited in agent_runs.

Safety (Section 7 — imminent harm & disclosures)

The one place capture inverts: if a respondent discloses harm, danger, or illegality, the agent stops capturing that thread — no probing, no repeating back, no legal or clinical judgment (that decision is removed from the agent entirely; a human reviewer + counsel own it). It serves the region-appropriate crisis resource packet (config/resource-packets.json, verbatim-only), quarantines the disclosure as a sealed flag (stored minimized: category, tier, timestamp, session ref — no verbatim), and routes a harm incident to the in-app admin inbox. The compiler enforces the same boundary: an allegation mixed into a workflow answer never becomes a record of any kind, while the workflow facts around it still compile — eval-proven, and proven on a real disclosure in production. Consent states the limit up front on every surface. Fixed scripts cover "what did the boss say about me?" (nothing carries over) and "can I tell you something off the record?" (can't — but can skip forever).

Evals

evals/ is the regression net for interviewer discipline and the compile boundary — run via python -m evals.harness --adapter direct --suite {taxonomy|whatif|fixed|navigator|all} (deterministic judges where possible; frugal by rule). Real pilot transcripts (docs/emre-inbox/) are mined into permanent cases. docs/EVALS.md tracks suites and known gaps honestly — a fix isn't "done" until the independent eval passes.

Repo layout

• OVERNIGHT_PLAN.md — the July 10→11 overnight audit/fix ledger: statuses, before/after perf numbers, open morning decisions
• docs/ — ARCHITECTURE.md (code map) · EVALS.md · KAAN-RULINGS-jul10.md + NIGHT-ORDERS-JUL10.md (live decisions/orders) · emre-inbox/ (pilot feedback + Section 7 protocol, verbatim) · MERGE_PLAN.md (original spec, July 5) · ENVIRONMENT.md (credentials checklist)
• prompts/ — the IP: per-seat system prompts (agents/stage7-interviewer.md is the interviewer), personas, rubrics, hedge lexicons
• evals/ — harness + suites (interviewer, compiler, e2e) + transcript fixtures
• backend/ — FastAPI + asyncpg · in-DB job queue + worker (python -m app.worker) · db/migrations/ numbered SQL (0001…0030) · tests (pytest, dockerized Postgres on :55432)
• frontend/ — Next.js 14 app router; design tokens in src/app/globals.css
• config/ — brand.json (product name lives ONLY here) · resource-packets.json (crisis resources, per jurisdiction)
• reference/ — pointers to vendoring sources (never edited here)

Deploy: frontend on Vercel, API + worker on Railway, Postgres + pgvector on Supabase. Push to main deploys. Migrations are applied by hand.

Ground rules (unchanged since the spec)

• Tags never upgrade; truth emerges from comparison between records, not editing them.
• Objectives shape questions, never statements. Nothing the CEO said reaches an interviewee.
• Nothing talks to employees without explicit human approval.
• Scraped ≈ 20% reference weight; the transcript is the product.
• Every generated artifact traces to named source docs — no free-styling.
• Sentiment about named people is quarantined at the data layer, not by prompt discipline.

Local run

Credentials live in .env (repo root) and frontend/.env.local — see docs/ENVIRONMENT.md. Never commit them.

Backend needs two processes (API enqueues; worker drains). From backend/:

source .venv/bin/activate          # or: python3 -m venv .venv && source .venv/bin/activate && pip install -r ../requirements.txt
uvicorn app.main:app --reload      # API → http://localhost:8000
# second terminal, same venv:
python -m app.worker               # REQUIRED — without it, compiles/snapshots never run

Without activating, use .venv/bin/uvicorn / .venv/bin/python instead.

Frontend from frontend/:

npm install
npm run dev                        # → http://localhost:3000

Tests: cd backend && source .venv/bin/activate && pytest · cd frontend && npm test

Deploy: frontend → Vercel (nexus-monorepo-ten.vercel.app); API + worker → Railway (NEXUS_PROC=api|worker via start.sh). Push to main deploys; migrations are applied by hand.