open-research-protocol 0.3.0

package/AGENT_INTEGRATION.md

@@ -0,0 +1,94 @@
+# Agent Integration (Agentic Flow)
+
+If you use an AI agent that reads a **primary instruction Markdown file** (agent-specific; the agent will know the filename),
+integrate ORP by adding an **ORP section** to that file.
+
+This makes ORP the agent’s default operating mode: explicit claim levels, reproducible verification, first-class failed paths,
+and dispute resolution by verification/downgrade (not debate).
+
+## Agent discovery surfaces
+
+Before deeper work, agents can discover ORP through three lightweight entry points:
+
+- `llms.txt` — concise repo/package map for agents that scan docs before acting.
+- `orp about --json` — machine-readable tool metadata, stable artifact paths, schemas, and available packs.
+- `orp pack list --json` — machine-readable inventory of bundled packs.
+- `docs/AGENT_LOOP.md` — canonical ORP operating rhythm for agent-led workflows.
+
+## What to add to your agent’s instruction file
+
+Copy/paste this section into your agent’s main instruction Markdown file:
+
+<!-- ORP:BEGIN -->
+## Open Research Protocol (ORP)
+
+**Non-negotiable boundary:** ORP docs/templates are **process-only** and are **not evidence**. Evidence must live in canonical
+artifact paths (code/data/proofs/logs/papers).
+
+### Default operating rules
+
+- **Always label claims** as one of: **Exact / Verified / Heuristic / Conjecture**.
+- If unsure, **downgrade** rather than overclaim.
+- For **Exact/Verified**: include a **Verification Hook** (commands + expected outputs + determinism notes) and produce a
+  **Verification Record** with **PASS / FAIL / INCONCLUSIVE**.
+- If verification is **FAIL**: **downgrade immediately** and link the failure evidence.
+- Treat **failed paths** as assets: record dead ends as a `Failed Path Record` with the blocking reason/counterexample and a
+  next hook.
+- Resolve disputes by **verification or downgrade**, not argument.
+
+### How to work in an ORP repo
+
+- Before starting: read `PROTOCOL.md` and confirm the project’s **Canonical Paths** are defined.
+- When proposing a result: create/update a claim (via `templates/CLAIM.md`) that points to canonical artifacts (not ORP docs).
+- When verifying: run the hook and write `templates/VERIFICATION_RECORD.md`.
+- When something fails: write `templates/FAILED_TOPIC.md` and link it from the claim/issue.
+
+### Instruments (optional; upstream framing only)
+
+- ORP may include optional Instruments under `modules/instruments/` (e.g., Orbit / Compression / Adversarial).
+- Instruments are **process-only** and must not contain evidence/results. Verification remains blind to instruments.
+- If an Instrument is used, note it in the claim’s **Instrument (optional)** section (name + parameters explored).
+
+### Protocol sync checks (required)
+
+To prevent drift (especially after **context compaction / summarization**), re-check ORP and re-sync this block:
+
+- at **session start** / **new task**,
+- **immediately after any context compaction/summarization**,
+- before publishing any **Verified/Exact** claim,
+- after pulling/updating ORP files in the repo.
+
+Sync procedure:
+1) Find the ORP root directory (the folder containing `PROTOCOL.md`).
+2) Ensure this ORP block matches `<ORP_ROOT>/AGENT_INTEGRATION.md` (between `<!-- ORP:BEGIN -->` and `<!-- ORP:END -->`).
+3) If out of date, sync it (script or manual):
+   - `<ORP_ROOT>/scripts/orp-agent-integrate.sh --sync /path/to/your/agent/instructions.md`
+
+### ORP checkpoint tool (recommended for agent workflows)
+
+Use the checkpoint tool to keep handoffs/compactions honest and to reduce “drift-by-forgetting” before `git commit` / `git push`.
+
+- Command:
+  - `<ORP_ROOT>/scripts/orp-checkpoint.sh --sync --agent-file /path/to/your/agent/instructions.md "checkpoint note"`
+- Recommended moments:
+  - after context compaction/summarization or handoff
+  - before `git commit` / `git push`
+  - before publishing any **Verified/Exact** claim
+
+This writes a process-only entry to `<ORP_ROOT>/cone/CONTEXT_LOG.md` and reports ORP snippet sync status.
+
+<!-- ORP:END -->
+
+## Optional helper script
+
+If you want an automated insert into a file you specify, use:
+
+```sh
+./scripts/orp-agent-integrate.sh --sync /path/to/your/agent/instructions.md
+```
+
+To check for drift (no changes), use:
+
+```sh
+./scripts/orp-agent-integrate.sh --check /path/to/your/agent/instructions.md
+```

package/INSTALL.md

