Merge pull request 'fix: count a run completed at the DONE transition, not after it (researchx#28)' (#29 ) from po/fix-cost-counter-race into main

Reviewed-on: #29
Merge branch 'main' into po/fix-cost-counter-race
2026-10-27 22:36:42 +00:00 · 2026-10-27 22:35:50 +00:00 · 2026-10-27 22:35:39 +00:00 · 2026-10-27 05:18:51 +00:00 · 2026-10-27 04:34:06 +00:00 · 2026-10-27 03:41:30 +00:00
27 changed files with 640 additions and 144 deletions
@@ -1,8 +1,8 @@
 {
-  "phase": 4,
-  "stage": "execute",
+  "phase": 5,
+  "stage": "complete",
  "milestone": "v0.2",
-  "phase_role": "execution",
+  "phase_role": "final",
  "attempts": 0,
-  "updated_at": "2026-09-27T14:15:00Z"
+  "updated_at": "2026-09-27T16:30:00Z"
 }
@@ -215,4 +215,5 @@ The plan is sound with fixable gaps. The evidence base is unusually strong for a
 | G-010 | Meta | Pre-agreed contingency lever: if P2/P4 slip beyond one extension cycle, Deep Report (depth 3) defers to v0.3 and the MVP ships Rapid Answer end-to-end; pulling the lever requires owner sign-off at a gate. | 0.65 |

 ### Escalations
- [G-009] Axis 2 — Owner ratification required at the P5 gate (D-018 halt): the v0.2 MVP demonstrates the **live core research loop only**; the remaining approved-prototype surfaces (Library, Settings persistence, Suggestions, Refine, graph/inbox previews, profile) remain mock-bound until v0.3+, and the live-mode gate demo requires a local backend + keys (or runs in mock mode) since D-019 forbids deploys. This redefines what "MVP done" looks like at the demo and must not be discovered by the owner at the gate — it must be ratified in advance. Engineering-side handling is bound in G-002/G-003; the ratification itself is unresolved until the owner records it.
+- [G-009] Axis 2 — Owner ratification required at the P5 gate (D-018 halt): the v0.2 MVP demonstrates the **live core research loop only**; the remaining approved-prototype surfaces (Library, Settings persistence, Suggestions, Refine, graph/inbox previews, profile) remain mock-bound until v0.3+, and the live-mode gate demo requires a local backend + keys (or runs in mock mode) since D-019 forbids deploys. This redefines what "MVP done" looks like at the demo and must not be discovered by the owner at the gate — it must be ratified in advance. Engineering-side handling is bound in G-002/G-003; the ratification itself is unresolved until the owner records it.
+  - **RESOLVED 2026-09-27: RATIFIED.** Owner approval recorded via /ci-run 'APPROVED' at the v0.2.5 gate (decision commit 4721c2a), following the owner-directed UAT staging at https://research.coreci.dev. Live-mode scope = core research loop only is the accepted MVP boundary; mock-bound surfaces move to v0.3+.
@@ -40,7 +40,7 @@ reason: "v0.2 is the MVP: FastAPI backend + engine + adapters + trust loop (back

 ### security-engineer (phase-specific: P2)
 - **Domain**: security
- **Active**: true (P2 only)
+- **Active**: false (P2 shipped — removed per phase-specific policy)
 - **Phase-specific**: true
 - **Frameworks**: httpx, pytest, STRIDE analysis
 - **Constraints**: secrets resolve from env-file scopes only (OLLAMA_API_KEY, TAVILY_API_KEY, GITEA_TOKEN via .ciagent/.env.secrets) — never shell env, never logged, never in git; liveness verification and trust-loop code must not leak keys in errors or traces; SSRF guard for fetched URLs (private-address refusal); authority tiering must not phone home
@@ -1,61 +1,44 @@
-# PLAN — Milestone v0.2 Phase 4: Hardening + Adversarial Suite + E2E
+# PLAN — Milestone v0.2 Phase 5 (FINAL): Review + Audit + Ship

 ---
-phase: 4
+phase: 5
 milestone: v0.2
-status: planned
+status: executed
 must_haves:
-  - "Adversarial suite (REQ-32): hallucinated-URL writer caught by the verifier (report cites a URL never visited/anchored → flagged in ledger, export gate fails it); quote-anchor mismatch detection (near-miss and fabricated quotes flagged, never silently accepted); pause/resume mid-depth-loop over the HTTP API"
-  - "E2E happy path (REQ-17): new user → research running in ≤3 clicks using defaults only, validated against the REAL stack (FastAPI + engine via ASGI, live ApiClient binding at the boundary) — not the mock"
-  - "Export round-trip (REQ-34): report + ledger + citations survive as real links — markdown export carries citation URLs, JSON export round-trips into pydantic models"
-  - "Live-adapter smoke test tier (opt-in, G-004): keyed tests for Ollama + Tavily marked skippable when keys absent — zero-key CI unaffected"
-  - "Monorepo tooling polish (REQ-33 completion): one-command install/dev documented + root convenience scripts"
+  - "Multi-persona full-milestone review: 4 P0 + 15 P1 + 15 P2 found; all 4 P0s fixed in-phase with attack-proofs (A1 tautological anchoring → real writer-quote extraction; C2 gate denominator → cited-URL scoped; C1 zombie runs → shape-validated plans + catch-all FAILED persist; S1 fetch SSRF → per-hop re-guarding); 6 cheap P1s fixed (approve-with-plan, FAILED status, length caps, probe wiring, README env-var + adapter honesty)"
+  - "Audit: PASS-WITH-NOTES — reconstruction PASS (all REQ-01..34 covered across v0.2.0–v0.2.4), secrets clean (zero key values in history), branch hygiene exact; critical notes fixed in-phase (REQUIREMENTS traceability un-staled, P5 PLAN written, ROADMAP P5 status, security-engineer persona deactivated per its removal note)"
+  - "Milestone ship: v0.2.5 tagged as the MVP release candidate — the pipeline then HALTS at the merge_to_main owner approval gate (D-018)"
+  - "G-009 escalation presented at the gate: the owner ratifies that live mode covers the core research loop only (G-002); remaining prototype surfaces stay mock-backed to v0.3+"
 personas:
-  - backend-engineer
-  - frontend-engineer
  - ci-lead-developer
-requirements: [REQ-17, REQ-32, REQ-34]
+requirements: [REQ-01, REQ-02, REQ-03, REQ-04, REQ-05, REQ-06, REQ-07, REQ-08, REQ-09, REQ-10, REQ-11, REQ-12, REQ-13, REQ-14, REQ-15, REQ-16, REQ-17, REQ-18, REQ-19, REQ-20, REQ-21, REQ-22, REQ-23, REQ-24, REQ-25, REQ-26, REQ-31, REQ-32, REQ-33, REQ-34]
 ---

 ## User-Facing Surface

-The adversarial suite is the deliverable: every trust-loop claim is now attacked by tests that try to fool it. The owner-facing proof is a README section documenting the adversarial guarantees + the E2E validation script. No UI changes.
+The MVP release candidate: the approved v0.1 prototype frontend (Ask → Choose → Plan & Run → Reading Room, all 8 cards, shell, library, settings) now backed by a real FastAPI research engine in live mode — methodology registry (Rapid Answer + Deep Report), 12-dial framework, asyncio state machine with durable pause/cancel/resume, visited-only evidence store, attack-proven trust loop (quote anchoring, SSRF-guarded liveness, citation ledger, ≥99% export gate with zero-unanchored requirement), SSE live trace, adversarial suite (14 attacks), E2E happy path on the real stack. Releases v0.2.0–v0.2.5.

-## Happy Path (P4 — written before execute)
+## Happy Path (owner review script)

-1. `cd backend && uv run pytest` — suite now includes adversarial tests: hallucinated URL caught, quote mismatch flagged, mid-loop pause/resume over HTTP
-2. `uv run pytest -m live` (keys present) or default skip — live smoke tier
-3. Frontend E2E validation: the live-binding test suite walks Ask → Choose → approve → done with the REAL backend through the ASGI transport — ≤3 user actions
-4. Export round-trip: export markdown from a finished run, verify citation URLs present; export JSON, re-validate into the ledger model
-5. All gates green: backend ruff/mypy/pytest, frontend typecheck/lint/test/build
+1. `cd backend && uv sync && uv run pytest` — 129 tests green, zero API keys (live tier: `uv run pytest -m live`, skips cleanly)
+2. `cd frontend && corepack pnpm install && corepack pnpm test` — 97 tests green (90 component + 5 live-binding + 2 real-stack E2E)
+3. `uv run uvicorn researchx.api.app:app --port 8000` + `NEXT_PUBLIC_RESEARCHX_API_MODE=live corepack pnpm dev` → http://localhost:3000 → Ask a question → Research this → pick Deep Report → Start research → approve the plan (3 clicks) → live SSE trace → report with anchored citations → ledger → export Markdown (citation links) / JSON (backend-schema round-trip)
+4. `uv run python -m researchx.engine.demo` — full pipeline on fakes, artifacts in a temp runs dir
+5. Owner decision: approve → milestone merge to main + v0.2.5 published as the MVP release; or direct changes → binding fix cycle

-## UX Acceptance Criteria (P4)
+## UX Acceptance Criteria

- Trust claims are adversarially proven, not asserted: the suite demonstrates attacks being caught
- The 3-click criterion is measured on the real stack, defaults only
- Zero-key test discipline holds; live tier is opt-in and never blocks CI
+- ≤3 clicks from cold start to initiated research, validated on the real stack (REQ-17)
+- Every trust claim attack-proven: hallucinated citations fail the export gate; fabricated quotes on real passage IDs flag unanchored; SSRF redirects die; pause/resume/cancel survive the loop
+- Honest scope: live mode = core research loop (G-002); library/settings/suggestions/refine stay mock-backed until v0.3+ — ratified at this gate (G-009)
+- No secret value in any artifact, trace, or log; zero-key test discipline throughout

-## Tasks (waves)
+## What this phase did

-### Wave 1 — Adversarial suite (backend-engineer)
- **T-4.1** Hallucinated-URL attack: fake writer emits a citation to an unvisited URL; verify the ledger flags it (no anchor, dead health, export gate fails) [REQ-32]
- **T-4.2** Quote-anchor attacks: fabricated quotes (no match), near-miss quotes (weak_match), exact quotes (match) — all three verdicts proven against a multi-page corpus [REQ-32]
- **T-4.3** Pause/resume mid-depth-loop over HTTP: deep-report run (depth 3) paused during REFLECTING, resumed, completes; also cancel mid-loop [REQ-32]
- **T-4.4** Liveness attack surface: private-IP redirect (must die), redirect chain to dead URL, oversized response cap
+1. **Review** (multi-persona, probe-verified): 4 P0 + 15 P1 + 15 P2. The 4 P0s broke the milestone's flagship guarantees and were all fixed with attack-proofs: quote anchoring extracted the stored passage's own quote (always 1.0) instead of the writer's text; the export-gate denominator counted unprobed visited pages as dead; malformed planner JSON left zombie runs; fetch adapters followed redirects without re-guarding. Six cheap P1s also fixed.
+2. **Audit**: PASS-WITH-NOTES — reconstruction, secrets sweep (clean), branch/tag hygiene exact; both critical notes (stale traceability rows, missing P5 plan) fixed in-phase.
+3. **Ship (this commit sequence)**: PR #14 (phase/05 → milestone), squash-merge, tag v0.2.5 — the MVP release candidate, release with the full milestone summary. Per D-018 and the merge_to_main escalation hook, the milestone merge to main does NOT proceed autonomously — the pipeline halts for the recorded owner decision, with G-009 (live-mode scope) presented at the same gate.

-### Wave 2 — E2E + round-trip (frontend-engineer + backend-engineer)
- **T-4.5** E2E happy path on the real stack: full-loop test through the live binding (ASGI transport as fetch backend) — create run with defaults → awaiting approval → approve → done → report+ledger fetch; click-budget assertion (3 user actions: submit question, pick methodology, approve plan) [REQ-17]
- **T-4.6** Export round-trip: markdown export contains citation URLs as links; JSON export validates back into the ledger model [REQ-34]
+## Scope Guard

-### Wave 3 — Live tier + polish (ci-lead-developer)
- **T-4.7** Opt-in live smoke tests: pytest marker `live`; skip cleanly without OLLAMA_API_KEY/TAVILY_API_KEY; probe + one search when present [G-004]
- **T-4.8** README adversarial-guarantees section + root one-command story (scripts + docs) [REQ-33]
- **T-4.9** REQ mapping table for verify: REQ-17/32/34 → tests
-
-## Out of scope for P4
- Any UI change; new API routes; methodology additions (G-010 lever untouched — Deep Report ships in this milestone)
-
-## Verification hooks
- Gates: backend ruff/mypy/pytest (adversarial suite included, zero-key); frontend typecheck/lint/test/build + live-binding E2E
- REQ coverage: REQ-17 (E2E 3-click), REQ-32 (adversarial), REQ-34 (round-trip)
- Security: attacks stay in tests; no live endpoints hit without the marker
+Milestone merge to main, v0.2.5 publication, and any deploy wait on the owner approval gate (D-018/G-009). The pipeline does not proceed autonomously past this commit.
@@ -130,8 +130,8 @@
 | REQ-63, REQ-64, REQ-65, REQ-66 (app shell, library, settings, avatar) | v0.1 | P5 | complete |
 | REQ-67, REQ-68 (ask suggestions, refine dialogue) | v0.1 | P7 | complete |
 | REQ-01..06, REQ-08..11, REQ-31 (framework, adapters) | v0.2 | P1 | complete (v0.2.1; REQ-07/12 contracts proven, live probing in P2) |
-| REQ-07, REQ-12, REQ-13..24 (probing, engine, trust) | v0.2 | P2 | blocked |
-| REQ-25, REQ-26, REQ-33 (API, client, tooling) | v0.2 | P3 | blocked |
-| REQ-17, REQ-32, REQ-34 (adversarial, E2E, round-trip) | v0.2 | P4 | blocked |
-| All REQ-01..34 (milestone gate) | v0.2 | P5 | blocked |
+| REQ-07, REQ-12, REQ-13..24 (probing, engine, trust) | v0.2 | P2 | complete (v0.2.2) |
+| REQ-25, REQ-26, REQ-33 (API, client, tooling) | v0.2 | P3 | complete (v0.2.3) |
+| REQ-17, REQ-32, REQ-34 (adversarial, E2E, round-trip) | v0.2 | P4 | complete (v0.2.4) |
+| All REQ-01..34 (milestone gate) | v0.2 | P5 | complete (v0.2.5 — **owner approval recorded 2026-09-27**, G-009 ratified; milestone merged to main) |
 | REQ-35..51 | v2 backlog (post-MVP milestones) | — | pending |
@@ -75,7 +75,7 @@ prototype release is **v0.1.8** (final phase patch). Milestone branch
 merged to main and deleted — tags v0.1.0–v0.1.8 preserve the full
 history. Next milestone: v0.2 MVP (unblocked).

-## Milestone v0.2 — MVP (feature) — UNBLOCKED (prototype approved 2026-09-27)
+## Milestone v0.2 — MVP (feature) — COMPLETE (approved 2026-09-27)

 Phases renumbered from the original v1.0 plan (1-based within the milestone). Tags run on the v0.2.x line; MAJOR stays 0.

@@ -103,14 +103,31 @@ Phases renumbered from the original v1.0 plan (1-based within the milestone). Ta
 - **Requirements covered**: REQ-25, REQ-26
 - **Status**: complete (PR #12 squash-merged 75479a9, tag v0.2.3, release HTTP 201, phase branch deleted; verify found 1 P0 mode-flag + 4 P1, all fixed in-phase; REQ-33 one-command story completed here per plan)

-### Phase 4 — Hardening + Adversarial Suite + E2E
- **Description**: Adversarial test suite (hallucinated-URL writer, quote-anchor mismatch, pause/resume mid-depth-loop), E2E happy-path (Playwright), monorepo tooling polish (one-command install/dev, lint/typecheck/test green).
+### Phase 4 — Hardening + Adversarial Suite + E2E (complete — shipped v0.2.4)
+- **Description**: Adversarial test suite (hallucinated-URL writer, quote-anchor mismatch, pause/resume mid-depth-loop), E2E happy-path (real stack via live binding + dev bridge), monorepo tooling polish (one-command install/dev, lint/typecheck/test green).
 - **Requirements covered**: REQ-17, REQ-32, REQ-33, REQ-34
- **Status**: blocked → next (sequential phases; unblock as each prior phase ships)
+- **Status**: complete (PR #13 squash-merged dcf2475, tag v0.2.4, release HTTP 201, phase branch deleted; verify found 5 P1 honesty gaps in the suite itself — export gate anchored, weak band pinned, fabricated reports fail export; E2E validated on the real stack, defaults only)

 ### Phase 5 — Final Review + Ship (FINAL)
 - **Description**: Review + audit + milestone ship; final patch tag IS the MVP release. MAJOR stays 0 — the MVP ships as a 0.x release. v1.0.0 comes only after an owner-approved release decision.
- **Status**: blocked → next (sequential phases; unblock as each prior phase ships)
+- **Status**: complete (PR #14 squash-merged 023667e, tag v0.2.5, release HTTP 201, phase branch deleted; review 4 P0 + 15 P1 — P0s attack-proven fixed; audit PASS-WITH-NOTES — criticals fixed; **owner approval RECORDED 2026-09-27** — decision commit 4721c2a, G-009 scope ratified; milestone merged to main, v0.2.5 = the MVP release)
+
+## Milestone v0.2 — COMPLETE (approved 2026-09-27)
+
+All requirements complete: REQ-01..26, REQ-31..34 (the MVP set). The
+approved MVP release is **v0.2.5** (final phase patch). Delivered: the
+FastAPI research engine (asyncio state machine, durable
+pause/cancel/resume), methodology framework (12 dials, Rapid Answer +
+Deep Report), five-adapter layer (Ollama cloud-first fallback,
+Tavily/DDG, storage, memory, secrets), the attack-proven trust loop
+(real quote anchoring, cited-scoped ≥99% liveness export gate, SSRF-
+guarded fetching, citation ledger, verification checklist), SSE live
+trace, OpenAPI-generated typed client behind the unchanged ApiClient
+boundary, a 14-attack adversarial suite, and the 3-click E2E on the
+real stack. G-009 ratified: live mode = core research loop only;
+library/settings/suggestions/refine/graph stay mock-backed until
+v0.3+. Milestone branch merged to main and deleted — tags
+v0.2.0–v0.2.5 preserve the full history. Next: v0.3 planning.

 ## Milestone Releases
 - **v0.1.4 = extended-prototype candidate** (superseded by the P5/P6 extension cycle)
@@ -118,7 +135,7 @@ Phases renumbered from the original v1.0 plan (1-based within the milestone). Ta
 - **v0.1.6 = extended-prototype candidate** (superseded by the P7/P8 extension cycle)
 - **v0.1.7 = ask suggestions + refine dialogue** (P7 patch)
 - **v0.1.8 = milestone release** (P8 final phase patch — the approved extended prototype release, pending owner decision)
- **v0.2.x = MVP release** (MAJOR still 0; ship only if all v0.2 phases complete)
+- **v0.2.5 = milestone release** (P5 final phase patch — the approved MVP; owner approval recorded 2026-09-27, G-009 ratified)
 - If MVP scope extends: additional 0.x minor milestones (v0.3, …), each a full milestone cycle
 - **v1.0.0**: owner-approved release only — not created by the pipeline autonomously

@@ -2,18 +2,23 @@
  "ci_version": "0.7.0",
  "projects": [],
  "active_project": "researchx",
-  "milestone": "v0.2",
-  "milestone_name": "mvp",
+  "milestone": "v0.3",
+  "milestone_name": "next-milestone-planning",
  "milestone_type": "feature",
  "versioning": {
    "major_locked": true,
-    "major_lock_note": "MAJOR remains 0 until an owner-approved v1 release; the MVP may span multiple 0.x minor milestones; all pre-v1 ships are MINOR/PATCH only",
-    "tag_line": "v0.2.x",
-    "next_milestone": "v0.3+ (post-MVP backlog milestones)"
+    "major_lock_note": "MAJOR remains 0 until an owner-approved v1 release; all pre-v1 ships are MINOR/PATCH only",
+    "tag_line": "v0.3.x",
+    "next_milestone": "v0.3 scope definition pending owner direction (post-MVP backlog: live-bound library/settings/suggestions/refine, backend hosting, remaining 6 methodologies)"
  },
  "autonomy": {
    "level": "full",
-    "escalation_hooks": ["deploy", "delete_data", "merge_to_main", "prototype_approval"],
+    "escalation_hooks": [
+      "deploy",
+      "delete_data",
+      "merge_to_main",
+      "prototype_approval"
+    ],
    "decision_confidence_threshold": 0.6,
    "max_revision_iterations": 3,
    "clarify_budget": 10
@@ -37,9 +42,16 @@
  "secrets": {
    "env_file": ".ciagent/.env.secrets",
    "scopes": {
-      "release": ["GITEA_TOKEN"],
-      "model": ["OLLAMA_API_KEY", "OLLAMA_BASE_URL"],
-      "search": ["TAVILY_API_KEY"]
+      "release": [
+        "GITEA_TOKEN"
+      ],
+      "model": [
+        "OLLAMA_API_KEY",
+        "OLLAMA_BASE_URL"
+      ],
+      "search": [
+        "TAVILY_API_KEY"
+      ]
    }
  }
-}
+}
@@ -1,8 +1,8 @@
-# Deploy Record — UAT stagings of the v0.1 prototype
+# Deploy Record — UAT stagings and releases

-Owner-directed UAT deployments, recorded per commit discipline. The
-approval gate (REQ-62) stays closed; UAT variants stage review builds
-without minting release tags.
+Owner-directed deployments, recorded per commit discipline. Release
+deploys carry the owner approval (v0.1.8); UAT variants stage review
+builds without minting release tags.

 | Date | Version | Commit | Directive | Result |
 |---|---|---|---|---|
@@ -11,6 +11,8 @@ without minting release tags.
 | 2026-09-27 | v0.1.7-uat | 432d2c0 (P7 ship + boundary docs) | owner cadence: deploy after P7 and P8 | healthy — http://10.0.0.114:3000 |
 | 2026-09-27 | v0.1.8-uat | 93a7b57 (P8 ship — release candidate) | owner cadence: deploy after P7 and P8 | healthy — http://10.0.0.114:3000 |
 | 2026-09-27 | **v0.1.8 (release)** | 93a7b57 (tagged) | **owner approval recorded — milestone release published** | healthy — http://10.0.0.114:3000 |
+| 2026-09-27 | v0.2.5-uat | c28a97e (v0.2 milestone HEAD + v0.2.5 version strings) | owner: "deploy and validate against https://research.coreci.dev" | healthy — https://research.coreci.dev (HAProxy/SSL) |
+| 2026-09-27 | **v0.2.5 (release)** | b11b202 (main merge; tag v0.2.5) | **owner approval recorded (/ci-run APPROVED) — milestone release published; G-009 ratified** | serving — same container (v0.2.5-uat build = release content); no redeploy needed |

 ## v0.1.6-uat (extended prototype for owner review)

@@ -24,4 +26,25 @@ without minting release tags.
 - Rollback: `ssh root@10.0.0.114 'docker stop researchx; docker rename
  researchx-prev researchx; docker start researchx'`
 - The approval gate remains closed: milestone merge to main still halts
-  for the recorded owner decision (REQ-62)
+  for the recorded owner decision (REQ-62)
+
+## v0.2.5-uat (MVP release candidate, owner-directed)
+
+- Deployed via `bash .ciagent/release/deploy.sh v0.2.5-uat` — the v0.2
+  milestone HEAD (c28a97e: tag v0.2.5 + v0.2.5 About/package.json
+  version strings), per the owner's direct request to deploy and
+  validate against the public URL
+- Gates re-run at deploy time from the milestone HEAD: typecheck,
+  lint, test (97/97), build — green before sync
+- Image `researchx:v0.2.5-uat` + `latest` on the host; container
+  swapped, `researchx-prev` (v0.1.8) kept for rollback
+- Health: 2 checks; validated through the HAProxy SSL front:
+  https://research.coreci.dev — /ask /library /settings /choose all
+  200, root 307→/ask, TLS verified; served settings chunk carries
+  "v0.2.5 · MVP release candidate"; the RESEARCHX_API_MODE switch is
+  present in the served bundle (mock default — correct for a
+  frontend-only container; live mode additionally needs the backend
+  API on the host, which is v0.3+ deployment work)
+- The merge gate (D-018) remains closed: milestone → main still halts
+  for the recorded owner decision, with G-009 (live-mode scope)
+  presented at the same gate
@@ -0,0 +1,87 @@
+# UAT Script — v0.2.5 (MVP release candidate)
+
+Deployment: https://research.coreci.dev (HAProxy → LXC container
+`researchx:v0.2.5-uat`, commit c28a97e, mock-backed frontend).
+
+Scope note (G-009): this container serves the v0.2.5 frontend with
+scripted mock data. The v0.2 engine (FastAPI, adapters, trust loop)
+is validated by the automated suites (129 backend + 97 frontend
+tests, 14 adversarial attacks, real-stack E2E) and runs via the
+README live-mode locally; hosting the backend is v0.3+ work. This
+UAT validates the release-candidate build of the product surface.
+
+## 1. Shell & navigation (REQ-63, REQ-66)
+
+1. Open https://research.coreci.dev → lands on **/ask** inside the app shell
+2. Sidebar: **New research / Library / Settings** nav present on every screen
+3. Top bar: press **⌘K** → navigation palette (screens + stored reports)
+4. Click the **avatar** (top right) → user menu: local profile, Settings, About
+5. Pass: shell persistent everywhere, honest preview-marked future slots
+
+## 2. Version check (this deploy)
+
+1. Sidebar → **Settings** → scroll to *About & version*
+2. Pass: reads **"v0.2.5 · MVP release candidate"** (confirms the deployed build)
+
+## 3. The ≤3-click happy path (REQ-61 / REQ-17 — core criterion)
+
+1. **/ask**: type a question → click **Research this** (click 1)
+2. **/choose**: pick a card (Deep Report is the recommended default) → **Start research** (click 2)
+3. **Plan & Run**: review the plan → **Approve plan** (click 3)
+4. Pass: exactly 3 clicks, defaults only, research running with a live trace
+
+## 4. Plan & Run (REQ-57)
+
+1. Plan approval UI shows sub-questions, source universe, outline
+2. Watch the live trace stream (scripted replay)
+3. Press **pause** → trace halts; **resume** → continues; **cancel** → terminal state
+4. Pass: all three controls behave; no lost events
+
+## 5. Reading Room + exports (REQ-58, REQ-59, REQ-34)
+
+1. Open the finished report from the run screen
+2. Hover/focus any **[n]** citation marker → the exact quoted passage appears
+3. Open the **citation ledger** panel: URL, quote, health, authority tier
+4. **Export Markdown** and **Export JSON** → real files download; citations survive as links
+5. Pass: quotes match exactly; files open; links intact
+
+## 6. Ask intelligence (REQ-67, REQ-68)
+
+1. **New research** → below the form: open-question suggestions appear
+2. Click one → the question box fills; **never auto-starts**
+3. Type a draft → **Refine question** → answer the 3 clarifying questions → **Use this** → refined question + context fill the form
+4. Try **Keep original** on a second draft → untouched; keyboard (Enter) works through both flows
+5. Pass: both helpers are opt-in, keyboard-accessible, drafts preserved on dismiss
+
+## 7. Library (REQ-64)
+
+1. Sidebar → **Library**: folder tree, auto-categorized (topic + methodology), sortable (recency/title)
+2. Open a stored report → its own Reading Room view
+3. **Connections** panel: shared-source ⇄ and topical → edges
+4. v2 previews: project graph + task inbox panels render
+5. Pass: folders, sorting, connections, previews all render from the fixture data
+
+## 8. Settings (REQ-65)
+
+1. API keys: masked (never raw); storage directory field
+2. Methodology defaults: resolved 12-dial display
+3. Appearance preview; About & version (step 2)
+4. Pass: everything honest and functional on mock data
+
+## Optional: hands-on the live engine (not on this URL)
+
+```bash
+# locally, two terminals:
+cd backend && uv sync && uv run uvicorn researchx.api.app:app --port 8000
+cd frontend && NEXT_PUBLIC_RESEARCHX_API_MODE=live corepack pnpm dev
+# then repeat steps 3-5 against the real engine (fake adapters, zero keys)
+```
+
+## Decision rubric (the gate this UAT feeds)
+
+- **Approve**: recorded via /ci-run → milestone merges to main,
+  v0.2.5 publishes as the MVP release, v0.3 planning unblocks
+  (with G-009 scope ratified: library/settings/suggestions/refine/
+  graph stay mock-backed until v0.3+)
+- **Request changes**: feedback becomes binding decisions for a
+  fix cycle (v0.1 precedent: two feedback cycles before approval)
@@ -9,7 +9,7 @@ as established by the CIAgent branch strategy and `config.json`.
 | Milestone | Tags | Deployed by |
 |---|---|---|
 | v0.1 prototype | v0.1.0 … v0.1.8 | `bash .ciagent/release/deploy.sh v0.1.8` |
-| v0.2 MVP | v0.2.0 … | `bash .ciagent/release/deploy.sh v0.2.x` |
+| v0.2 MVP | v0.2.0 … v0.2.5 | `bash .ciagent/release/deploy.sh v0.2.5-uat` (staged) — see DEPLOY-RECORD.md |

 ## Rules

@@ -0,0 +1,157 @@
+# .gitea/workflows/ci.yml - ResearchX phase-4 CI gate (researchx#24).
+#
+# This file IS the gate. The pre-code clause (coreci/company#105, c14057):
+# a code phase opens only when the product repo's gating workflow file has
+# dispatched at least one run on `main` and every job in that file is green
+# in that run. Until this file exists, coreci/researchx has no workflow and
+# no run at all - that is the case the clause was amended for (researchx#24,
+# c14093). A half-green pipeline does not open the phase either.
+#
+# Two jobs:
+#   backend  - uv + Python 3.12: ruff, mypy, pytest
+#   frontend - Node 22 + pnpm 12.6.0: typecheck, lint, test, build
+#
+# Runner label: `ubuntu-latest` - the org CI fleet's published label whose
+# image is docker.gitea.com/runner-images:ubuntu-latest (label map read at
+# source: coreci/nextcraft deploy/ci/docker-compose.yaml + deploy/ci/README.md,
+# R-3). The previous string `employee-runner` was a fleet NAME, not a label:
+# the employee fleet's labels are `employee-py` and `employee-coder` (read
+# from a live job log of this seat's own home), and the CI fleet's are node /
+# ubuntu-latest / python / release - no runner carried the old label, so a
+# merged file asking for it could still buy no run.
+#
+# Toolchain: measured, not assumed. From the runner's own logs (job 56393,
+# coreci/nova-platform, 2026-10-26T23:17Z, and job 57005, coreci/inboxos-v1,
+# 2026-10-27T03:01Z): the image carries python 3.12.3, pip, git, node (the
+# actions run in it), pypi REACHABLE and github REACHABLE; actions/checkout@v4,
+# actions/setup-python@v5 and actions/setup-go@v5 all run inside it. It does
+# NOT carry uv or pnpm, so this file installs them: uv from pypi (pip), pnpm
+# 12.6.0 through corepack - the repo's own documented way (README command map).
+# The gates are the repo's documented commands: backend `uv run ruff check src
+# tests`, `uv run mypy src`, `uv run pytest`; frontend `pnpm typecheck`,
+# `pnpm lint`, `pnpm test`, `pnpm build`. The frontend lane mirrors the
+# release image's own recipe (frontend/Dockerfile: node:22-alpine, corepack,
+# pnpm install --frozen-lockfile, pnpm build), so the gate tests what the
+# product ships.
+#
+# Owner of a red leg (the clause asks for the owner of the fix next to the
+# owner of the product line): toolchain / image / dispatch problems ->
+# coreci-sre (employee-runner-fleet + gitea-instance); product-line problems
+# -> coreci-researchx-po. Approval for this file rides the merge request
+# (merge = approval, constitution v1.3).
+
+name: ci
+
+on:
+  push:
+  pull_request:
+    branches: ["main"]
+  workflow_dispatch:
+
+jobs:
+  backend:
+    name: "backend (uv, Python 3.12: ruff/mypy/pytest)"
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # uv is not in the CI image; pypi is reachable from it (measured). The
+      # install is a toolchain leg, not a product gate: the gates still run
+      # from the repo's own committed lockfile (backend/uv.lock).
+      - name: Install uv (from pypi)
+        run: |
+          set -eu
+          python -m pip install --upgrade uv
+          uv --version
+
+      - name: Install dependencies (uv, from the committed lockfile)
+        working-directory: backend
+        run: uv sync --frozen
+
+      - name: Lint (ruff)
+        working-directory: backend
+        run: uv run ruff check src tests
+
+      - name: Typecheck (mypy)
+        working-directory: backend
+        run: uv run mypy src
+
+      - name: Test (pytest)
+        working-directory: backend
+        run: uv run pytest
+
+  frontend:
+    name: "frontend (Next.js on pnpm: typecheck/lint/test/build)"
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # Node 22 to mirror the release image (frontend/Dockerfile: node:22).
+      - name: Setup Node 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Setup Python 3.12 (for the real-stack e2e bridge)
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv (from pypi)
+        run: |
+          set -eu
+          python -m pip install --upgrade uv
+
+      # pnpm 12.6.0 is pinned by frontend/package.json `packageManager`;
+      # corepack reads it from there. If the image carries no corepack, npm
+      # installs the same pinned version.
+      - name: pnpm 12.6.0 (corepack, pinned by frontend/package.json)
+        working-directory: frontend
+        run: |
+          set -eu
+          node --version
+          corepack enable pnpm 2>/dev/null || true
+          if ! pnpm --version >/dev/null 2>&1; then
+            npm i -g pnpm@12.6.0
+          fi
+          test "$(pnpm --version)" = "12.6.0"
+
+      - name: Install dependencies (from the committed lockfile)
+        working-directory: frontend
+        run: pnpm install --frozen-lockfile
+
+      # frontend/src/lib/api/e2e-real-stack.test.ts drives the real FastAPI
+      # stack: it spawns `uv run python -m researchx.api.dev_bridge` from
+      # ../backend (loopback :8000, fakes only, zero API keys). Without a
+      # synced backend venv that test cannot come up, so the lane provisions
+      # it. Provisioning only - the backend gates stay in the backend job.
+      - name: Backend venv for the real-stack e2e bridge
+        working-directory: backend
+        run: uv sync --frozen
+
+      - name: Typecheck
+        working-directory: frontend
+        run: pnpm typecheck
+
+      - name: Lint
+        working-directory: frontend
+        run: pnpm lint
+
+      - name: Test
+        working-directory: frontend
+        run: pnpm test
+
+      - name: Build
+        working-directory: frontend
+        env:
+          NEXT_TELEMETRY_DISABLED: "1"
+        run: pnpm build
@@ -1,8 +1,15 @@
 # ResearchX

+**TL;DR** — ResearchX turns one question into a cited research report: pick a method, approve the plan, and the engine visits real web sources, with every claim anchored to a quoted passage from a page it actually read. The engine milestone (v0.2.5) is shipped and owner-approved; hosting goes live next (v0.3, in progress).
+
+- **What** — FastAPI backend (planning, search, extraction, verification, export gates) plus a Next.js frontend; the full test suite runs with zero API keys.
+- **Why** — Readers can check every citation back to its source passage; runs are resumable from durable state.
+- **Action** — no action — FYI. Developers: see the Quickstart below.
+- **Details** — `frontend/README.md` (web app); `.ciagent/` (pipeline state and roadmap).
+
 A deep-research studio where you bring your own model, storage, and memory; choose a research methodology before a single query fires; and every claim in the final report is anchored to a visited, verified, quotable source.

-**Status: MVP in development (milestone v0.2)** — the approved v0.1 prototype frontend (mock-backed) plus the FastAPI backend, research engine, adapter layer, and trust loop. The frontend runs standalone on mock data; live backend mode arrives with v0.2 phase 3.
+**Status: MVP shipped (v0.2.5, owner-approved 2026-09-27)** — the full research engine (FastAPI + asyncio state machine + adapter layer + attack-proven trust loop) behind the v0.1 frontend. Live mode covers the core research loop (G-002/G-009): the engine runs locally per the quickstart; library/settings/suggestions/refine stay mock-backed until v0.3+.

 ## Quickstart

@@ -84,11 +91,13 @@ The test suite needs **no** keys: fake model/search adapters (REQ-31) drive ever
 The frontend runs mock-backed by default (works standalone, zero keys). To run the core research loop against the real backend:

 ```bash
-# terminal 1 — backend (fake adapters by default; live adapters via env-file keys)
+# terminal 1 — backend (fake adapters by default; real Ollama/Tavily adapters
+# are used by the engine in v0.2.5+ wiring — the served API currently ships
+# fake-adapter runs for demos and tests; see Adapter configuration below)
 cd backend && uv run uvicorn researchx.api.app:app --reload --port 8000

 # terminal 2 — frontend in live mode
-cd frontend && RESEARCHX_API_MODE=live corepack pnpm dev
+cd frontend && NEXT_PUBLIC_RESEARCHX_API_MODE=live corepack pnpm dev
 ```

 Live mode covers the core loop (Ask → Choose → approve plan → live trace → report + ledger); the library, settings persistence, suggestions, refine, and graph surfaces stay mock-backed until v0.3. The API surface: `POST /api/runs`, `GET /api/methodologies`, run lifecycle (`approve/pause/cancel/resume`), `GET /api/runs/{id}/events` (SSE), `GET /api/config`, report + ledger artifacts.
@@ -3,7 +3,6 @@ import json
 import httpx

 from researchx.adapters.model import ModelAdapter
-from researchx.adapters.ollama import OllamaModelAdapter
 from researchx.adapters.probe import (
    DEFAULT_EMBEDDING_BATCH,
    CapabilityProbe,
@@ -13,19 +12,25 @@ from researchx.adapters.probe import (
 from researchx.adapters.types import ModelMessage


-async def probe_model_adapter(adapter: OllamaModelAdapter) -> CapabilityProbe:
+def supports_probe(adapter: ModelAdapter) -> bool:
+    return getattr(adapter, "probing_supported", False)
+
+
+async def probe_model_adapter(adapter: ModelAdapter) -> CapabilityProbe:
    models = await adapter.list_models()
    smoke_ok = await _structured_output_smoke_test(adapter)
    writer = adapter.roles().writer
    warning = structured_output_warning(smoke_ok, writer)
+    endpoint = getattr(adapter, "active_base_url", "unknown")
+    fallback_reason = getattr(adapter, "last_fallback_reason", None)
    return CapabilityProbe(
-        endpoint=adapter.active_base_url,
+        endpoint=str(endpoint),
        models=models,
        context_window=cap_context_window(None),
        embedding_batch=DEFAULT_EMBEDDING_BATCH,
        structured_outputs_supported=smoke_ok,
        structured_output_warning=warning,
-        fallback_reason=adapter.last_fallback_reason,
+        fallback_reason=fallback_reason,
    )


@@ -13,6 +13,7 @@ from researchx.adapters.url_guard import url_allowed
 _DDG_URL = "https://html.duckduckgo.com/html"
 _SEARCH_TIMEOUT = 10.0
 _FETCH_TIMEOUT = 10.0
+_MAX_FETCH_REDIRECTS = 5
 _BACKOFF_SECONDS = 1.0
 _USER_AGENT = "researchx/0.2 (local research studio)"
 _RESULT_RE = re.compile(
@@ -93,21 +94,34 @@ class DuckDuckGoSearchAdapter:
        return re.sub(r"\s+", " ", text).strip()

    async def fetch(self, url: str) -> PageContent:
-        if not url_allowed(url):
-            raise AdapterError("fetch refused: url not allowed (private or non-http scheme)")
+        from urllib.parse import urljoin
+
+        current = url
        async with httpx.AsyncClient(
            timeout=_FETCH_TIMEOUT,
-            follow_redirects=True,
+            follow_redirects=False,
            headers={"User-Agent": _USER_AGENT},
        ) as client:
-            response = await client.get(url)
-            response.raise_for_status()
-        return PageContent(
-            url=url,
-            title=extract_title(response.text),
-            text=extract_text(response.text),
-            fetched_at=datetime.now(UTC),
-        )
+            for _ in range(_MAX_FETCH_REDIRECTS + 1):
+                if not url_allowed(current):
+                    raise AdapterError(
+                        "fetch refused: url not allowed (private or non-http scheme)"
+                    )
+                response = await client.get(current)
+                if 300 <= response.status_code < 400:
+                    location = response.headers.get("location")
+                    if not location:
+                        raise AdapterError("fetch failed: redirect without location")
+                    current = urljoin(current, location)
+                    continue
+                response.raise_for_status()
+                return PageContent(
+                    url=url,
+                    title=extract_title(response.text),
+                    text=extract_text(response.text),
+                    fetched_at=datetime.now(UTC),
+                )
+        raise AdapterError("fetch failed: too many redirects")

    @property
    def last_degradation(self) -> str | None:
@@ -12,6 +12,8 @@ _REQUEST_TIMEOUT = 60.0


 class OllamaModelAdapter:
+    probing_supported = True
+
    def __init__(
        self,
        secrets: EnvFileSecretsProvider,
@@ -10,6 +10,7 @@ from researchx.adapters.url_guard import url_allowed
 _TAVILY_URL = "https://api.tavily.com/search"
 _SEARCH_TIMEOUT = 10.0
 _FETCH_TIMEOUT = 10.0
+_MAX_FETCH_REDIRECTS = 5
 _USER_AGENT = "researchx/0.2 (local research studio)"
 _TITLE_RE = re.compile(r"<title[^>]*>(.*?)</title>", re.IGNORECASE | re.DOTALL)
 _BLOCK_RE = re.compile(r"<(script|style)[^>]*>.*?</\1>", re.IGNORECASE | re.DOTALL)
@@ -56,18 +57,31 @@ class TavilySearchAdapter:
        ][:max_results]

    async def fetch(self, url: str) -> PageContent:
-        if not url_allowed(url):
-            raise AdapterError("fetch refused: url not allowed (private or non-http scheme)")
+        from urllib.parse import urljoin
+
+        current = url
        async with httpx.AsyncClient(
            timeout=_FETCH_TIMEOUT,
-            follow_redirects=True,
+            follow_redirects=False,
            headers={"User-Agent": _USER_AGENT},
        ) as client:
-            response = await client.get(url)
-            response.raise_for_status()
-        return PageContent(
-            url=url,
-            title=extract_title(response.text),
-            text=extract_text(response.text),
-            fetched_at=datetime.now(UTC),
-        )
+            for _ in range(_MAX_FETCH_REDIRECTS + 1):
+                if not url_allowed(current):
+                    raise AdapterError(
+                        "fetch refused: url not allowed (private or non-http scheme)"
+                    )
+                response = await client.get(current)
+                if 300 <= response.status_code < 400:
+                    location = response.headers.get("location")
+                    if not location:
+                        raise AdapterError("fetch failed: redirect without location")
+                    current = urljoin(current, location)
+                    continue
+                response.raise_for_status()
+                return PageContent(
+                    url=url,
+                    title=extract_title(response.text),
+                    text=extract_text(response.text),
+                    fetched_at=datetime.now(UTC),
+                )
+        raise AdapterError("fetch failed: too many redirects")
@@ -8,12 +8,13 @@ from fastapi.middleware.cors import CORSMiddleware
 from pydantic import BaseModel, Field, ValidationError
 from sse_starlette.sse import EventSourceResponse

+from researchx.adapters.capability_probe import probe_model_adapter, supports_probe
 from researchx.adapters.fakes import CORPUS, FakeModelAdapter, FakeSearchAdapter
 from researchx.adapters.local_storage import LocalStorageAdapter
 from researchx.adapters.types import AdapterError, ChatResult
 from researchx.engine.actor import RunActor, make_run_config
 from researchx.engine.events import EventBus, RunEvent
-from researchx.engine.run_state import RunState
+from researchx.engine.run_state import Plan, RunState
 from researchx.engine.states import RunStateName
 from researchx.methodologies import registry

@@ -28,8 +29,8 @@ _CANNED_WRITER = (


 class CreateRunBody(BaseModel):
-    question: str = Field(min_length=1)
-    context: str = ""
+    question: str = Field(min_length=1, max_length=2000)
+    context: str = Field(default="", max_length=8000)
    methodology: str
    dial_overrides: dict[str, Any] = Field(default_factory=dict)

@@ -76,7 +77,7 @@ _STATUS_MAP = {
    RunStateName.VERIFYING: "verifying",
    RunStateName.DONE: "done",
    RunStateName.CANCELLED: "cancelled",
-    RunStateName.FAILED: "cancelled",
+    RunStateName.FAILED: "failed",
 }

 _ETA_TABLE = {"rapid-answer": (2, "low"), "deep-report": (12, "medium")}
@@ -170,11 +171,15 @@ def create_app(

    @app.get("/api/config")
    async def config_status() -> ConfigStatus:
+        latest_probe = None
+        for run_id in list(runs._actors)[-1:]:
+            actor_probe = runs.actor(run_id).state.probe
+            latest_probe = actor_probe
        return ConfigStatus(
            model_adapter=type(model).__name__,
            search_adapter=type(search).__name__,
            storage_dir=str(storage.run_dir("00000000").parent),
-            probe=None,
+            probe=latest_probe,
            cost_counters=runs.cost_counters,
        )

@@ -221,14 +226,22 @@ def create_app(
            storage=storage,
            registry=registry,
            event_bus=bus,
+            on_complete=runs.note_completed,
        )
+        probe_data: dict[str, Any] | None = None
+        if supports_probe(model):
+            try:
+                probe = await probe_model_adapter(model)
+                probe_data = probe.model_dump(mode="json")
+                await actor.attach_probe(probe_data)
+            except AdapterError:
+                probe_data = None
+
        task = asyncio.create_task(actor.run())
        runs.add(run_id, actor, task, bus)

        async def _watch() -> None:
-            state = await task
-            if state.state == RunStateName.DONE:
-                runs.note_completed()
+            await task

        asyncio.create_task(_watch())
        return _summary(run_id)
@@ -244,7 +257,13 @@ def create_app(
        if not runs.has(run_id):
            raise HTTPException(status_code=404, detail="run not found")
        actor = runs.actor(run_id)
-        await actor.approve()
+        edited_plan: Plan | None = None
+        if body and body.plan:
+            try:
+                edited_plan = Plan.model_validate(body.plan)
+            except ValidationError:
+                raise HTTPException(status_code=422, detail="invalid plan")
+        await actor.approve(edited_plan)
        return _summary(run_id)

    @app.post("/api/runs/{run_id}/pause")
@@ -1,4 +1,5 @@
 import asyncio
+from collections.abc import Callable
 from datetime import UTC, datetime
 from typing import Any

@@ -34,6 +35,7 @@ class RunActor:
        storage: LocalStorageAdapter,
        registry: MethodologyRegistry,
        event_bus: EventBus,
+        on_complete: Callable[[], None] | None = None,
    ) -> None:
        self._config = run_config
        self._model = model
@@ -41,6 +43,7 @@ class RunActor:
        self._storage = storage
        self._registry = registry
        self._bus = event_bus
+        self._on_complete = on_complete
        self._store = EvidenceStore()
        self.state = RunState(
            run_id=run_config.run_id,
@@ -83,6 +86,8 @@ class RunActor:
    async def _checkpoint(self, target: RunStateName) -> None:
        if self.state.state != target:
            self.state.transition(target)
+            if target is RunStateName.DONE and self._on_complete is not None:
+                self._on_complete()
        await self._persist()

    async def _wait_if_paused(self) -> None:
@@ -112,6 +117,15 @@ class RunActor:
        except AdapterError as exc:
            await self._fail(str(exc))
            raise EngineError(str(exc)) from exc
+        except httpx.HTTPError as exc:
+            await self._fail(f"network error ({type(exc).__name__})")
+            raise EngineError(f"network error ({type(exc).__name__})") from exc
+        except EngineError:
+            await self._fail("engine error")
+            raise
+        except Exception as exc:
+            await self._fail(f"unexpected engine failure ({type(exc).__name__})")
+            raise EngineError(f"unexpected engine failure ({type(exc).__name__})") from exc
        return self.state

    async def attach_probe(self, probe_data: dict[str, Any]) -> None:
@@ -177,10 +191,21 @@ class RunActor:
            data = json.loads(raw)
        except json.JSONDecodeError as exc:
            raise AdapterError("planner returned non-JSON plan") from exc
+        if not isinstance(data, dict):
+            raise AdapterError("planner plan is not a JSON object")
+        sub_questions = data.get("sub_questions", [])
+        source_universe = data.get("source_universe", [])
+        outline = data.get("outline", [])
+        if not (
+            isinstance(sub_questions, list)
+            and isinstance(source_universe, list)
+            and isinstance(outline, list)
+        ):
+            raise AdapterError("planner plan has malformed lists")
        return Plan(
-            sub_questions=[str(q) for q in data.get("sub_questions", [])],
-            source_universe=[str(u) for u in data.get("source_universe", [])],
-            outline=[str(o) for o in data.get("outline", [])],
+            sub_questions=[str(q) for q in sub_questions if isinstance(q, str)],
+            source_universe=[str(u) for u in source_universe if isinstance(u, str)],
+            outline=[str(o) for o in outline if isinstance(o, str)],
        )

    async def _approval_phase(self) -> None:
@@ -49,17 +49,41 @@ def anchor_quote(quote: str, passages: list[Passage]) -> AnchorVerdict:
    )


-def extract_quotes_from_report(report_text: str, evidence: EvidenceStore) -> list[str]:
-    marker_re = re.compile(r"\[p-(\d+)\]")
-    quotes: list[str] = []
-    for match in marker_re.finditer(report_text):
+_MARKER_RE = re.compile(r"\[p-(\d+)\]")
+_HEADER_RE = re.compile(r"^#{1,6}\s.*$", re.MULTILINE)
+
+
+def _claim_fragment(before: str) -> str:
+    cleaned = _HEADER_RE.sub("", before).rstrip()
+    fragment_start = max(
+        cleaned.rfind("."), cleaned.rfind("!"), cleaned.rfind("?"), cleaned.rfind("\n")
+    )
+    quote_text = cleaned[fragment_start + 1 :].strip(" \t>\"'*-")
+    if not quote_text:
+        quote_text = cleaned[-200:].strip(" \t>\"'*-")
+    return quote_text
+
+
+def extract_report_claims(report_text: str) -> list[tuple[str, str]]:
+    """Extract (passage_id, quote_text) claims from the report.
+
+    The quote text is what the WRITER actually wrote adjacent to the
+    citation marker — the last sentence fragment before each [p-N]
+    marker — NOT the stored passage's own text. This is the adversarial
+    core of REQ-20: a fabricated quote riding a real passage ID must
+    be visible to the anchorer.
+    """
+    claims: list[tuple[str, str]] = []
+    for match in _MARKER_RE.finditer(report_text):
        passage_id = f"p-{match.group(1)}"
-        passage = evidence.get(passage_id)
-        if passage:
-            quotes.append(passage.quote)
-    return quotes
+        quote_text = _claim_fragment(report_text[: match.start()])
+        claims.append((passage_id, quote_text))
+    return claims
+
+
+def extract_quotes_from_report(report_text: str, evidence: EvidenceStore) -> list[str]:
+    return [quote for _pid, quote in extract_report_claims(report_text) if evidence.get(_pid)]


 def extract_cited_passage_ids(report_text: str) -> list[str]:
-    marker_re = re.compile(r"\[p-(\d+)\]")
-    return [f"p-{m.group(1)}" for m in marker_re.finditer(report_text)]
+    return [f"p-{m.group(1)}" for m in _MARKER_RE.finditer(report_text)]
@@ -7,7 +7,7 @@ from researchx.evidence.store import EvidenceStore, Passage
 from researchx.trust.anchoring import (
    anchor_quote,
    extract_cited_passage_ids,
-    extract_quotes_from_report,
+    extract_report_claims,
    normalize,
 )
 from researchx.trust.liveness import LivenessStatus
@@ -80,17 +80,22 @@ def build_ledger(
 ) -> CitationLedger:
    claims = _claims_per_passage(report_text)
    all_passages = evidence.writer_context()
-    report_quotes = extract_quotes_from_report(report_text, evidence)
+    report_claims = extract_report_claims(report_text)
    cited_ids = extract_cited_passage_ids(report_text)
    known_ids = {p.passage_id for p in all_passages}
+    cited_urls: list[str] = []
    entries: list[CitationEntry] = []
    anchored = 0
    unanchored = 0
    weak = 0
    confidence: dict[str, str] = {}

-    for quote in report_quotes:
-        verdict = anchor_quote(quote, all_passages)
+    for passage_id, writer_quote in report_claims:
+        passage = evidence.get(passage_id)
+        if passage is None:
+            unanchored += 1
+            continue
+        verdict = anchor_quote(writer_quote, [passage])
        if verdict.matched:
            anchored += 1
        elif verdict.weak:
@@ -101,8 +106,13 @@ def build_ledger(
    for cited_id in cited_ids:
        if cited_id not in known_ids:
            unanchored += 1
+        passage = evidence.get(cited_id)
+        if passage is not None and passage.url not in cited_urls:
+            cited_urls.append(passage.url)

    for page in evidence.pages():
+        if page.url not in cited_urls:
+            continue
        passages = evidence.passages_for_url(page.url)
        passage_ids = [p.passage_id for p in passages]
        page_claims = sum(claims.get(pid, 0) for pid in passage_ids)
@@ -12,7 +12,7 @@ from pathlib import Path
 import httpx

 from researchx.adapters.fakes import CORPUS, FakeModelAdapter, FakeSearchAdapter
-from researchx.adapters.types import ChatResult
+from researchx.adapters.types import AdapterError, ChatResult
 from researchx.api.app import create_app
 from researchx.evidence.store import EvidenceStore
 from researchx.trust.anchoring import anchor_quote
@@ -261,8 +261,9 @@ def test_export_round_trip_json_validates_into_backend_model() -> None:
    from researchx.trust.ledger import CitationLedger

    store = EvidenceStore()
-    store.add_passage("https://example.org/a", "A passage with real content " * 6)
-    report = "# Report\n\nClaim [p-1].\n"
+    stored_text = "A passage with real content for the round-trip proof."
+    store.add_passage("https://example.org/a", stored_text)
+    report = f"# Report\n\n{stored_text} [p-1].\n"
    ledger = build_ledger(
        run_id="attack003",
        report_text=report,
@@ -276,3 +277,83 @@ def test_export_round_trip_json_validates_into_backend_model() -> None:
    checklist_md = export_checklist(ledger)
    assert "Anchoring gate" in checklist_md
    assert "PASS" in checklist_md
+
+
+def test_attack_fabricated_quote_on_real_passage_id_fails() -> None:
+    store = EvidenceStore()
+    stored = store.add_passage(
+        "https://example.org/real",
+        "The genuine finding about verification pipelines is that anchoring works. " * 3,
+    )
+    report = (
+        "# Report\n\n"
+        f"THIS FABRICATED QUOTE WAS NEVER STORED ANYWHERE AT ALL [{stored.passage_id}]\n"
+    )
+    ledger = build_ledger(
+        run_id="attack004",
+        report_text=report,
+        evidence=store,
+        liveness={"https://example.org/real": LivenessStatus.LIVE},
+        visited_at=datetime.now(UTC),
+    )
+    assert ledger.checklist.unanchored_claims >= 1, (
+        "a fabricated quote riding a real passage ID must be flagged (REQ-20)"
+    )
+    passed, _ = liveness_export_gate(ledger)
+    assert passed is False
+
+
+def test_attack_real_verbatim_quote_on_real_passage_anchors() -> None:
+    store = EvidenceStore()
+    stored_text = (
+        "The genuine finding about verification pipelines is that anchoring works."
+    )
+    stored = store.add_passage("https://example.org/real", stored_text + " " + stored_text)
+    report = f"# Report\n\n{stored_text} [{stored.passage_id}]\n"
+    ledger = build_ledger(
+        run_id="attack005",
+        report_text=report,
+        evidence=store,
+        liveness={"https://example.org/real": LivenessStatus.LIVE},
+        visited_at=datetime.now(UTC),
+    )
+    assert ledger.checklist.anchored_claims == 1
+    assert ledger.checklist.unanchored_claims == 0
+    passed, _ = liveness_export_gate(ledger)
+    assert passed is True
+
+
+async def test_attack_search_result_redirecting_to_private_ip_refused(monkeypatch) -> None:
+    import tempfile
+    from pathlib import Path as PathMod
+
+    import httpx as httpx_mod
+
+    from researchx.adapters.secrets import EnvFileSecretsProvider
+    from researchx.adapters.tavily import TavilySearchAdapter
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        env_file = PathMod(tmpdir) / ".env.secrets"
+        env_file.write_text("TAVILY_API_KEY=t-key\n", encoding="utf-8")
+        secrets = EnvFileSecretsProvider(paths=[env_file])
+        adapter = TavilySearchAdapter(secrets)
+
+        def handler(request: httpx_mod.Request) -> httpx_mod.Response:
+            if "boobytrap" in str(request.url):
+                return httpx_mod.Response(
+                    302, headers={"location": "http://169.254.169.254/latest/meta-data"}
+                )
+            return httpx_mod.Response(200, text="<html><body>ok</body></html>")
+
+        transport = httpx_mod.MockTransport(handler)
+        original = httpx_mod.AsyncClient
+        monkeypatch.setattr(
+            httpx_mod, "AsyncClient", lambda **kw: original(transport=transport, **kw)
+        )
+
+        try:
+            await adapter.fetch("https://example.org/boobytrap")
+        except AdapterError as exc:
+            assert "refused" in str(exc) or "not allowed" in str(exc)
+        else:
+            raise AssertionError("fetch of a private-redirecting URL must be refused")
@@ -190,10 +190,11 @@ def test_ledger_export_gate() -> None:
    from researchx.trust.liveness import LivenessStatus

    store = EvidenceStore()
-    store.add_passage("https://a", "passage one " * 20)
+    stored_text = "The verified sentence used for the export gate test."
+    store.add_passage("https://a", stored_text)
    ledger = build_ledger(
        run_id="abcd2345",
-        report_text="[p-1]",
+        report_text=f"{stored_text} [p-1]",
        evidence=store,
        liveness={"https://a": LivenessStatus.LIVE},
        visited_at=datetime.now(UTC),
@@ -204,7 +205,7 @@ def test_ledger_export_gate() -> None:

    ledger_dead = build_ledger(
        run_id="abcd2345",
-        report_text="[p-1]",
+        report_text=f"{stored_text} [p-1]",
        evidence=store,
        liveness={"https://a": LivenessStatus.DEAD},
        visited_at=datetime.now(UTC),
@@ -97,7 +97,10 @@ def _store_with_report() -> tuple[EvidenceStore, str]:
    store = EvidenceStore()
    for page in CORPUS[:3]:
        store.add_page(page.url, page.title, page.text)
-    report = f"# Report\n\nClaim one [{store.pages()[0].passage_ids[0]}] and claim two [p-1].\n"
+    first_passage = store.pages()[0].passage_ids[0]
+    stored = store.get(first_passage)
+    sentence = (stored.text if stored else "").split(".")[0] + "."
+    report = f"# Report\n\n{sentence} [{first_passage}]\n\nMore context [{first_passage}]\n"
    return store, report


@@ -121,9 +124,10 @@ async def test_ledger_build_and_checklist_export(monkeypatch) -> None:
        visited_at=datetime.now(UTC),
    )
    assert ledger.run_id == "abcd2345"
-    assert len(ledger.entries) == len(store.pages())
-    assert ledger.checklist.citations_checked == len(store.pages())
-    assert ledger.checklist.live == len(store.pages())
+    cited_url = store.pages()[0].url
+    assert [e.url for e in ledger.entries] == [cited_url]
+    assert ledger.checklist.citations_checked == 1
+    assert ledger.checklist.live == 1
    assert ledger.checklist.dead == 0
    assert ledger.checklist.anchored_claims >= 1
    assert all(
@@ -1,5 +1,12 @@
 # ResearchX Frontend

+**TL;DR** — This is the ResearchX web interface: ask a question, choose a research method, approve the plan, watch the live trace, read the cited report. The prototype runs entirely on scripted sample data — no API keys, no backend, no network — so the full product journey is tryable today.
+
+- **What** — A Next.js app (ask, choose, run, report, library, settings) rendering mock data through one typed client interface.
+- **Why** — The journey is checkable end-to-end before live inference exists.
+- **Action** — no action — FYI. Developers: Quickstart below (Node 20+, pnpm).
+- **Details** — Root `README.md`: backend engine, live mode, architecture.
+
 The prototype frontend for ResearchX — methodology-driven deep research
 with a trust loop. This milestone (v0.1) runs **entirely on mock data**:
 no API keys, no env vars, no network calls beyond static assets.
@@ -1,6 +1,6 @@
 {
  "name": "@researchx/frontend",
-  "version": "0.1.8",
+  "version": "0.2.5",
  "private": true,
  "packageManager": "pnpm@12.6.0",
  "scripts": {
@@ -107,6 +107,6 @@ describe("SettingsView (REQ-65)", () => {
    expect(screen.getByText("preview", { exact: true })).toBeInTheDocument();

    expect(screen.getByText(/About & version|About and version/i)).toBeInTheDocument();
-    expect(screen.getByText(/v0\.1\.8 · prototype/i)).toBeInTheDocument();
+    expect(screen.getByText(/v0\.2\.5 · MVP release candidate/i)).toBeInTheDocument();
  });
 });
@@ -244,8 +244,9 @@ export function SettingsView() {
            visited-only citations, three clicks to a trustworthy report.
          </p>
          <p className="mt-2 text-caption text-ink-faint">
-            v0.1.8 · prototype — runs on scripted mock data; the engine,
-            adapters, and trust loop arrive in v0.2.
+            v0.2.5 · MVP release candidate — mock-backed by default; the
+            engine, adapters, and trust loop ship with v0.2 (live mode:
+            NEXT_PUBLIC_RESEARCHX_API_MODE=live).
          </p>
        </section>
Author	SHA1	Message	Date
jonathan	57528d7473	Merge pull request 'fix: count a run completed at the DONE transition, not after it (researchx#28)' (#29 ) from po/fix-cost-counter-race into main ci / backend (uv, Python 3.12: ruff/mypy/pytest) (push) Successful in 32s Details ci / frontend (Next.js on pnpm: typecheck/lint/test/build) (push) Successful in 1m37s Details Reviewed-on: #29	2026-10-27 22:36:42 +00:00
jonathan	f790435023	Merge branch 'main' into po/fix-cost-counter-race ci / backend (uv, Python 3.12: ruff/mypy/pytest) (push) Successful in 32s Details ci / frontend (Next.js on pnpm: typecheck/lint/test/build) (push) Successful in 1m36s Details ci / backend (uv, Python 3.12: ruff/mypy/pytest) (pull_request) Successful in 32s Details ci / frontend (Next.js on pnpm: typecheck/lint/test/build) (pull_request) Successful in 1m35s Details	2026-10-27 22:35:50 +00:00
jonathan	b29105adf3	Merge pull request 'ci: quote the two job names so the gate file parses (researchx#24)' (#27 ) from po/phase4-ci-trigger2 into main ci / backend (uv, Python 3.12: ruff/mypy/pytest) (push) Successful in 31s Details ci / frontend (Next.js on pnpm: typecheck/lint/test/build) (push) Successful in 1m36s Details Reviewed-on: #27	2026-10-27 22:35:39 +00:00
coreci-researchx-po	70243eeb8b	fix: count a run completed at the DONE transition, not after it (researchx#28) ci / backend (uv, Python 3.12: ruff/mypy/pytest) (push) Successful in 31s Details ci / frontend (Next.js on pnpm: typecheck/lint/test/build) (push) Successful in 1m35s Details ci / backend (uv, Python 3.12: ruff/mypy/pytest) (pull_request) Successful in 31s Details ci / frontend (Next.js on pnpm: typecheck/lint/test/build) (pull_request) Successful in 1m35s Details The cost counter was incremented by a watcher that awaited the run task, so it lagged the status flip: the run read as done while /api/config still counted zero completed runs. The increment now happens in the same step as the transition to DONE, so any client that observes the run as done also observes the counter. Refs researchx#28	2026-10-27 05:18:51 +00:00
coreci-researchx-po	c7ce780edd	ci: quote the two job names - the file could not parse ci / backend (uv, Python 3.12: ruff/mypy/pytest) (pull_request) Failing after 31s Details ci / frontend (Next.js on pnpm: typecheck/lint/test/build) (pull_request) Successful in 1m39s Details ci / backend (uv, Python 3.12: ruff/mypy/pytest) (push) Successful in 32s Details ci / frontend (Next.js on pnpm: typecheck/lint/test/build) (push) Successful in 1m38s Details The gate file has never parsed: the two job names were plain scalars containing ': ' (YAML 1.2 plain-scalar rule - a colon followed by a space ends the scalar and starts a mapping, so the file fails to load). Gitea cannot build a run from a file it cannot parse, and the tell is a dispatch POST answered HTTP 500 with an empty body. Measured at this seat, own PAT, own repo: dispatch on main -> HTTP 500, dispatch on this branch -> HTTP 500, 0 run records, 0 queued jobs. Quoting the two names is the whole change; gates, labels, toolchain and the trigger shape (workflow_dispatch: {} -> workflow_dispatch:) are unchanged. Evidence and the follow-up dispatch live on researchx#24.	2026-10-27 04:34:06 +00:00
coreci-researchx-po	95681c4b97	ci: workflow_dispatch as a null trigger, not an empty map (researchx#24 - the fleet control)	2026-10-27 03:41:30 +00:00
jonathan	5d9b6fca23	Merge pull request 'ci: fire the pipeline - the trigger shape this instance actually runs (researchx#24)' (#26 ) from po/phase4-ci-trigger into main Reviewed-on: #26	2026-10-27 03:34:53 +00:00
coreci-researchx-po	ae2584c7f7	ci: pin a runner label that exists (ubuntu-latest) and install uv+pnpm in-file (researchx#24)	2026-10-27 03:29:06 +00:00
coreci-researchx-po	de6c4e096c	ci: fire the pipeline - bare push trigger and a non-null workflow_dispatch (researchx#24)	2026-10-27 00:59:08 +00:00
jonathan	b9108ae873	Merge pull request 'ci: register the phase-4 gate - backend + frontend jobs, one dispatched green run on main opens the code phase (researchx#24)' (#25 ) from po/phase4-ci-gate into main Reviewed-on: #25	2026-10-26 23:18:24 +00:00
coreci-researchx-po	01e2d2702c	ci: register the phase-4 gating workflow (researchx#24) - backend (uv/Python 3.12: ruff, mypy, pytest) + frontend (Node 22/pnpm 12.6.0: typecheck, lint, test, build); one dispatched run on main with both jobs green opens the code phase	2026-10-26 12:55:48 +00:00
coreci-hap	ab1cf5f3f8	Merge pull request 'comms-etiquette v1.0 pass: TL;DR prologues for README + frontend/README (researchx#20)' (#21 ) from docs/comms-etiquette-tldr-prologues into main	2026-10-19 19:51:57 +00:00
coreci-researchx-po	9ace9d8a02	docs(comms): TL;DR prologue for frontend/README.md (comms-etiquette v1.0; researchx#20)	2026-10-19 19:43:57 +00:00
coreci-researchx-po	c1e8e53e5b	docs(comms): TL;DR prologue for README.md (comms-etiquette v1.0; researchx#20)	2026-10-19 19:43:51 +00:00
coreci	8db45e478b	docs(release): v0.2.5 published — approved milestone release; ledger closed for v0.2 ---ci--- phase: 5 milestone: v0.2 status: complete escalation: type: deploy hook: deploy resolution: auto directive: milestone release publication post-approval message: >- The approved milestone release v0.2.5 published. Gitea release retitled to note the recorded approval (decision `4721c2a`) and G-009 ratification. The deployed container at https://research.coreci.dev already serves the release content (the v0.2.5-uat staging was built from the same milestone HEAD as the merged release) - no redeploy needed. DEPLOY-RECORD ledger row added; v0.2 milestone cycle closed. requirements: covered: [] partial: [] ---/ci---	2026-09-29 15:29:21 +00:00
coreci	702d3aae71	chore(milestone): clear checkpoint — v0.2-mvp complete ---ci--- phase: 5 milestone: v0.2 status: complete message: >- Milestone v0.2-mvp COMPLETE and APPROVED. Checkpoint cleared per the run workflow: the next /ci-run starts milestone v0.3 at phase 0 (pre-execution: specify, clarify, research, plan, grill, mvp/ux check), which config.json now points at (tag line v0.3.x). v0.3 scope is pending owner direction: live-bound library/settings/suggestions/refine surfaces (G-009 ratified scope), backend hosting for the LXC deployment, and the remaining 6 methodologies from the locked catalog. requirements: covered: [REQ-01, REQ-02, REQ-03, REQ-04, REQ-05, REQ-06, REQ-07, REQ-08, REQ-09, REQ-10, REQ-11, REQ-12, REQ-13, REQ-14, REQ-15, REQ-16, REQ-17, REQ-18, REQ-19, REQ-20, REQ-21, REQ-22, REQ-23, REQ-24, REQ-25, REQ-26, REQ-31, REQ-32, REQ-33, REQ-34] partial: [] ---/ci--- Milestone branch will be deleted (local + remote); tags v0.2.0-v0.2.5 and the main merge (`b11b202`) preserve the full history. v0.3 unblocked.	2026-09-29 15:28:52 +00:00
coreci-bot	b11b202271	milestone: v0.2 MVP — approved, merge to main (#15 )	2026-09-29 15:28:45 +00:00