ORP — Open Research Protocol (template pack)

ORP is a project-agnostic, docs-first, agent-friendly protocol for doing research (or research-like engineering) with:

• explicit claim levels,
• reproducible verification hooks,
• dispute handling that resolves disagreements by verification or downgrade (not argument),
• first-class “failed paths” (dead ends recorded as assets),
• and a non-blocking Alignment/Polish Log for optional wording/clarity suggestions.

Boundary (non-negotiable): ORP files are process-only. They are not evidence and must not be cited as proof for results. Evidence lives in your project’s canonical artifact paths (data, code, paper, proofs, logs, etc.).

ORP also supports optional, modular Instruments for framing inquiry upstream of claims. Instruments are process-only and verification remains independent of framing. See modules/instruments/README.md and docs/WHY_INSTRUMENTS.md.

What’s in this folder

• AGENT_INTEGRATION.md — optional: integrate ORP into an AI agent’s primary instruction file
• llms.txt — concise discovery guide for LLM and agentic systems
• PROTOCOL.md — the protocol to copy into a project
• INSTALL.md — how to adopt ORP in an existing repo or start a new project from it
• docs/AGENT_LOOP.md — canonical operating loop when an agent is the primary ORP user
• docs/CANONICAL_CLI_BOUNDARY.md — canonical source-of-truth boundary between CLI, Rust, and web
• docs/ORP_REASONING_KERNEL_V0_1.md — draft kernel model for turning loose intent into promotable canonical artifacts
• docs/ORP_REASONING_KERNEL_EVOLUTION.md — stable-core, observable-pressure, explicit-evolution model for growing the kernel over time
• docs/ORP_REASONING_KERNEL_TECHNICAL_VALIDATION.md — technical rationale, benchmarks, and alternatives analysis for the kernel
• docs/ORP_REASONING_KERNEL_COMPARISON_PILOT.md — first matched comparison between free-form, checklist, and kernel artifacts
• docs/ORP_REASONING_KERNEL_PICKUP_PILOT.md — first explicit pickup/handoff proxy across free-form, checklist, and kernel artifacts
• docs/ORP_REASONING_KERNEL_AGENT_PILOT.md — first live fresh-agent Codex recoverability simulation across free-form, checklist, and kernel artifacts
• docs/ORP_REASONING_KERNEL_AGENT_REPLICATION.md — 10-repeat fresh-agent replication study for live kernel recoverability and per-field stability
• docs/ORP_REASONING_KERNEL_CONTINUATION_PILOT.md — first live downstream continuation smoke for kernel, checklist, and free-form artifacts
• docs/ORP_REASONING_KERNEL_CANONICAL_CONTINUATION_PILOT.md — harder live downstream benchmark where the agent must produce the next canonical task artifact
• docs/ORP_REASONING_KERNEL_EVIDENCE_MATRIX.md — honest map of what the kernel proves, only suggests, or still leaves unproven
• docs/ORP_REASONING_KERNEL_EVALUATION_PLAN.md — comparative experiment plan for upgrading kernel evidence beyond implementation validity
• docs/EXTERNAL_CONTRIBUTION_GOVERNANCE.md — canonical local-first workflow for external OSS PR work
• docs/OSS_CONTRIBUTION_AGENT_LOOP.md — agent operating rhythm for external contribution workflows
• templates/ — claim, verification, failure, and issue templates
• examples/ — minimal examples (illustrative, not exhaustive)
• scripts/ — optional helper scripts (no dependencies beyond standard shell tools)
• modules/ — optional modules (including Instruments)
• docs/ — optional docs (including Instruments overview + presentation)
  • includes standardized external PR governance: docs/EXTERNAL_CONTRIBUTION_GOVERNANCE.md
  • includes sunflower-coda PR governance mapping: docs/SUNFLOWER_CODA_PR_GOVERNANCE_MAPPING.md
• cone/ — optional process-only context log (agentic handoff/compaction)
• spec/ — optional v1 runtime draft schemas (packets/config/lifecycle mapping)
• packs/ — optional downloadable profile packs (domain templates + metadata)

