Literature Review Wrapper

The repo-local wrapper around the OpenClaw literature search capability.

Workflow Rules · /home/jonas/social-carousel-codex/docs/literature-review-wrapper.md

Last modified: 2026-03-29T11:30:50.037Z

# Literature Review Wrapper

## Purpose

Phase 7 adds a repo-local adapter around the OpenClaw literature-review search capability:

```bash
python3 scripts/literature_review_wrapper.py build-package <spec.json>
```

This wrapper does not create a new search engine. It calls the reference script at:

- `/home/openclaw/workspace/skills/literature-review/scripts/lit_search.py`

It keeps the OpenClaw workspace read-only and uses the repo-local helper surface as the persistence layer.

## What The Wrapper Does

For one research package run, the wrapper:

1. loads a repo-local spec JSON
2. either:
   - calls the reference search script live, or
   - consumes a fixture-style raw-results JSON
3. normalizes the selected search results into deterministic source records
4. builds helper-ready `research-summary` inputs plus either a pre-approval research-lock proposal or an approval-ready lock input
5. writes research artifacts under `artifacts/research/<idea_id>/<research_bundle_id>/`
6. persists:
   - always `state/ideas/<idea_id>/research-summary.json`
   - optionally `state/ideas/<idea_id>/research-lock.json`

## Command Variants

Live search:

```bash
python3 scripts/literature_review_wrapper.py build-package /tmp/research-spec.json
```

Deterministic fixture mode:

```bash
python3 scripts/literature_review_wrapper.py build-package /tmp/research-spec.json --raw-results fixtures/phase7/raw-search-results.json
```

Approval-gated supervised mode:

```bash
python3 scripts/literature_review_wrapper.py build-package /tmp/research-spec.json --summary-only
```

The wrapper uses the same Python interpreter and invokes:

- `python3 scripts/runtime_state.py record-research-summary ...`
- optionally `python3 scripts/runtime_state.py approve-research ...`

With `--summary-only`, the wrapper writes `research-lock-proposal.json` under `artifacts/research/...`, but it does not persist `research-lock.json` or an approval-only lock input. This is the correct mode for supervised runs that must stop for explicit research approval.

Clean approval path after review:

```bash
python3 scripts/runtime_state.py show-research-package <idea_id>
python3 scripts/runtime_state.py approve-research-proposal <idea_id>
```

Optional explicit approval timestamp:

```bash
python3 scripts/runtime_state.py approve-research-proposal <idea_id> --approved-at 2026-03-29T10:00:00+07:00
```

## Required Spec Shape

The wrapper spec must provide:

- `idea_id`
- `query`
- `source`
- `limit`
- `max_sources`
- `selected_angle`
- `required_coverage`
- `slide_architecture`
- `forbidden_claims_or_inferences`

Useful optional fields:

- `approved_at`
- `generated_at`
- `research_bundle_id`
- `summary`
- `evidence_bullets`
- `supported_claims`
- `approval_status`

Minimal example:

```json
{
  "idea_id": "IDEA-local-phase7-wrapper-live",
  "query": "protein breakfast satiety adults",
  "source": "pm",
  "limit": 2,
  "max_sources": 2,
  "research_bundle_id": "RB-IDEA-local-phase7-wrapper-live-live",
  "selected_angle": {
    "option_number": 2,
    "title": "Morning protein steadies cravings",
    "full_text": "Why morning protein helps steady cravings..."
  },
  "required_coverage": [
    "Higher-protein breakfasts can improve satiety in adults.",
    "A protein-forward breakfast may help reduce rebound hunger later in the morning."
  ],
  "slide_architecture": [
    "cover",
    "content: satiety",
    "content: rebound hunger",
    "cta",
    "sources"
  ],
  "forbidden_claims_or_inferences": [
    "Do not claim breakfast protein cures disease."
  ]
}
```

`approved_at` is required only when the wrapper is expected to auto-persist `research-lock.json`. It is not required for `--summary-only`.

## Repo-Local Outputs

Artifact bundle:

- `artifacts/research/<idea_id>/<research_bundle_id>/search-spec.json`
- `artifacts/research/<idea_id>/<research_bundle_id>/search-results.json`
- `artifacts/research/<idea_id>/<research_bundle_id>/research-summary-input.json`
- `artifacts/research/<idea_id>/<research_bundle_id>/research-lock-proposal.json`
- optional `artifacts/research/<idea_id>/<research_bundle_id>/research-lock-approval-input.json`
- `artifacts/research/<idea_id>/<research_bundle_id>/wrapper-result.json`

Persisted workflow state:

- `state/ideas/<idea_id>/research-summary.json`
- optional `state/ideas/<idea_id>/research-lock.json`
- updated `state/ideas/<idea_id>/ledger.json`
- new checkpoint and event-log entries

## Deterministic Behavior

Deterministic aspects:

- the wrapper writes only inside this repo
- `source_id` assignment is deterministic for a given raw-results order
- helper input files are written atomically
- a fixed `research_bundle_id` can be supplied for dry runs
- `--raw-results` mode makes the whole path repeatable without live network access

Migration note:

- older Phase 7 bundles may still contain `research-lock-input.json`
- newly written bundles split that path into `research-lock-proposal.json` and optional `research-lock-approval-input.json`

Non-goal:

- semantic evidence synthesis from scratch

The wrapper is intentionally conservative. It transforms search results and binds them to explicitly provided business context. It does not invent claim interpretation or approval.

## Verified In Phase 7

Verified fixture-backed run:

- `IDEA-local-phase7-wrapper`
- used `--raw-results fixtures/phase7/raw-search-results.json`

Verified live-search run:

- `IDEA-local-phase7-wrapper-live`
- called the reference PubMed search path directly

Ready