From 6ee4cbbf39d43145f543f4d99956e9562e34e030 Mon Sep 17 00:00:00 2001 From: coreci Date: Sat, 26 Sep 2026 23:46:58 +0000 Subject: [PATCH] docs(init): initialize researchx (6 phases) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ---ci--- phase: 0 milestone: v1.0 status: specify autonomy: full decisions: - id: D-001 decision: Milestone v1.0 scope = slice 1 core loop (Ask → Choose → Plan & Run) with Rapid Answer + Deep Report only rationale: Phased MVP approved in planning session; 8-methodology catalog locked in vision but rolled out across milestones confidence: 0.95 alternatives: [all 8 methodologies in v1.0, backend-engine-first] - id: D-002 decision: Custom async engine (hand-rolled asyncio state machine) instead of LangGraph rationale: Full control over pause/resume, durable state, and trace streaming; avoids framework lock-in (open_deep_research archived Aug 2026) confidence: 0.85 alternatives: [langgraph engine, custom-deferred-interrupts] - id: D-003 decision: Stack = FastAPI (Python 3.12, uv, pydantic) + Next.js App Router (TypeScript strict) rationale: Best fit for adapter/LLM ecosystem; gpt-researcher validates the split; OpenAPI generates typed frontend client confidence: 0.9 alternatives: [python cli-first, typescript end-to-end] - id: D-004 decision: Model adapter defaults to Ollama cloud (ollama.com/v1, keyed) with keyless localhost:11434/v1 fallback rationale: User clarification — covers cloud + local in one default; graceful degradation confidence: 0.9 alternatives: [cloud-only, local-first] - id: D-005 decision: Release target = Gitea git.coreci.dev/coreci/researchx; secrets in .ciagent/.env.secrets (0600, gitignored) rationale: User-provided forge target and credentials; keys never in config.json or git confidence: 1.0 alternatives: [local-only] - id: D-006 decision: Phase tags run on v0.9.x patch line; final phase patch tag is the v1.0 milestone release rationale: Branch-strategy tag rules — tags run on previous minor's patch line, no separate milestone tag confidence: 0.9 alternatives: [tags on v1.0.x line] ---/ci--- Specification: ResearchX deep-research studio — BYO model/storage/memory, methodology-first selection, visited-only verified citations, 3-click core loop Requirements: 12-dial methodology framework, 5 adapter slots, custom async engine, trust loop, API + Next.js frontend, fake-adapter test suite Constraints: local-first single-user, OpenAI-compatible endpoints only, no paywalled academic access, secrets never committed Out of scope: chatbot/model host/closed index, auth/multi-tenancy, remaining 6 methodologies (v2 backlog) --- .ciagent/ARCHITECTURE.md | 68 ++++++++++++++++++++++++++ .ciagent/CHECKPOINT.json | 6 +++ .ciagent/PROJECT.md | 48 ++++++++++++++++++ .ciagent/REQUIREMENTS.md | 102 +++++++++++++++++++++++++++++++++++++++ .ciagent/ROADMAP.md | 58 ++++++++++++++++++++++ .ciagent/config.json | 28 +++++++++++ .gitignore | 5 ++ 7 files changed, 315 insertions(+) create mode 100644 .ciagent/ARCHITECTURE.md create mode 100644 .ciagent/CHECKPOINT.json create mode 100644 .ciagent/PROJECT.md create mode 100644 .ciagent/REQUIREMENTS.md create mode 100644 .ciagent/ROADMAP.md create mode 100644 .ciagent/config.json create mode 100644 .gitignore diff --git a/.ciagent/ARCHITECTURE.md b/.ciagent/ARCHITECTURE.md new file mode 100644 index 0000000..a089b14 --- /dev/null +++ b/.ciagent/ARCHITECTURE.md @@ -0,0 +1,68 @@ +# Architecture + +## Overview +Three-tier local-first web application: Next.js frontend → FastAPI backend → custom async research engine, with all external capabilities (model, search, storage, memory, secrets) isolated behind hot-swappable adapter interfaces. The engine is a hand-rolled asyncio state machine; every run persists its resolved 12-dial configuration and full event trace for reproducibility and auditability. + +## Components + +### 1. Methodology Framework (`src/researchx/config/`, `src/researchx/methodologies/`) +Typed pydantic schema for the 12 dials (source universe, search routing, query strategy, breadth, depth, quality gates, citation rigor, verification passes, synthesis style, output structure, memory scope, checkpoints) with safe defaults. A methodology is a named dial bundle + planner/writer prompt templates + output shape. Registry resolves methodologies by slug; every run snapshots resolved dial values. + +- **Boundaries:** pure data + prompts, no I/O. Depends on nothing internal. +- **DependsOn:** none + +### 2. Adapter Layer (`src/researchx/adapters/`) +Five pluggable slots with versioned contracts: +- **Model**: any OpenAI-compatible endpoint (covers Ollama cloud/local and vLLM); separate planner/writer roles; capability probe on connect (context window estimate, conservative request cap = min(model claim, 8192), embedding batch 8) surfaced as UI overrides; structured-output capability warning. Default: ollama.com/v1 cloud-first with localhost:11434/v1 fallback. +- **Search**: Tavily default; DuckDuckGo keyless fallback; interface ready for Exa/Perplexity later. +- **Storage**: local filesystem adapter; reports as plain Markdown/JSON under user-chosen directory; run state as JSON after each transition. +- **Memory**: off in v1.0 — interface stubbed for semantic caching. +- **Secrets**: env-file provider in v1.0 — interface stubbed for OpenBao. + +- **Boundaries:** all external I/O lives here; engine never imports vendor SDKs directly. +- **DependsOn:** config (dial schemas only) + +### 3. Research Engine (`src/researchx/engine/`) +Custom asyncio state machine: PLANNING → AWAITING_APPROVAL → SEARCHING → EXTRACTING → REFLECTING → (depth loop) → SYNTHESIZING → VERIFYING → DONE. One RunActor per run; durable JSON state persisted to storage after each transition (pause/cancel/resume); typed event bus feeding SSE live trace; plan (sub-questions + source universe + outline) halts at AWAITING_APPROVAL until approved/edited. + +- **Boundaries:** orchestrates; contains no HTTP handling and no vendor I/O. +- **DependsOn:** adapters, methodologies, trust, evidence + +### 4. Evidence Store (`src/researchx/evidence/`) +Visited-page store with stable passage IDs; passage extraction from fetched pages. The only source of writer context — the visited-only citation constraint is enforced by construction: the writer sees nothing else. + +- **Boundaries:** owns evidence data model. +- **DependsOn:** adapters (search/storage only) + +### 5. Trust Loop (`src/researchx/trust/`) +Runs inside every methodology: generation-time visited-only constraint [E1]; post-run URL liveness pass with live/stale/dead classification [E1]; claim-to-passage quote anchoring (fuzzy match against stored passages) [E1b]; citation ledger JSON per run (URL, visited_at, passages, claims supported, health, authority tier); verification checklist export. + +- **Boundaries:** read side of evidence store; verification reports feed the ledger. +- **DependsOn:** evidence, adapters (model for verification passes) + +### 6. API Layer (`src/researchx/api/`) +FastAPI routes: POST /api/runs, GET /api/methodologies, GET /api/runs/{id}, approve/pause/cancel/resume, GET /api/runs/{id}/events (SSE), GET /api/config. OpenAPI schema generates the typed frontend client. + +- **Boundaries:** transport only — no business logic. +- **DependsOn:** engine, methodologies, config + +### 7. Frontend (Next.js App Router, TypeScript strict) +Screens: Ask (question + optional context), Choose (methodology cards with ETA/cost/why-recommended; dials behind "advanced"), Plan & Run (approve/edit plan, live SSE trace, pause/cancel), Reading Room v0 (rendered report, hover-a-citation → exact quoted passage, ledger panel, Markdown/JSON export). + +- **Boundaries:** consumes typed API client; no direct engine access. +- **DependsOn:** API layer (via generated client) + +## Data Flow +Ask (question + context) → Choose (methodology slug + dial overrides) → POST /api/runs → engine PLANNING (planner model via model adapter, dial bundle resolved) → AWAITING_APPROVAL (plan persisted; SSE events; user approves/edits) → SEARCHING (search adapter, routing per dials) → EXTRACTING (fetch pages → evidence store, stable passage IDs) → REFLECTING (planner model; depth loop per dials) → SYNTHESIZING (writer model; context = evidence passages only, per-claim citation markers) → VERIFYING (liveness pass, quote anchoring, confidence labels) → DONE (report + ledger + checklist persisted to storage; Reading Room renders; export). + +## Build Order +1. Methodology framework (dial schema + 2 seed methodologies + registry) +2. Adapter layer (model/search/storage contracts + local implementations; fake adapters for tests) +3. Evidence store (visited pages, passage extraction) +4. Trust loop (liveness, anchoring, ledger) +5. Engine (state machine, event bus, durable state, pause/resume) +6. API layer (routes + SSE) +7. Frontend (Ask → Choose → Plan & Run → Reading Room v0) +8. Adversarial test suite (hallucinated-URL detection, quote-mismatch detection, pause/resume mid-depth-loop) + E2E happy path + +Build order is dependency-driven: trust verification requires evidence; engine requires adapters + trust; API requires engine; frontend requires API. \ No newline at end of file diff --git a/.ciagent/CHECKPOINT.json b/.ciagent/CHECKPOINT.json new file mode 100644 index 0000000..719a38d --- /dev/null +++ b/.ciagent/CHECKPOINT.json @@ -0,0 +1,6 @@ +{ + "phase": 0, + "stage": "specify", + "milestone": "v1.0", + "phase_role": "pre_execution" +} \ No newline at end of file diff --git a/.ciagent/PROJECT.md b/.ciagent/PROJECT.md new file mode 100644 index 0000000..3b80544 --- /dev/null +++ b/.ciagent/PROJECT.md @@ -0,0 +1,48 @@ +# ResearchX + +## Name +ResearchX (working name; rename deferred — naming collision audit on file, see vision Decisions Log) + +## Core Value +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. Simple enough to run in three clicks, transparent enough to audit line by line. + +## Objective (MVP milestone v1.0) +Build the 3-click happy path end-to-end: Ask → Choose (methodology cards) → Plan & Run (approved plan + live interruptible trace), with a custom async engine, a hot-swappable adapter layer, the trust loop (visited-only citations, URL liveness verification, quote anchoring, citation ledger), and the two seed methodologies (Rapid Answer, Deep Report). + +## Requirements (validated) +1. Five pluggable adapter slots: model (OpenAI-compatible, planner/writer split), storage (local FS), search (Tavily default, DuckDuckGo keyless fallback), memory (off — stubbed), secrets (env — OpenBao later) +2. Hardware-aware defaults: probe backend, cap requests conservatively (8192 context default, embedding batch 8), surface overrides in UI, degrade gracefully +3. 12-dial methodology framework (typed schema, every run persists resolved dial values for reproducibility/auditability) +4. Methodology registry shipping Rapid Answer (depth 1/breadth 1/memo/per-claim citations) and Deep Report (depth 3/breadth 2/executive report/full verification); 8-methodology catalog locked for v1, phased rollout +5. Custom async engine: state machine PLANNING → AWAITING_APPROVAL → SEARCHING → EXTRACTING → REFLECTING → SYNTHESIZING → VERIFYING → DONE; durable JSON state; pause/cancel/resume; typed event bus → SSE live trace +6. Trust loop in every methodology: visited-only constraint at generation time; URL liveness pass with live/stale/dead classification; claim-to-passage quote anchoring; citation ledger JSON per run; exportable verification checklist +7. API surface: POST /api/runs, GET /api/methodologies, run lifecycle (approve/pause/cancel/resume), SSE events, config status; OpenAPI-generated typed frontend client +8. Frontend: Ask, Choose, Plan & Run screens + Reading Room v0 (page-anchored citations with hover quotes, ledger panel, Markdown/JSON export) +9. Testing: fake model/search adapters enabling zero-API-key engine tests; adversarial hallucinated-URL and quote-mismatch detection tests targeting ≥99% citation liveness +10. Tech stack: FastAPI (Python 3.12, uv, pydantic) + Next.js App Router (TypeScript strict) + +## Requirements (active, later phases) +- Remaining 6 methodologies: SOTA Survey, Systematic Review (PRISMA-like), Fact-Check Dossier, Multi-Perspective Dossier, Competitive Landscape, Corpus Interrogation +- Reading Room full: project graph, global search, task inbox, confidence labels, BibTeX/PDF export +- Memory scopes (semantic caching), S3/git storage adapters, Exa/Perplexity/Google search, OpenBao secrets, Docker packaging + +## Constraints +- Not a general-purpose chatbot; not a model host; not a closed content index (v1) +- Paywalled academic access out of scope v1 — open APIs (ArXiv/PubMed) only +- Single-user, local-first tool — no auth/multi-tenancy in MVP +- Ollama/vLLM supported via OpenAI-compatible endpoints only (no vendor-specific adapters) +- Secrets never in app config or git; model capability honesty (warn when selected model is weak at structured outputs) + +## Out of Scope +- Paywalled academic sources; model hosting; multi-tenant/auth; native Ollama API adapter; domain registration/rename decision + +## Context +Vision finalized and locked 2026-09-26: v1 methodology composition LOCKED (8 core), product named ResearchX, OpenBao retained as architectural secrets component, criticism matrix and evidence base [E1]–[E15] on file. MVP plan approved this session: phased slices — slice 0 scaffolding, slice 1 core loop (this milestone), slices 2–4 extend catalog/adapters/infrastructure. + +## Key Decisions +- Methodology-first selection is the core differentiator, not raw model quality — converts ad-hoc prompt-crafting into structured, reproducible selection +- Visited-only citation constraint + mandatory verification pass in all methodologies — deep-research agents hallucinate URLs at the highest measured rates; verification cuts failures to <1% [E1] +- Progressive disclosure resolves granular-vs-simple tension — defaults on the surface, dials on demand +- Custom async engine (hand-rolled asyncio state machine) over LangGraph — full control over pause/resume, durable state, trace streaming; framework lock-in avoided +- NotebookLM-style source grounding kept; source-blindness removed via quality annotation +- Model adapter default: Ollama cloud-first (ollama.com/v1) with keyless localhost:11434/v1 fallback on auth/connection failure \ No newline at end of file diff --git a/.ciagent/REQUIREMENTS.md b/.ciagent/REQUIREMENTS.md new file mode 100644 index 0000000..122a6f1 --- /dev/null +++ b/.ciagent/REQUIREMENTS.md @@ -0,0 +1,102 @@ +# Requirements + +## V1 (Milestone v1.0 — Core Loop) + +### Methodology Framework +- **REQ-01**: Typed pydantic schema for the 12 methodology dials (source universe, search routing, query strategy, breadth, depth, quality gates, citation rigor, verification passes, synthesis style, output structure, memory scope, checkpoints), each with a safe default value +- **REQ-02**: Methodology = named dial bundle + planner/writer prompt templates + output shape; registry resolves by slug +- **REQ-03**: Methodology registry ships Rapid Answer (depth 1, breadth 1, memo output, per-claim citations) and Deep Report (depth 3, breadth 2, executive report, full verification) +- **REQ-04**: Every run persists its resolved dial values → runs are reproducible and auditable +- **REQ-05**: Methodology choice measurably changes behavior: different query sets, depth, and output shape between methodologies + +### Adapters +- **REQ-06**: Model adapter accepts any OpenAI-compatible endpoint with separate planner and writer roles +- **REQ-07**: Capability probe on connect: context window estimate, conservative request cap (min of model claim and 8192), embedding batch 8; overrides surfaced in UI; degrade gracefully — never OOM a backend [E4][E5][E6] +- **REQ-08**: Default model endpoint ollama.com/v1 (cloud, keyed) with automatic localhost:11434/v1 (keyless) fallback on auth/connection failure +- **REQ-09**: Search adapter with Tavily default and keyless DuckDuckGo fallback; interface extensible to Exa/Perplexity later +- **REQ-10**: Storage adapter writes reports as plain Markdown/JSON to a user-chosen local directory; no upload quotas +- **REQ-11**: Memory slot stubbed (off) and secrets slot env-file-backed; both hot-swappable via interface without config edits +- **REQ-12**: Methodologies needing structured outputs warn when the selected model is weak at function calling rather than failing cryptically + +### Engine +- **REQ-13**: Custom asyncio state machine: PLANNING → AWAITING_APPROVAL → SEARCHING → EXTRACTING → REFLECTING → (depth loop) → SYNTHESIZING → VERIFYING → DONE +- **REQ-14**: Plan = sub-questions + source universe + outline; run halts at AWAITING_APPROVAL until approved or edited +- **REQ-15**: Durable run state persisted as JSON after each state transition; pause/cancel/resume works across process restarts +- **REQ-16**: Typed event bus → SSE live trace (query fired, source visited, passage extracted); every run records a trace file +- **REQ-17**: New user → research running in ≤3 clicks using defaults only + +### Trust Loop +- **REQ-18**: Generation-time visited-only constraint: writer context contains only stored evidence passages with stable IDs [E1] +- **REQ-19**: Post-run URL liveness pass with live/stale/dead classification [E1] +- **REQ-20**: Claim-to-passage quote anchoring: every cited quote fuzzy-matches a stored passage; mismatches flagged [E1b] +- **REQ-21**: Citation ledger JSON per run: URL, visited_at, passages, claims supported, health, authority tier +- **REQ-22**: Exportable verification checklist attached to every final report +- **REQ-23**: ≥99% of citations in shipped reports pass the liveness check +- **REQ-24**: Confidence labels: single-source vs corroborated claims + +### API & Frontend +- **REQ-25**: API: POST /api/runs; GET /api/methodologies (cards with ETA, cost estimate, why-recommended); GET /api/runs/{id}; approve/pause/cancel/resume; GET /api/runs/{id}/events (SSE); GET /api/config (adapter status + probe results) +- **REQ-26**: OpenAPI schema generates a typed frontend client +- **REQ-27**: Ask screen: one question box + one optional context box +- **REQ-28**: Choose screen: 3–5 ranked methodology cards with ETA/cost/why; dials behind "advanced" (progressive disclosure) +- **REQ-29**: Plan & Run screen: approved plan display, live interruptible trace, pause/cancel controls +- **REQ-30**: Reading Room v0: page-anchored citations (hover shows exact quoted passage), ledger panel, Markdown/JSON export with citations surviving as real links + +### Testing & Infrastructure +- **REQ-31**: Fake model + fake search adapters (canned planner/writer, fixture corpus) → full engine tests with zero API keys +- **REQ-32**: Adversarial tests: hallucinated-URL writer caught by verifier; quote-anchor mismatch detection; pause/resume mid-depth-loop +- **REQ-33**: Monorepo: uv-managed backend (ruff, mypy, pytest) + Next.js frontend (ESLint, strict TS, Vitest); one-command install/dev +- **REQ-34**: Full export round-trip: report + ledger + citations survive as real links + +## V2 (Post-v1.0) + +### Methodology Catalog Extension +- **REQ-35**: SOTA Survey (academic+web routing, outline-first encyclopedic synthesis) +- **REQ-36**: Systematic Review (PRISMA-like flow, academic-only, strictest rigor) +- **REQ-37**: Fact-Check Dossier (adversarial evidence for/against, mandatory quote anchoring) +- **REQ-38**: Multi-Perspective Dossier (steelmanned opposing views) +- **REQ-39**: Competitive Landscape (comparison matrix, per-cell provenance) +- **REQ-40**: Corpus Interrogation (local documents only, chunk+rerank, quality annotation, no caps) + +### Source Quality & Routing +- **REQ-41**: ArXiv/PubMed academic API routing +- **REQ-42**: Authority tiers, SEO-farm blocklist, paywall handling +- **REQ-43**: Source quality annotation panel (grounding kept, blindness removed) + +### Reading Room Full +- **REQ-44**: Project graph with cross-linked sources and findings across projects +- **REQ-45**: Global search; task inbox (open questions become checkable follow-ups) +- **REQ-46**: BibTeX/PDF export + +### Infrastructure Extension +- **REQ-47**: Memory scopes: none/project/cross-project + semantic caching to cut repeat-query cost +- **REQ-48**: S3-compatible and git-repo storage adapters +- **REQ-49**: Exa, Perplexity, Google search adapters +- **REQ-50**: OpenBao secrets integration (lease/revocation; keys never in app config) +- **REQ-51**: Docker packaging + +## Out of Scope +| Feature | Reason | +|---|---| +| Paywalled academic access | Unsolved in v1 — routed around via open APIs (vision §8) | +| General-purpose chatbot / model host / closed content index | Explicit non-goals (vision §8) | +| Auth / multi-tenancy | Single-user local-first MVP | +| Native Ollama API adapter | Ollama supported via OpenAI-compatible endpoint only | +| Domain registration / product rename | Deferred by owner (vision §11) | + +## Traceability +| Requirement | Phase | Status | +|---|---|---| +| REQ-01..06, REQ-08..11 (framework, adapters) | P1 | pending | +| REQ-31 (fake adapters) | P1 | pending | +| REQ-07, REQ-12 (probing, warnings) | P2 | pending | +| REQ-13..17 (engine) | P2 | pending | +| REQ-18..24 (trust loop) | P2 | pending | +| REQ-25 (API) | P3 | pending | +| REQ-26 (typed client) | P3 | pending | +| REQ-33 (monorepo tooling) | P3 | pending | +| REQ-27..30 (frontend) | P4 | pending | +| REQ-17 (≤3 clicks) | P4 | pending | +| REQ-32, REQ-34 (adversarial, round-trip) | P5 | pending | +| All REQ-01..34 (milestone gate) | P6 | pending | +| REQ-35..51 | v2 backlog (next milestone) | pending | \ No newline at end of file diff --git a/.ciagent/ROADMAP.md b/.ciagent/ROADMAP.md new file mode 100644 index 0000000..4c1fbb4 --- /dev/null +++ b/.ciagent/ROADMAP.md @@ -0,0 +1,58 @@ +# Roadmap — Milestone v1.0 (MVP Core Loop) + +## Overview +Milestone v1.0 delivers the ResearchX 3-click happy path: Ask → Choose methodology → Plan & Run, powered by a custom async engine, hot-swappable adapters, the trust loop, and the two seed methodologies (Rapid Answer, Deep Report). Five execution phases follow phase 0. Per branch-strategy tag rules, phase tags run on the previous minor's patch line: phase 0 ships as v0.9.0, execution phases as v0.9.1–v0.9.5, and the final phase's patch tag (v0.9.6) IS the milestone release — no separate minor tag is created. Post-v1.0 methodology catalog and infrastructure extensions (REQ-35..51) are tracked as v2 backlog. + +## Phases + +### Phase 0 — Pre-Execution (in progress) +- **Description**: Specification parsing, clarification, .ciagent/ reference files (PROJECT, ARCHITECTURE, REQUIREMENTS, ROADMAP), initial commit. Vision locked: 8-methodology catalog (composition frozen), MVP plan approved (custom async engine, FastAPI + Next.js). +- **Requirements covered**: none (planning artifacts) +- **Success criteria**: .ciagent/ files committed on phase/00-pre-execution; milestone v1.0 established in config.json and PROJECT.md; decisions logged in init commit +- **Depends on**: — +- **Status**: in_progress + +### Phase 1 — Methodology Framework + Adapter Layer +- **Description**: Dial schema (12 dials, typed, safe defaults), methodology registry with Rapid Answer + Deep Report, adapter contracts (model/search/storage/memory/secrets) with local implementations, capability probing with conservative caps (8192 context, embedding batch 8, Ollama cloud-first + local fallback), fake model/search adapters for tests. +- **Requirements covered**: REQ-01..06, REQ-08..11, REQ-31 +- **Success criteria**: registry resolves both methodologies from dial bundles; fake adapters drive contract tests; model probe caps requests and surfaces overrides; zero-API-key test suite green +- **Depends on**: 0 +- **Status**: not_started + +### Phase 2 — Research Engine + Trust Loop +- **Description**: Asyncio state machine with durable JSON state and pause/cancel/resume; plan approval gate; typed event bus → SSE; evidence store with stable passage IDs; trust loop (visited-only constraint, URL liveness pass, quote anchoring, citation ledger, verification checklist, confidence labels). +- **Requirements covered**: REQ-07, REQ-12, REQ-13..24 +- **Success criteria**: engine completes depth-loop runs on fake adapters; run state survives process restart mid-run; hallucinated-URL and quote-mismatch adversarial tests pass; ≥99% citation liveness on fixture corpus +- **Depends on**: 1 +- **Status**: not_started + +### Phase 3 — API Layer + Typed Client +- **Description**: FastAPI routes (runs, methodologies, lifecycle, SSE events, config status); OpenAPI-generated typed frontend client; ETA/cost estimation heuristics for methodology cards. +- **Requirements covered**: REQ-25, REQ-26 +- **Success criteria**: full run lifecycle drivable over HTTP; SSE trace streams live; generated client typechecks strict +- **Depends on**: 2 +- **Status**: not_started + +### Phase 4 — Frontend (Ask / Choose / Plan & Run / Reading Room v0) +- **Description**: Next.js App Router screens: Ask, Choose (progressive disclosure dials), Plan & Run (live trace, pause/cancel), Reading Room v0 (page-anchored citations, ledger panel, Markdown/JSON export). ≤3-click happy path with defaults. +- **Requirements covered**: REQ-27..30, REQ-17 +- **Success criteria**: new user reaches a running research session in ≤3 clicks on defaults; citations hover to exact quoted passages; export round-trips (REQ-34) +- **Depends on**: 3 +- **Status**: not_started + +### Phase 5 — 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). +- **Requirements covered**: REQ-32, REQ-33, REQ-34 +- **Success criteria**: adversarial suite green; E2E green; README quickstart works from clean clone +- **Depends on**: 4 +- **Status**: not_started + +### Phase 6 — Final Review + Ship +- **Description**: REVIEW + SHIP + AUDIT of milestone v1.0: requirements traceability verification, milestone merge to main, release. (Final phase is numeric: 6 execution phases → this is the 6th; merge/tag per branch-strategy.) +- **Requirements covered**: milestone gate (all REQ-01..34 verified) +- **Success criteria**: all v1 requirements complete or explicitly deferred with rationale; milestone tag created; release notes summarize milestone +- **Depends on**: 5 +- **Status**: not_started + +## Milestone Release +Feature milestone (contains feat phases) → next minor tag on milestone completion, per branch-strategy tag rules. v2 backlog (REQ-35..51) starts the next milestone cycle. \ No newline at end of file diff --git a/.ciagent/config.json b/.ciagent/config.json new file mode 100644 index 0000000..e1a1db2 --- /dev/null +++ b/.ciagent/config.json @@ -0,0 +1,28 @@ +{ + "ci_version": "0.7.0", + "projects": [], + "active_project": "researchx", + "milestone": "v1.0", + "milestone_type": "feature", + "autonomy": { + "level": "full", + "escalation_hooks": ["deploy", "delete_data", "merge_to_main"], + "decision_confidence_threshold": 0.6, + "max_revision_iterations": 3, + "clarify_budget": 10 + }, + "release": { + "forge": "gitea", + "base_url": "https://git.coreci.dev", + "owner": "coreci", + "repo": "researchx" + }, + "secrets": { + "env_file": ".ciagent/.env.secrets", + "scopes": { + "release": ["GITEA_TOKEN"], + "model": ["OLLAMA_API_KEY", "OLLAMA_BASE_URL"], + "search": ["TAVILY_API_KEY"] + } + } +} \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..57f9972 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +# CIAgent secrets — never commit +.env +.env.secrets +.env.* +!.env.example \ No newline at end of file