Product Shape

ORP should feel like one CLI with built-in abilities:

• workspace for hosted auth, idea, feature, world, checkpoint, and worker operations
• governance for local-first repo initialization, branch safety, checkpoint commits, backup refs, readiness, repair, and cleanup
• discover for profile-based GitHub scanning and opportunity selection
• collaborate for repository collaboration setup and workflow execution
• erdos for Erdos-specific data and workflow support
• report and packet for ORP artifacts

The pack layer still exists, but it is now an advanced/internal surface rather than the main product story.

Install CLI (npm)

Global install:

npm i -g open-research-protocol
orp
orp -h

Prerequisites:

• Python 3 available on PATH
• PyYAML in that Python environment (python3 -m pip install pyyaml)

Fresh-directory smoke test:

mkdir test-orp && cd test-orp
npm i -g open-research-protocol
orp init
orp status --json
orp branch start work/bootstrap --allow-dirty --json
orp checkpoint create -m "bootstrap governance" --json
orp backup -m "backup bootstrap work" --json
orp gate run --profile default
orp checkpoint create -m "capture passing validation" --json
orp ready --json
orp packet emit --profile default
orp report summary
find orp -maxdepth 3 -type f | sort

What this proves:

• the global orp binary resolves,
• running bare orp opens the CLI home screen with packs and quick actions,
• the runtime can initialize a repo-local ORP-governed workspace,
• branch safety and checkpoint mechanics are available locally from day one,
• a gate run writes RUN.json,
• readiness can be marked explicitly after validation plus checkpointing,
• packet emit writes process metadata to orp/packets/,
• and report summary renders a one-page digest from the last run.

Local repo usage still works:

./scripts/orp -h

Agent-first discovery surfaces:

orp
orp home --json
orp about --json
orp auth login
orp whoami --json
orp ideas list --json
orp world bind --idea-id <idea-id> --project-root /abs/path --codex-session-id <session-id> --json
orp checkpoint queue --idea-id <idea-id> --json
orp runner work --once --json
orp runner work --continuous --transport auto --json
orp agent work --once --json   # compatibility alias with legacy checkpoint fallback
orp status --json
orp branch start work/<topic> --json
orp checkpoint create -m "describe completed unit" --json
orp backup -m "backup current work" --json
orp ready --json
orp doctor --json
orp cleanup --json
orp discover profile init --json
orp discover github scan --profile orp.profile.default.json --json
orp collaborate workflows --json
orp collaborate gates --workflow full_flow --json
orp erdos sync --json
orp pack list --json
orp pack install --pack-id erdos-open-problems --json
orp pack fetch --source <git-url> --pack-id <pack-id> --install-target . --json
orp gate run --profile default --json
orp packet emit --profile default --json
orp report summary --json

These surfaces are meant to help automated systems discover ORP quickly:

• bare orp opens a home screen with repo/runtime status, available packs, and next commands
• orp home --json returns the same landing context in machine-readable form
• orp auth ..., orp ideas ..., orp world ..., orp checkpoint ..., orp runner ..., and orp agent ... expose the hosted workspace surface directly through ORP
• orp init, orp status, orp branch start, orp checkpoint create, orp backup, orp ready, orp doctor, and orp cleanup expose the local-first repo governance surface directly through ORP
• orp discover ... exposes profile-based GitHub scanning as a built-in ORP ability
• orp collaborate ... exposes built-in collaboration setup and workflow execution without asking users to think in terms of separate governance packs
• llms.txt gives a concise repo/package map for agents that scan documentation.
• docs/AGENT_LOOP.md gives agents one intended operating rhythm instead of leaving them to invent one.
• docs/DISCOVER.md explains the portable discovery profile model and scan artifacts.
• orp about --json returns machine-readable capability, artifact, schema, and pack metadata.
• Core runtime and pack commands can emit JSON so agents do not need to scrape human text.
• Stable artifact paths make it easy to follow outputs across runs:
• orp/state.json
• orp/artifacts/<run_id>/RUN.json
• orp/artifacts/<run_id>/RUN_SUMMARY.md
• orp/packets/<packet_id>.json
• orp/packets/<packet_id>.md
• orp/discovery/github/<scan_id>/SCAN.json
• orp/discovery/github/<scan_id>/SCAN_SUMMARY.md