@@ -0,0 +1,159 @@
+# Installing ORP into a repo
+
+ORP supports both:
+
+- docs-first template adoption (`PROTOCOL.md`, templates), and
+- optional runtime CLI usage (`orp`) for gates/packets/packs.
+
+The default runtime story is now:
+
+- `orp discover ...` for profile-based GitHub scanning and opportunity selection
+- `orp collaborate ...` for repository collaboration
+- `orp erdos ...` for Erdos-specific workflows
+- `orp pack ...` only when you need advanced/internal template install behavior
+
+Optional global CLI install:
+
+```sh
+npm i -g open-research-protocol
+orp
+orp -h
+orp about --json
+```
+
+CLI prerequisites:
+
+- Python 3 on `PATH`
+- `PyYAML` (`python3 -m pip install pyyaml`)
+
+Agent-friendly discovery surfaces:
+
+- bare `orp` for the CLI home screen with packs, repo status, and quick actions
+- `orp home --json` for machine-readable landing context
+- `orp discover profile init --json` for a portable discovery profile scaffold
+- `orp discover github scan --profile orp.profile.default.json --json` for ranked GitHub repo/issue/person recommendations
+- `orp collaborate init` for immediate collaboration scaffolding
+- `orp collaborate workflows --json` for built-in collaboration workflow discovery
+- `orp collaborate gates --workflow full_flow --json` for the exact gate chain
+- `llms.txt` for quick repo/package discovery
+- `orp about --json` for machine-readable capabilities, schemas, artifacts, and bundled packs
+- `docs/DISCOVER.md` for the discovery profile model and Coda relationship
+- `docs/AGENT_LOOP.md` for the intended agent operating rhythm
+- `orp pack list --json` for machine-readable bundled pack inventory
+
+Fastest collaboration setup in a fresh repo:
+
+```sh
+orp collaborate init
+orp collaborate workflows --json
+orp collaborate run --workflow full_flow --json
+```
+
+This uses ORP's built-in collaboration ability. You do not need to think in
+terms of separate governance packs for the default collaboration path.
+
+To choose where collaboration should start, scaffold a profile first:
+
+```sh
+orp discover profile init --owner SproutSeeds --owner-type org
+orp discover github scan --profile orp.profile.default.json --json
+```
+
+## Option 0 — Smoke-test ORP in a fresh directory
+
+This is the fastest way to verify the published CLI before integrating ORP into a real repo.
+
+```sh
+mkdir test-orp && cd test-orp
+npm i -g open-research-protocol
+orp init
+orp gate run --profile default
+orp packet emit --profile default
+orp report summary
+find orp -maxdepth 3 -type f | sort
+```
+
+Expected outcomes:
+
+- `orp.yml` is created in the working directory
+- `orp/artifacts/<run_id>/RUN.json` is written after `gate run`
+- `orp/packets/*.json` and `orp/packets/*.md` are written after `packet emit`
+- `orp/artifacts/<run_id>/RUN_SUMMARY.md` is written after `report summary`
+
+Then validate a real public pack flow:
+
+```sh
+orp pack list
+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 exercises the published pack install path plus a real pack-backed gate run.
+
+## Option A — Add ORP to an existing repo
+
+1) Copy the folder into your repo (recommended: `orp/`):
+
+```sh
+mkdir -p /path/to/your/repo/orp
+cp -R /path/to/orp/* /path/to/your/repo/orp/
+```
+
+2) Link it from your repo `README.md` (example):
+
+```md
+## Protocol
+This project follows ORP: `orp/PROTOCOL.md`.
+```
+
+3) Edit `orp/PROTOCOL.md` and fill in the **Canonical Paths** section for your repo. This is required for correctness.
+
+4) Start using templates for all claims/verifications:
+- `orp/templates/CLAIM.md`
+- `orp/templates/VERIFICATION_RECORD.md`
+- `orp/templates/FAILED_TOPIC.md`
+
+5) Optional (agent users): integrate ORP into your agent’s primary instruction file:
+- Read `orp/AGENT_INTEGRATION.md`
+- Or run: `orp/scripts/orp-agent-integrate.sh --sync /path/to/your/agent/instructions.md`
+   - Optional checkpoint tool (writes a process-only handoff/compaction log): `orp/scripts/orp-checkpoint.sh --sync --agent-file /path/to/your/agent/instructions.md "checkpoint note"`
+
+## Option B — Start a new project from ORP
+
+1) Create a new project directory and copy ORP in:
+
+```sh
+mkdir -p /path/to/new-project
+cp -R /path/to/orp/* /path/to/new-project/
+```
+
+2) Rename/edit `README.md` and `PROTOCOL.md` for your project.
+
+3) Define canonical paths (paper/code/data/etc) in `PROTOCOL.md`.
+
+4) Optional (agent users): integrate ORP into your agent’s primary instruction file:
+- Read `AGENT_INTEGRATION.md`
+- Or run: `scripts/orp-agent-integrate.sh --sync /path/to/your/agent/instructions.md`
+   - Optional checkpoint tool (writes a process-only handoff/compaction log): `scripts/orp-checkpoint.sh --sync --agent-file /path/to/your/agent/instructions.md "checkpoint note"`
+
+## Optional helper script
+
+If you want a guided copy:
+
+```sh
+./scripts/orp-init.sh /path/to/your/repo/orp
+```
+
+If you are evaluating ORP for the first time, prefer Option 0 before copying files into a larger repo.
+
+## Important note: “activation”
+
+ORP becomes real only when your team adopts the procedure:
+
+- claims must be labeled,
+- Exact/Verified claims must have verification hooks,
+- disagreements are resolved by verification or downgrade,
+- and failures are recorded as first-class artifacts.
+
+There is no automated enforcement unless you add it (CI hooks, PR checks, etc.).

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 SproutSeeds
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/PROTOCOL.md

@@ -0,0 +1,140 @@
+# Project Protocol (ORP)
+**Last updated:** 2026-01-21
+
+ORP is a **process-only** protocol for producing trustworthy results.
+
+**Boundary (non-negotiable):** This document and all ORP templates are **not evidence**. They must not be cited as proof for
+results. Evidence must live in your project’s **canonical artifact paths** (code, data, logs, proofs, papers, etc.).
+
+---
+
+## Canonical Paths (Source of Truth)
+
+Every project must define, in concrete paths, where authoritative artifacts live. Edit this list for your repo:
+
+- **Paper/spec (if any):** `paper/`
+- **Code:** `src/` (or `core/`, etc.)
+- **Analysis/experiments:** `analysis/`
+- **Data/artifacts:** `data/`
+- **Formal proofs (optional):** `proof/` / `lean/` / `coq/`
+- **Runbooks/logs (optional):** `runbooks/` / `logs/`
+
+Rule: **All claims must point to canonical artifacts.** If a claim cannot be tied to a canonical artifact, it is not a claim yet.
+
+---
+
+## Claim Levels
+
+All claims must be labeled as exactly one of:
+
+- **Exact** — proven/certified; independently reproducible with explicit commands and artifacts.
+- **Verified** — confirmed for a specific artifact (e.g., a construction, dataset, or run) but not claimed optimal/universal.
+- **Heuristic** — strong evidence, not exhaustive.
+- **Conjecture** — hypothesis / model / pattern; explicitly unproven.
+
+Default rule: **When unsure, downgrade.**
+
+---
+
+## Artifact Requirements (Minimum)
+
+### Exact claims
+Must include a verification hook that another person can run:
+
+- precise command(s),
+- inputs (paths, versions),
+- outputs (logs, certificates, checksums),
+- and a verification record showing PASS.
+
+### Verified claims
+Must include:
+
+- the artifact (data/model/etc),
+- a verifier script or deterministic procedure,
+- and a verification record showing PASS.
+
+### Heuristic / Conjecture
+Must include:
+
+- scope and limitations,
+- what would upgrade it to Verified/Exact,
+- and at least one concrete next hook.
+
+---
+
+## Verification Records (Required for Exact/Verified)
+
+Use `templates/VERIFICATION_RECORD.md`.
+
+**Default dispute action:**
+- If verification is **FAIL** → downgrade the claim level immediately.
+- If verification is **INCONCLUSIVE** → downgrade by default (or keep the original label but add an explicit “blocked by X” note).
+
+---
+
+## Dispute Workflow (Verifier-first)
+
+If two contributors disagree:
+
+1) The claim owner provides canonical artifacts + commands.
+2) A verifier attempts reproduction and writes a verification record.
+3) Outcomes:
+   - PASS → claim stands at its label.
+   - FAIL → claim is downgraded (and linked to the failure record).
+   - INCONCLUSIVE → downgrade by default; open a follow-up issue.
+
+Disputes must resolve via **verification or downgrade**, not argument.
+
+---
+
+## Failed Paths (First-class artifacts)
+
+Failures are valuable when they prevent repeated work.
+
+Use `templates/FAILED_TOPIC.md` to record:
+
+- what was tried,
+- what failed and why,
+- the minimal counterexample / blocking reason,
+- and a “next hook” for future attempts.
+
+Suggested naming convention:
+
+- `analysis/FAILED_<topic>.md` (or your repo’s canonical analysis area)
+
+---
+
+## Alignment / Polish Log (Non-blocking; Append-only)
+
+When a verification/audit **PASSES** but yields optional suggestions (wording, clarity, alignment),
+record them in an append-only log (recommended path):
+
+- `analysis/ALIGNMENT_LOG.md`
+
+Rules:
+- Non-authoritative; non-blocking.
+- Must not upgrade claims.
+- Must not be cited as evidence.
+
+---
+
+## Roles (Optional, but recommended)
+
+This protocol supports role separation:
+
+- **Explorer** — proposes claims, builds artifacts.
+- **Verifier** — reproduces/checks claims; can downgrade labels.
+- **Synthesizer** — integrates results into shared structure without introducing new claims.
+
+No maintainer tie-break is required if verification hooks exist and downgrade rules are followed.
+
+---
+
+## Contribution Workflow (default)
+
+If unsure where something belongs, record it at a lower claim level and let verification decide.
+
+1) Write a claim using `templates/CLAIM.md` and put the real content in canonical paths.
+2) Run verification and write `templates/VERIFICATION_RECORD.md`.
+3) Only then update any shared docs (paper/README) with language matching the claim level.
+4) If something fails, record it with `templates/FAILED_TOPIC.md`.