open-research-protocol 0.3.0

package/cone/CONTEXT_LOG.md

@@ -0,0 +1,33 @@
+# Context Log (process-only; not evidence)
+
+> This file is **not evidence**. It is a running, lightweight trace of “what’s going on” to support handoff, compaction, and
+> coordination.
+>
+> Keep entries neutral: hypotheses, decisions, links, next hooks. Avoid “proving” anything here.
+
+---
+
+## How to use
+
+- Add an entry at major transitions:
+  - after context compaction/summarization
+  - before `git commit` / `git push` (optional but recommended for agentic workflows)
+  - before publishing a **Verified/Exact** claim
+  - at handoff (“here’s the state; here’s next”)
+- Prefer links to canonical artifacts (code/data/logs) rather than reproducing content here.
+
+---
+
+## Entry template
+
+### Checkpoint — YYYY-MM-DDTHH:MM:SSZ
+- Note:
+- Repo state:
+  - Branch:
+  - Head:
+  - Git status: staged=?, unstaged=?, untracked=?
+- ORP snippet sync:
+  - Agent instruction files checked:
+  - Result: PASS / FAIL / (skipped)
+- Canonical artifacts touched (paths only):
+- Next hook:

package/docs/AGENT_LOOP.md

@@ -0,0 +1,63 @@
+# ORP Agent Loop
+
+Use this loop when an AI agent is the primary operator of an ORP-enabled repo.
+
+## 1. Discover
+
+- Read `llms.txt`.
+- Run `orp about --json`.
+- If packs matter, run `orp pack list --json`.
+- Read `PROTOCOL.md` before making claims.
+- If the task is external OSS contribution workflow or PR governance, read
+  `docs/EXTERNAL_CONTRIBUTION_GOVERNANCE.md` before selecting work.
+- For the more detailed external-contribution operator rhythm, then read
+  `docs/OSS_CONTRIBUTION_AGENT_LOOP.md`.
+
+## 2. Select Work
+
+- Identify the target profile and canonical artifact paths.
+- If a pack-backed workflow needs setup, run:
+  - `orp pack install --pack-id <pack-id> --json`
+  - or `orp pack fetch --source <git-url> --pack-id <pack-id> --install-target . --json`
+- If the workflow depends on public Erdos data, sync it first:
+  - `orp erdos sync --problem-id <id> --out-problem-dir <dir> --json`
+
+## 3. Run
+
+- Execute the target workflow:
+  - `orp gate run --profile <profile> --json`
+- Treat the resulting `run_id` as the handle for follow-on steps.
+
+## 4. Emit Process Metadata
+
+- Write the packet:
+  - `orp packet emit --profile <profile> --run-id <run_id> --json`
+- Packets are process metadata only. They are not evidence.
+
+## 5. Render Human Review Output
+
+- Write the one-page digest:
+  - `orp report summary --run-id <run_id> --json`
+- Share the generated `RUN_SUMMARY.md` with humans when a fast review artifact is useful.
+- Read `RUN.json.epistemic_status` and packet `evidence_status` before making any claim about what counts as evidence versus starter scaffolding.
+
+## 6. Checkpoint
+
+- Before handoff, compaction, `git commit`, or `git push`, write a checkpoint:
+  - `scripts/orp-checkpoint.sh --sync --agent-file /path/to/agent/instructions.md "checkpoint note"`
+
+## 7. Respect the Boundary
+
+- ORP docs, packets, and summaries are process artifacts.
+- Evidence must remain in canonical artifact paths such as code, data, proofs, logs, and papers.
+- If verification fails, downgrade the claim immediately and preserve the failed path.
+
+## Minimal Public Example
+
+```sh
+orp about --json
+orp pack install --pack-id erdos-open-problems --include catalog --json
+orp --config orp.erdos-catalog-sync.yml gate run --profile erdos_catalog_sync_active --json
+orp --config orp.erdos-catalog-sync.yml packet emit --profile erdos_catalog_sync_active --json
+orp --config orp.erdos-catalog-sync.yml report summary --json
+```

package/docs/CHOOSING_OR_IGNORING_INSTRUMENTS.md