Release process:

• docs/NPM_RELEASE_CHECKLIST.md
• docs/ORP_PUBLIC_LAUNCH_CHECKLIST.md
• .github/workflows/npm-publish.yml (publishes on v* tags)

Quick start (existing repo)

1. Copy this folder into your repo (recommended location: orp/).
2. Link to orp/PROTOCOL.md from your repo README.md.
3. Customize Canonical Paths inside orp/PROTOCOL.md to match your repo layout.
4. Run orp init in the repo root to establish ORP governance.
5. Use orp status, orp branch start, orp checkpoint create, and orp backup as the default implementation loop.
6. Use the templates for all new claims and verifications.
7. Optional (agent users): integrate ORP into your agent’s primary instruction file (see orp/AGENT_INTEGRATION.md).

Quick start (new project)

1. Copy this folder into a new project directory.
2. Run orp init immediately so the repo starts ORP-governed.
3. Edit PROTOCOL.md to define your canonical paths and claim labels.
4. Start implementation on a work branch with orp branch start.
5. Create regular checkpoint commits with orp checkpoint create.
6. Use orp backup whenever you want ORP to capture current work to a dedicated remote backup ref.
7. Validate promotable task/decision/hypothesis artifacts with orp kernel validate <path> --json.
8. Start by adding one small claim + verification record using the templates.
9. Optional (agent users): integrate ORP into your agent’s primary instruction file (see AGENT_INTEGRATION.md).

Activation is procedural/social, not runtime: nothing “turns on” automatically. ORP works only if contributors follow it.

Optional Runtime Draft (v1)

ORP remains docs-first by default. For teams that want local gate execution and machine-readable packets, there is an optional v1 draft:

• Overview: docs/ORP_V1_ATOMIC_DISCOVERY_EVOLUTION.md
• Packet schema: spec/v1/packet.schema.json
• Config schema: spec/v1/orp.config.schema.json
• Kernel schema: spec/v1/kernel.schema.json
• Lifecycle mapping: spec/v1/LIFECYCLE_MAPPING.md
• Sunflower atomic profile example: examples/orp.sunflower-coda.atomic.yml
• Kernel starter example: examples/orp.reasoning-kernel.starter.yml

Minimal CLI skeleton:

orp auth login
orp ideas list --json
orp world bind --idea-id <idea-id> --project-root /abs/path --codex-session-id <session-id> --json
orp checkpoint queue --idea-id <idea-id> --json
orp runner work --once --json
orp runner work --continuous --transport auto --json
orp agent work --once --json   # compatibility alias with legacy checkpoint fallback
orp init
orp status --json
orp branch start work/<topic> --json
orp checkpoint create -m "describe completed unit" --json
orp kernel validate analysis/orp.kernel.task.yml --json
orp backup -m "backup current work" --json
orp gate run --profile default
orp ready --json
orp packet emit --profile default
orp report summary --run-id <run_id>
orp erdos sync

Equivalent local-repo commands are available via ./scripts/orp ... when developing ORP itself.

Kernel helper surfaces:

orp kernel scaffold --artifact-class task --out analysis/trace-widget.kernel.yml --json
orp kernel validate analysis/trace-widget.kernel.yml --json

Run summaries are one-page markdown reports generated from RUN.json and intended for fast teammate review:

• what ran,
• what passed/failed,
• where evidence logs live,
• and how reproducible the run is.

Sample summaries:

• examples/reports/sunflower_live_compare_857.RUN_SUMMARY.md
• examples/reports/sunflower_live_compare_20.RUN_SUMMARY.md
• examples/reports/sunflower_live_compare_367.RUN_SUMMARY.md

Optional Profile Packs

ORP supports reusable domain profile packs so core runtime stays general.

