Dashboard/Intelligence-Research-OS/wiki/current-state.md
Intelligence-Research-OS

wiki/current-state.md

Intelligence Research OS — Current State

Last Updated: 2026-05-22
Source provenance: repository SESSION.md, repository CLAUDE.md, docs/workspace/intelligence-research-os-e2e/TEST_REPORT.md, git log --oneline -5, and local code inspection of src/research_module/app.py, src/research_module/intelligence.py, and src/research_module/cli.py.

Executive Status

Intelligence Research OS is in local-first workbench foundation state. The core ResearchModule engine is implemented through Scoper, AAR Planner, Fan-out 3A, Basic Synthesis 4A, and Heavy Multi-POV Synthesis 4B. The product layer now has mission schemas, mission CLI commands, twelve mission templates, a local FastAPI backend, and a static workbench UI that exercises a Competitive Intelligence demo workflow end to end.

The latest repository commits show the post-foundation UI checkpoint:

Commit Meaning
725fb4c feat: complete Intelligence OS workbench UI Latest UI/workbench checkpoint.
7462453 chore: clean project residue Cleanup after initial checkpoint.
d157c70 feat: build intelligence research os foundation First GitHub foundation checkpoint.

Built So Far

Core Engine

  • Python package research_module.
  • Strict Pydantic v2 schema contracts.
  • Atomic .tmp write plus validated rename artifact gates.
  • Citation integrity layer: claim -> evidence -> source validation.
  • Workspace and resumable state.json management.
  • Offline Scoper and live Challenger Scoper foundation.
  • AAR Planner with planning artifacts and source recording.
  • Perplexity Fan-out Supervisor 3A with canary-first execution, budget-cap behavior, raw provider outputs, source registry, evidence items, and compressed notes.
  • Basic Synthesis 4A with claim extraction, final outline, cited markdown report, and citation audit.
  • Heavy Multi-POV Synthesis 4B as the default synthesis path, with isolated perspective artifacts, reconciliation report, model-produced report draft, and strict citation audit.

Product Layer

  • Product framing renamed to Intelligence Research OS; research_module remains the core engine package.
  • Mission abstractions implemented in src/research_module/intelligence.py: MissionSpec, WatchSpec, SourcePack, Signal, SignalCluster, DeltaReport, OpportunityBrief, OutputPack, and mission service scaffolding.
  • Twelve mission templates are visible and selectable.
  • Competitive Intelligence is the first fully actionable vertical.
  • The other eleven mission templates create valid missions and source defaults, but their specialized vertical outputs remain pending.
  • Mission CLI surface exists: research mission create, research mission run, research mission status, and research mission show output.

Local Workbench

  • research app --workspace-parent <dir> --port <port> launches a local FastAPI backend and static UI.
  • Backend endpoints cover health, workspace, templates, missions, sources, signals, evidence, synthesis, outputs, deltas, and deterministic Markdown/JSON export.
  • UI screens implemented and browser-tested: Mission Control, New Mission Builder, Source Radar, Signal Inbox, Evidence Board, Synthesis Studio, Output Workspace, and Delta Timeline.
  • The UI consumes local file-gated artifacts; no database or parallel state model exists in v1.
  • Deterministic demo seed exists for the Competitive Intelligence path.
  • Unsupported findings are blocked at the Evidence Board.
  • Source readiness checks are redacted and do not expose secrets.

Documentation and UX

  • Competitive Intel proof gate documented.
  • Use-case coverage matrix documented.
  • Information architecture documented.
  • Six-screen GPT Image 2 mockup contract and assets captured.
  • E2E report exists at docs/workspace/intelligence-research-os-e2e/TEST_REPORT.md.

Key Decisions and Architecture Changes

Technical Decisions

  • Core engine first: ResearchModule is the product-grade engine; CLI, skill wrapper, app, and future API are thin adapters.
  • File-gated state machine: every pipeline step writes a temporary artifact, validates with Pydantic, then atomic-renames on success.
  • Two-layer type safety: Pydantic v2 validates runtime data boundaries; pyright --strict validates code at write time.
  • BYOK provider model: provider keys are supplied through SecretsProvider / .env.local / environment variables and are never written to logs, state, traces, or errors.
  • Source/evidence/citation gates: unsupported claims cannot pass final audit.
  • No scheduler in engine: cadence belongs to external workflow tools; Intelligence Research OS owns mission definition, execution quality, provenance, synthesis, and outputs.

Product and Design Decisions

  • Product boundary: Intelligence Research OS is the workbench/product layer; ResearchModule remains the core engine package.
  • Composite workbench UX: the UX is not a single dashboard. It is a workflow across Mission Control, Mission Builder, Source Radar, Signal Inbox, Evidence Board, Synthesis Studio, Output Workspace, and Delta Timeline.
  • Local file-gated workbench: v1 local app consumes the same artifacts as the engine instead of creating a second UI database.
  • Progressive template support: all twelve templates remain visible, with explicit support levels. Competitive Intelligence is fully actionable; the other templates are partial until vertical outputs are implemented.
  • Competitive Intelligence first: CI is the first executable vertical because it exercises missions, sources, signals, evidence, synthesis, output packs, and deltas.
  • Heavy multi-POV synthesis: synthesis runs isolated lens artifacts and reconciliation before final reporting. Latest memory suggests refining user-facing lens names around agreer/contrarian/pessimist/optimist/methodical expander while preserving the Evidence Judge role.

Latest Architecture Delta

The main architecture delta is that Intelligence Research OS now has a real local app surface over the file-gated engine, but mission execution is still split: the UI can create missions and run a deterministic Competitive Intelligence demo path, while live provider-backed execution remains connected through the CLI/backend engine path. The next architecture task is to remove that split by making UI mission runs create or continue real ResearchModule run artifacts.

Verification Status

Latest recorded verification from the project docs:

  • uv run pytest -q passed with 152 tests.
  • uv run ruff check . passed.
  • uv run ruff format --check . passed.
  • uv run pyright passed with 0 errors, 0 warnings, 0 informations.
  • Browser E2E report passed across the seven-screen workflow plus responsive checks.

Important caveat: the E2E workflow uses deterministic demo data for the UI path. Live provider execution is implemented in the CLI/backend engine path, but the UI Run Mission flow is not yet wired into the full live Scoper -> AAR -> Fan-out -> Synthesis pipeline.

Still Pending

  • Wire UI Run Mission into live engine execution beyond mission preparation and deterministic demo seed.
  • Implement source-backed signal generation from dossier artifacts.
  • Generate durable signals.json and signal_clusters.json from real evidence.
  • Build Competitive Intelligence battlecard and competitor digest rendering from live artifacts.
  • Add delta memory for repeated mission runs.
  • Add multi-provider Fan-out triangulation beyond Perplexity Sonar Pro.
  • Add premium report polish and richer contradiction handling.
  • Run real-provider smoke tests with actual Anthropic/Perplexity keys.
  • Build dedicated source adapters after provider-search/web-fetch v1 is stable.
  • Implement production-grade vertical output packs for the eleven non-CI templates.

Next Step

The next engineering step should be UI-to-engine live execution wiring:

  1. Make /api/missions/{mission_id}/run launch or continue a real ResearchModule run instead of only preparing the mission topic.
  2. Persist the generated research run id and phase transitions back into mission_run_report.json.
  3. Expose step-level status in Mission Control and Source Radar.
  4. Keep demo seed as explicit demo mode, not the default path.
  5. Add tests for mission run -> engine artifact creation -> UI status readback.

This step is the right unlock because source-backed signals, output packs, and delta memory all depend on real run artifacts being connected to mission artifacts.