@@ -0,0 +1,128 @@
+# Choosing (or Ignoring) Instruments
+
+> *Instruments are available, not required.*
+
+This document explains **when to use an instrument**, **when not to**, and shows a small example of both paths. The goal is clarity without pressure.
+
+---
+
+## The Short Rule
+
+You do **not** need an instrument to use ORP.
+
+ORP functions fully with:
+- clear claims
+- explicit verification hooks
+- honest downgrade or failure recording
+
+Instruments are optional tools for **upstream framing**, nothing more.
+
+---
+
+## When an Instrument Helps
+
+Consider using an instrument if:
+
+- the problem feels large, vague, or multidimensional
+- you are unsure what to measure first
+- competing intuitions are pulling in different directions
+- you want to generate *predictions* before making claims
+
+An instrument helps you choose *where to stand* before you speak.
+
+---
+
+## When to Ignore Instruments
+
+It is often better to skip instruments when:
+
+- the claim is narrow and well-defined
+- the verification method is obvious
+- you are extending known work incrementally
+- speed matters more than framing
+
+Skipping instruments is not a shortcut.
+It is a valid choice.
+
+---
+
+## How to Choose an Instrument (If You Do)
+
+Ask one simple question:
+
+> *What kind of uncertainty am I facing?*
+
+Then choose accordingly:
+
+- **Orbit Lens** → uncertainty about *stability, balance, or persistence*
+- **Compression Lens** → uncertainty about *what really matters*
+- **Adversarial Lens** → uncertainty about *hidden failure modes*
+
+You may use more than one — or none.
+
+---
+
+## Tiny Example A: Using an Instrument
+
+**Context:** Studying a large combinatorial family suspected to be extremal.
+
+Before making a claim, you apply the **Orbit Lens**:
+- forces: structure vs entropy
+- distance knob: density of the family
+- invariant: collision count under projection
+
+**Result:**
+You predict that beyond a certain density, collisions must explode.
+
+**Then:**
+You write a claim in ORP:
+> *Claim:* Any family exceeding density X contains a forbidden configuration.
+>
+> *Instrument used:* Orbit Lens (density regime)
+>
+> *Verification:* SAT search + counting argument
+
+Verification proceeds normally.
+The instrument does not affect acceptance.
+
+---
+
+## Tiny Example B: Ignoring Instruments
+
+**Context:** Checking whether a specific bound holds for n ≤ 10.
+
+You already know:
+- what to compute
+- how to verify it
+
+You write a claim directly:
+> *Claim:* Bound Y holds for all n ≤ 10.
+>
+> *Verification:* Exhaustive computation
+
+No instrument is referenced.
+This is fully valid ORP usage.
+
+---
+
+## Important Boundary
+
+Instruments:
+- influence *what questions are asked*
+- never influence *whether a claim is accepted*
+
+Verification is blind to framing.
+
+---
+
+## Final Reassurance
+
+If you:
+- never use an instrument, ORP still works
+- use one instrument, ORP still works
+- invent a new instrument, ORP still works
+
+Instruments are an invitation, not an obligation.
+
+*Use them when they help. Ignore them when they don’t.*
+

package/docs/CODA_ORP_CONTRACT.md