The main public collaboration story is now the built-in orp collaborate ... surface. Treat packs as advanced/internal packaging structure unless you are working on ORP itself or installing domain-specific workflows like erdos.

Built-in collaboration quickstart:

orp collaborate init
orp collaborate workflows --json
orp collaborate gates --workflow full_flow --json
orp collaborate run --workflow full_flow --json

• Pack docs: docs/PROFILE_PACKS.md
• Pack metadata schema: spec/v1/profile-pack.schema.json
• Included pack: packs/erdos-open-problems/ (857/20/367 + catalog sync + governance profiles)
• Included pack: packs/external-pr-governance/ (generic external OSS contribution workflow pack)
• Included pack: packs/issue-smashers/ (opinionated external contribution workspace pack built on the same governance ideas)

If you are using ORP normally, prefer:

• orp collaborate ... for collaboration
• orp erdos ... for Erdos work

Reach for orp pack ... when you are doing advanced installs, ORP maintenance, or direct domain-template work.

Install pack configs into a target repo (recommended):

orp pack list

orp pack install \
  --pack-id erdos-open-problems

Fetch an external pack repo and install through CLI (no manual clone flow required):

orp pack fetch \
  --source https://github.com/example/orp-packs.git \
  --pack-id erdos-open-problems \
  --install-target .

This writes rendered configs and a dependency audit report at:

• ./orp.erdos-catalog-sync.yml
• ./orp.erdos-live-compare.yml
• ./orp.erdos-problem857.yml
• ./orp.erdos.pack-install-report.md

Advanced/internal direct install of the Issue Smashers workspace pack:

orp pack install \
  --pack-id issue-smashers

This writes:

• ./orp.issue-smashers.yml
• ./orp.issue-smashers-feedback-hardening.yml
• ./orp.issue-smashers.pack-install-report.md
• ./issue-smashers/ workspace scaffold

The pack is intentionally install-and-adapt:

• it creates the workspace layout and starter docs
• it does not auto-clone target repos
• it keeps governance commands as explicit placeholders until you wire in a repo adapter

By default, install includes starter scaffolding for Problems 857/20/367 so live_compare runs are install-and-go in a fresh repo.

If you want the Problem 857 lane to pull the real public sunflower-lean repo into an empty repo instead of writing starter-only 857 files, use:

orp pack install \
  --pack-id erdos-open-problems \
  --include problem857 \
  --var PROBLEM857_SOURCE_MODE=public_repo \
  --var PROBLEM857_PUBLIC_REPO_URL=https://github.com/SproutSeeds/sunflower-lean

This syncs the public Lean repo into sunflower_lean/ and generates the ORP-owned 857 bridge files (analysis/, docs/, scripts/, and orchestrator/) on top of it.

For public-only adoption (no private sunflower adapters yet):

orp pack install \
  --pack-id erdos-open-problems \
  --include catalog

Clean-room public pack cycle:

orp pack install \
  --pack-id erdos-open-problems \
  --include catalog

orp --config orp.erdos-catalog-sync.yml \
  gate run --profile erdos_catalog_sync_active

orp report summary

This is the simplest end-to-end pack workflow currently validated against the published npm package.

Manual render path (advanced):

python3 scripts/orp-pack-render.py --pack packs/erdos-open-problems --list
python3 scripts/orp-pack-render.py --pack packs/erdos-open-problems --template sunflower_live_compare_suite \
  --var TARGET_REPO_ROOT=/path/to/repo --out /path/to/repo/orp.erdos-live-compare.yml
python3 scripts/orp-pack-render.py --pack packs/erdos-open-problems --template sunflower_mathlib_pr_governance \
  --var TARGET_REPO_ROOT=/path/to/repo --out /path/to/repo/orp.erdos-mathlib-pr-governance.yml
python3 scripts/orp-pack-render.py --pack packs/erdos-open-problems --template erdos_problems_catalog_sync \
  --var TARGET_REPO_ROOT=/path/to/repo --var ORP_REPO_ROOT=/path/to/orp --out /path/to/repo/orp.erdos-catalog-sync.yml