Spec 010: plan, research and 24 tasks — build the endpoint slow, unblock the website repo

[adamjohnwright]

Spec 010 had a spec and a contract and no plan. This adds plan.md, research.md, quickstart.md and 24 tasks — and takes a position on sequencing.

The sequencing call

Build the endpoint first, and slow. The website session is blocked on nothing but this service's absence. An endpoint that answers correctly in fifteen seconds unblocks their panel and their token handshake; an endpoint that doesn't exist blocks them completely.

So FR-005's 2s/10s budget is explicitly not a gate on the first increment. MVP is Phases 1–4: correct, verified, streaming, at roughly today's p50. Latency is Phase 5 and runs alongside the handover.

Three things from reading the code rather than assuming

AgentGraph exposes ainvoke and nothing else. Chainlit's streaming comes from a Chainlit callback handler, not any graph-level API — so there is no surface an HTTP handler can use. The plan takes LangGraph's astream_events, names a queue-fed callback as the fallback, and requires a test that tokens actually arrive. A surface that completes without streaming would pass a 200 check, which is exactly how the userguide shell fooled two sessions today.

The FastAPI app doesn't hold a graph at all — chat-chainlit.py constructs it. Building a second would pay 51.5s of startup twice and let the panel and the chat answer differently, which SC-003 forbids. One instance, shared.

Citations come from retrieval, not prose. The answer prompt emits <a href> anchors inline, and parsing those out of a token stream would couple the wire contract to prompt wording — which changed twice this week. Retrieved documents already carry st_id. The cost is stated rather than hidden: citations become what retrieval found rather than what the answer used.

Where two principles meet

FR-006 says fail invisibly; Principle IV says fail loudly. Not in conflict, but the line is written down:

• Misconfiguration stops the process — a missing verifying key means the endpoint refuses to start, because one that accepts everything would test clean
• A runtime failure answering one question returns state: failed and logs, because a search page must not break

Also noted

verify_captcha_middleware intercepts every path under CHAINLIT_URI, so a new route needs it to pass /chat/api/ through — with a characterization test pinning the middleware's current behaviour first. That middleware is where today's silent-captcha-bypass bug lived, so adding a route beside it warrants the care.

Docs only, no code. 333 tests still green.

🤖 Generated with Claude Code