@@ -0,0 +1,222 @@
+# Coda to ORP Contract
+
+This document defines the boundary between:
+
+- `codacli.com` / `coda-cli`
+- `ORP`
+
+The goal is to let both systems work together without turning ORP into an app
+backend or turning Coda into a second protocol runtime.
+
+## Repository Split
+
+Recommended shape:
+
+- `orp` repo
+  - protocol/runtime
+  - discovery execution
+  - collaboration execution
+  - packets, run records, summaries
+  - portable local-first CLI
+- `coda-cli` repo
+  - operator-facing wrapper
+  - active profile selection
+  - auth/session handling
+  - Coda export retrieval
+  - convenience commands layered over ORP
+- `codacli.com`
+  - authenticated web product
+  - user database
+  - idea cards
+  - feature scaffolds
+  - notes/detail sections
+  - export surface for agents and `coda-cli`
+
+## Ownership Boundary
+
+Coda owns:
+
+- user identity
+- database records
+- idea cards
+- categories
+- feature scaffolds
+- note/detail sections
+- active context selection
+- export APIs / export files
+
+ORP owns:
+
+- portable discovery profile format
+- GitHub discovery scans
+- collaboration workflows
+- gate execution
+- packets
+- run summaries
+- process artifacts
+
+In short:
+
+- Coda answers: "What does this user care about right now?"
+- ORP answers: "How do we discover, structure, and execute the work?"
+
+## MVP Rule
+
+The MVP should be read-only from Coda into ORP.
+
+That means:
+
+- Coda exports context
+- ORP consumes derived context
+- ORP produces scan/run artifacts
+- Coda may read those artifacts later
+- ORP does not write back into Coda yet
+
+This keeps the first integration simple and auditable.
+
+## Canonical Coda Export
+
+Coda should expose a canonical export that reflects the app's richer data
+model.
+
+Example shape:
+
+```json
+{
+  "schema_version": "1.0.0",
+  "user": {
+    "id": "user_123",
+    "handle": "cody"
+  },
+  "active_context": {
+    "idea_id": "idea_problem857",
+    "title": "Sunflower formalization work",
+    "categories": ["math", "lean", "formalization"]
+  },
+  "ideas": [
+    {
+      "id": "idea_problem857",
+      "title": "Sunflower formalization work",
+      "summary": "Look for repos and issues aligned with Problem 857 work.",
+      "tags": ["sunflower", "lean", "proof"],
+      "feature_scaffold": {
+        "areas": ["balance", "container", "docs"],
+        "notes": ["Prefer public repos first."]
+      }
+    }
+  ]
+}
+```
+
+ORP should not depend directly on the full Coda export schema.
+
+## Derived ORP Inputs
+
+`coda-cli` should derive smaller ORP-native inputs from the richer Coda export.
+
+The first derived input is an ORP discovery profile.
+
+Example:
+
+```json
+{
+  "schema_version": "1.0.0",
+  "profile_id": "idea_problem857",
+  "notes": [
+    "Derived from Coda active context."
+  ],
+  "discover": {
+    "github": {
+      "owner": {
+        "login": "SproutSeeds",
+        "type": "org"
+      },
+      "signals": {
+        "keywords": ["sunflower", "formalization", "proof"],
+        "repo_topics": ["lean", "math"],
+        "languages": ["Lean"],
+        "areas": ["balance", "container", "docs"],
+        "people": []
+      },
+      "filters": {
+        "include_repos": [],
+        "exclude_repos": [],
+        "issue_states": ["open"],
+        "labels_any": [],
+        "exclude_labels": [],
+        "updated_within_days": 180
+      },
+      "ranking": {
+        "repo_sample_size": 30,
+        "max_repos": 12,
+        "max_issues": 24,
+        "max_people": 12,
+        "issues_per_repo": 30
+      }
+    }
+  }
+}
+```
+
+Other future derived inputs may include:
+
+- collaboration bootstrap hints
+- target repo selection
+- issue lane selection
+- preferred adapters
+
+## ORP Outputs Coda May Read
+
+For the first integration, Coda should treat ORP outputs as read-only runtime
+artifacts.
+
+Useful outputs:
+
+- `orp/discovery/github/<scan_id>/SCAN.json`
+- `orp/discovery/github/<scan_id>/SCAN_SUMMARY.md`
+- `orp/artifacts/<run_id>/RUN.json`
+- `orp/artifacts/<run_id>/RUN_SUMMARY.md`
+- `orp/packets/<packet_id>.json`
+
+These let Coda display:
+
+- recommended repos/issues/people
+- latest collaboration run results
+- packetized process context
+
+## CLI Relationship
+
+`coda-cli` should be a thin wrapper over ORP, not a second workflow engine.
+
+Good examples:
+
+- `coda profile export`
+- `coda profile use <idea-id>`
+- `coda discover`
+- `coda collaborate init`
+
+Under the hood, those should call ORP's JSON surfaces such as:
+
+- `orp discover profile init --json`
+- `orp discover github scan --json`
+- `orp collaborate init --json`
+- `orp collaborate run --json`
+
+## Non-Goals For ORP
+
+ORP should not own:
+
+- authenticated user databases
+- profile sharing semantics
+- team/private visibility policy
+- app-level note editing
+- direct mutation of Coda records
+
+Those belong in Coda.
+
+## Practical Rule
+
+When in doubt:
+
+- if it is portable execution or protocol data, keep it in ORP
+- if it is user/app context or authenticated product state, keep it in Coda

package/docs/CORE_ABILITY_REFOCUS_CHECKLIST.md

@@ -0,0 +1,62 @@
+# ORP Core Ability Refocus Checklist
+
+This checklist tracks the shift from a pack-first public story to an
+ability-first ORP CLI.
+
+## Product Shape
+
+- [x] Discovery is presented as a built-in ORP ability.
+- [x] Bare `orp` opens a home screen instead of only failing on missing
+  subcommands.
+- [x] Collaboration is presented as a built-in ORP ability.
+- [x] `erdos` remains a domain-specific ORP ability.
+- [x] Packs remain available for advanced/internal use.
+- [ ] The released npm package includes the new collaboration-first surface.
+
+## Default User Story
+
+- [x] `orp discover profile init` scaffolds a portable discovery profile.
+- [x] `orp discover github scan` ranks repo, issue, and people opportunities
+  inside a GitHub owner space.
+- [x] `orp collaborate init` is the fastest collaboration setup path.
+- [x] `orp collaborate workflows` exposes built-in collaboration workflows.
+- [x] `orp collaborate gates --workflow <id>` shows the gate chain before a run.
+- [x] `orp collaborate run --workflow <id>` runs the built-in collaboration
+  workflow.
+- [x] README points users at `orp collaborate ...` first.
+- [x] INSTALL points users at `orp collaborate ...` first.
+- [ ] Add a collaboration-specific summary/example doc if real users still need
+  more onboarding.
+
+## Advanced / Internal Story
+
+- [x] `pack` is still available.
+- [x] Home screen labels packs as advanced bundles.
+- [x] Pack docs remain available for ORP maintainers and advanced users.
+- [ ] Decide later whether `external-pr-governance` and `issue-smashers` stay
+  as visible internal names or become more hidden implementation details.
+
+## Machine-Readable Discovery
+
+- [x] `orp home --json` exists.
+- [x] `orp about --json` exists.
+- [x] `orp about --json` exposes commands.
+- [x] `orp about --json` exposes abilities.
+- [x] `orp discover ... --json` exists.
+- [x] `orp collaborate workflows --json` exists.
+- [x] `orp collaborate gates --json` exists.
+- [ ] Add a machine-readable examples surface if agents still need more direct
+  task discovery.
+
+## Domain Shape
+
+- [x] Collaboration is part of ORP core UX.
+- [x] Erdos stays separate.
+- [ ] Decide whether `erdos` should gain a matching `workflows` / `run`
+  surface for symmetry with `collaborate`.
+
+## Release Checklist
+
+- [ ] Commit the collaboration-first refocus.
+- [ ] Release the next npm version.
+- [ ] Validate the collaboration-first story from a clean published install.

package/docs/DISCOVER.md

@@ -0,0 +1,69 @@
+# ORP Discover
+
+`orp discover` is ORP's built-in discovery ability for finding promising work
+inside a GitHub owner space.
+
+The first concrete surface is a GitHub profile scanner:
+
+- scaffold a discovery profile
+- define keywords, languages, topics, areas, and people signals
+- scan a GitHub user or organization
+- rank repositories, issues, and active people
+- hand off the strongest match into `orp collaborate`
+
+Today ORP scans public GitHub owner space by default. If richer access policy
+or profile governance exists later, that belongs in Coda rather than in ORP.
+
+## Commands
+
+Scaffold a profile:
+
+```bash
+orp discover profile init --owner SproutSeeds --owner-type org --json
+```
+
+Run a scan:
+
+```bash
+orp discover github scan --profile orp.profile.default.json --json
+```
+
+## Profile Model
+
+Discovery profiles are portable JSON files owned by ORP.
+
+Current profile fields let you shape:
+
+- GitHub owner scope
+- keywords
+- repo topics
+- languages
+- area terms
+- people signals
+- repo and issue filters
+- ranking limits
+
+## Artifacts
+
+GitHub scans write:
+
+- `orp/discovery/github/<scan_id>/SCAN.json`
+- `orp/discovery/github/<scan_id>/SCAN_SUMMARY.md`
+
+These are process-only recommendation artifacts, not evidence.
+
+## Coda Relationship
+
+ORP should own the portable discovery profile format and the scanning
+artifacts.
+
+If `coda-cli` exists later, the clean role for Coda is:
+
+- manage active profiles
+- switch between operator contexts
+- wrap ORP commands for a smoother operator UX
+
+That keeps ORP as the protocol/runtime while letting Coda become a higher-level
+profile manager if it earns its place.
+
+For the fuller boundary, see `docs/CODA_ORP_CONTRACT.md`.