open-research-protocol 0.3.0

package/modules/instruments/ADVERSARIAL/TEMPLATE.md

@@ -0,0 +1,27 @@
+# Adversarial Lens — Template
+
+## Purpose
+- What must be robust, and why?
+
+## Forces
+- Inward force (coherence/confidence):
+- Outward force (attack/perturbation):
+
+## Distance / Control Parameters
+- Adversary strength / perturbation budget:
+
+## Stability Invariants
+- What should remain true under stress?
+
+## Failure Signals
+- What would count as a decisive break?
+
+## Reframing Moves
+- What counterexample or quantifier flip helps?
+
+## Observation Test
+- What new robustness bound or minimal counterexample would count?
+
+## Notes
+- (Optional) worst-case scenario:
+

package/modules/instruments/COMPRESSION/README.md

@@ -0,0 +1,112 @@
+# Compression Lens
+
+> *What survives compression is structure. What vanishes was noise.*
+
+The Compression Lens reframes inquiry by asking not whether a system works, but **what remains invariant when description length is reduced**.
+
+This instrument is orthogonal to Orbit.
+Where Orbit studies balance under motion, Compression studies **essence under reduction**.
+
+---
+
+## Purpose
+
+Use the Compression Lens when:
+- a system feels complex or over-parameterized,
+- multiple explanations exist,
+- or you suspect hidden structure beneath surface variability.
+
+---
+
+## Forces
+
+- **Inward force:** compression, minimal description, parsimony.
+- **Outward force:** expressiveness, redundancy, flexibility.
+
+Too much compression destroys meaning.
+Too little compression hides it.
+
+---
+
+## Distance / Control Parameters
+
+- Compression strength
+- Description length budget
+- Number of retained generators / features
+- Allowed approximation error
+
+This lens tunes *how aggressively* information is discarded.
+
+---
+
+## Stability Invariants
+
+Quantities that should persist under healthy compression:
+
+- core generators
+- invariant statistics
+- minimal counterexamples
+- structural symmetries
+
+If these disappear, compression is too strong.
+
+---
+
+## Failure Signals
+
+- conclusions change wildly with small compression changes
+- different compressions yield incompatible cores
+- essential behavior vanishes early
+
+These signal loss of meaning, not discovery.
+
+---
+
+## Reframing Moves
+
+- project onto minimal generating sets
+- replace objects with summaries
+- identify equivalence classes
+- measure description length explicitly
+
+Change the question from:
+> “Does this hold?”
+
+to:
+> “What cannot be compressed away?”
+
+---
+
+## Observation Test
+
+A new observation under the Compression Lens:
+
+- identifies a minimal invariant
+- shows two phenomena compress to the same core
+- proves a lower bound on description length
+
+If compression clarifies rather than obscures, the lens is valid.
+
+---
+
+## Relation to Orbit
+
+Orbit asks:
+> Can this system persist under opposing forces?
+
+Compression asks:
+> What must exist for persistence to be possible at all?
+
+Together, they form a cone of vision:
+- Orbit controls *trajectory*
+- Compression reveals *essence*
+
+---
+
+## Closing
+
+Compression is not simplification.
+It is respect for what cannot be removed.
+
+*If it survives compression, it deserves explanation.*
+

package/modules/instruments/COMPRESSION/TEMPLATE.md

@@ -0,0 +1,27 @@
+# Compression Lens — Template
+
+## Purpose
+- What is being clarified by compression?
+
+## Forces
+- Inward force (compression/parsimony):
+- Outward force (expressiveness/redundancy):
+
+## Distance / Control Parameters
+- Compression knobs / budgets:
+
+## Stability Invariants
+- What should survive reduction?
+
+## Failure Signals
+- What changes mean we over-compressed?
+
+## Reframing Moves
+- What representation or generator set helps?
+
+## Observation Test
+- What new invariant / equivalence / lower bound would count?
+
+## Notes
+- (Optional) minimal core found:
+

package/modules/instruments/INSTRUMENT_TEMPLATE.md

@@ -0,0 +1,30 @@
+# ORP Instrument — Template (process-only)
+
+> Constraint: no evidence, no results, no conclusions.
+
+## Name
+
+## Purpose
+- What kinds of systems/questions does this instrument help with?
+
+## Forces
+- What competing pressures does it highlight?
+
+## Distance / Control Parameters
+- What knobs can be tuned?
+
+## Stability Invariants
+- What quantities indicate persistence/health?
+
+## Failure Signals
+- What patterns indicate collapse or invalid framing?
+
+## Reframing Moves
+- How does this instrument change perspective?
+
+## Observation Test
+- What would count as a *new observation* using this instrument?
+
+## Notes
+- (Optional) predicted boundary / corridor:
+

package/modules/instruments/ORBIT/README.md

@@ -0,0 +1,124 @@
+# ORBIT: a Universal Research Lens
+
+> *Stability is not stillness. It is sustained motion under opposing forces.*
+
+This lens is a way to step out of default binaries and into dynamics. It does not try to control systems or collapse them into endpoints. It asks how systems **persist**, how they **fail**, and how meaning emerges from **balanced motion**.
+
+Use this lens before proofs, before models, before decisions.
+
+---
+
+## 1) Forces
+**Question:** What pulls the system inward, and what pushes it outward?
+
+Identify the two dominant pressures that cannot both be maximized at once.
+
+- **Inward force** (structure): constraints, rigidity, shared core, determinism, compression.
+- **Outward force** (entropy): freedom, variability, randomness, expansion, exploration.
+
+**Rule:** If one force wins outright, the system collapses.
+
+---
+
+## 2) Extremes (Failure Modes)
+**Question:** What breaks when we go too far in either direction?
+
+- **Too close** (over-structure): brittleness, collapse, triviality, burnout.
+- **Too far** (over-entropy): incoherence, collisions, noise, meaninglessness.
+
+**Rule:** Extremes are not solutions; they are diagnostic boundaries.
+
+---
+
+## 3) Distance (The Orbit Radius)
+**Question:** What parameter controls closeness to either extreme?
+
+This is the knob you can tune.
+
+Examples:
+- Density / scale
+- Degree imbalance
+- Step size / learning rate
+- Projection depth / conditioning
+- Time horizon
+
+**Rule:** Distance is adjustable. The system survives by tuning, not fixing.
+
+---
+
+## 4) Stability Invariant
+**Question:** What quantity stays bounded when the system is healthy?
+
+Choose an invariant that:
+- is measurable,
+- reacts smoothly to distance,
+- and blows up near failure.
+
+Examples:
+- Collision count
+- Energy / potential
+- Entropy under constraint
+- Error under perturbation
+
+**Rule:** Stability is what persists under motion.
+
+---
+
+## 5) Instability Signals
+**Question:** How does failure announce itself?
+
+Watch for:
+- sudden growth in collisions or conflicts
+- runaway rigidity (forced variables, frozen cores)
+- loss of sensitivity (everything looks the same)
+
+**Rule:** Instability is not subtle. It accelerates.
+
+---
+
+## 6) Reframing (Change Coordinates)
+**Question:** What happens if we change perspective?
+
+Instead of forcing control, **switch frames**:
+- condition on a coordinate
+- project onto a lower dimension
+- sample a slice or biased measure
+- slow down or zoom out
+
+**Rule:** Choose a frame where chaos becomes measurable and structure becomes unavoidable.
+
+---
+
+## 7) Observation Test
+**Question:** What would count as a *new observation* in this frame?
+
+A good observation:
+- predicts a boundary,
+- explains why extremes fail,
+- or identifies a narrow corridor of persistence.
+
+**Rule:** If the lens produces predictions, it belongs in science.
+
+---
+
+## 8) Docking Principle
+This lens is portable.
+
+Apply it when (and only when) a problem presents:
+- competing forces,
+- a tunable distance,
+- and a question about persistence.
+
+If it fits, it will **snap into place**.
+
+If it doesn’t, keep orbiting.
+
+---
+
+## Closing
+Meaning is not found at the center.
+It is built by holding a trajectory long enough to create coherence.
+
+*Orbit is not avoidance.
+Orbit is precision.*
+

package/modules/instruments/ORBIT/TEMPLATE.md

@@ -0,0 +1,28 @@
+# Orbit Lens — Template
+
+## Forces
+- Inward force (structure):
+- Outward force (entropy):
+
+## Extremes (Failure Modes)
+- Too close (over-structure):
+- Too far (over-entropy):
+
+## Distance (Orbit Radius)
+- Tunable parameter(s) / knobs:
+
+## Stability Invariant
+- What stays bounded when healthy?
+
+## Instability Signals
+- What indicates collapse?
+
+## Reframing (Change Coordinates)
+- What frame-switch helps?
+
+## Observation Test
+- What would count as a new observation?
+
+## Notes
+- (Optional) predicted boundary / corridor:
+

package/modules/instruments/README.md

@@ -0,0 +1,179 @@
+# ORP Instruments Framework
+
+> *Truth does not emerge from a single lens. It emerges from well-governed interaction between lenses.*
+
+This document defines **what an Instrument is**, **how Instruments integrate with ORP**, and **how anyone can create one**. Orbit is the first instrument — not the only one.
+
+---
+
+## Quick links
+
+- Orbit: `modules/instruments/ORBIT/README.md` · `modules/instruments/ORBIT/TEMPLATE.md`
+- Compression: `modules/instruments/COMPRESSION/README.md` · `modules/instruments/COMPRESSION/TEMPLATE.md`
+- Adversarial: `modules/instruments/ADVERSARIAL/README.md` · `modules/instruments/ADVERSARIAL/TEMPLATE.md`
+- Create a new instrument: `modules/instruments/INSTRUMENT_TEMPLATE.md`
+
+## 1) What We Are Building (Plainly)
+
+ORP is a protocol for **truth under pressure**.
+
+It governs:
+- how claims are stated,
+- how verification is attached,
+- how failures are recorded,
+- how disagreement resolves via evidence, not argument.
+
+**Instruments live upstream of this.**
+
+An Instrument is a *framing tool* that helps generate better questions, sharper claims, and testable predictions *before* ORP governance begins.
+
+ORP does **not** judge instruments.
+ORP only governs what happens *after* an instrument is used.
+
+---
+
+## 2) Definition: ORP Instrument
+
+An **ORP Instrument** is a modular, process-only artifact that:
+
+- operates **pre-claim**
+- introduces a **reference frame** for inquiry
+- identifies **forces, parameters, and invariants**
+- produces **testable observations or predictions**
+- never contains evidence or conclusions
+
+An instrument may influence *what claims are made*, but never *how they are verified*.
+
+---
+
+## 3) Non-Negotiable Constraints (Why This Works)
+
+Every ORP Instrument must satisfy:
+
+1. **Process-only**  
+   No data, no results, no conclusions.
+
+2. **Non-authoritative**  
+   Instruments do not override claims or verification.
+
+3. **Composable**  
+   Multiple instruments may be applied to the same inquiry.
+
+4. **Discardable**  
+   Instruments may be abandoned without loss of truth.
+
+5. **Prediction-generating**  
+   Must lead to statements that can be verified or falsified downstream.
+
+These constraints prevent ideology, lock-in, or protocol drift.
+
+---
+
+## 4) The Instrument Contract (Template Spec)
+
+Every instrument should answer the following:
+
+### A) Purpose
+What kind of systems or questions does this instrument help with?
+
+### B) Forces
+What competing pressures does this instrument highlight?
+
+### C) Distance / Control Parameters
+What knobs can be tuned?
+
+### D) Stability Invariants
+What quantities indicate persistence or health?
+
+### E) Failure Signals
+What patterns indicate collapse or invalid framing?
+
+### F) Reframing Moves
+How does this instrument change perspective?
+
+### G) Observation Test
+What would count as a *new observation* using this instrument?
+
+---
+
+## 5) Orbit Lens (Instrument #1)
+
+**Focus:** balance, gradients, persistence, stability under motion.
+
+- Forces: structure vs entropy
+- Distance: density, degree, step size, conditioning depth
+- Invariants: bounded collisions, energy, entropy under constraint
+- Failure: collapse into rigidity or noise
+
+Orbit establishes the pattern. It is not canonical.
+
+---
+
+## 6) Future Instruments (Examples, Not Prescriptions)
+
+- **Compression Lens** – invariants under minimal description
+- **Adversarial Lens** – worst-case stress and counterexamples
+- **Evolution Lens** – mutation, selection, path dependence
+- **Energy Lens** – cost, dissipation, potential functions
+- **Temporal Lens** – time, accumulation, irreversible steps
+
+Each instrument must obey the same contract.
+
+---
+
+## 7) Integration with ORP Workflow
+
+Instruments are optional inputs to claims.
+
+**CLAIM.md hook (optional):**
+
+> **Instrument(s) used:**  
+> (e.g. Orbit Lens, Compression Lens, Adversarial Lens)
+>
+> **Instrument parameters explored (if any):**  
+> (brief — distance knob, regime, or slice examined)
+
+Claims may reference one or more instruments, but verification ignores the instrument and tests the claim directly.
+
+Failed claims remain valuable regardless of instrument choice.
+
+---
+
+## 8) Where Instruments Live
+
+Recommended structure:
+
+- `modules/instruments/ORBIT/`
+- `modules/instruments/<NAME>/`
+
+Each instrument contains:
+- `README.md` (definition + philosophy)
+- `TEMPLATE.md` (fillable version)
+
+ORP core remains unchanged.
+
+---
+
+## 9) Why This Matters
+
+Disagreements move upstream.
+
+Instead of arguing outcomes, researchers compare:
+- frames
+- invariants
+- predictions
+
+Truth advances by **instrument performance**, not persuasion.
+
+---
+
+## Closing
+
+ORP governs truth.
+Instruments explore reality.
+
+No single lens owns understanding.
+But every lens must answer to verification.
+
+*Orbit is the first instrument.
+It will not be the last.*

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "open-research-protocol",
+  "version": "0.3.0",
+  "description": "ORP CLI (Open Research Protocol): agent-friendly research workflows, runtime, reports, and pack tooling.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SproutSeeds/orp.git"
+  },
+  "homepage": "https://github.com/SproutSeeds/orp#readme",
+  "bugs": {
+    "url": "https://github.com/SproutSeeds/orp/issues"
+  },
+  "bin": {
+    "orp": "bin/orp.js"
+  },
+  "files": [
+    "bin/",
+    "cli/",
+    "cone/",
+    "docs/",
+    "examples/",
+    "modules/",
+    "packs/",
+    "scripts/",
+    "spec/",
+    "templates/",
+    "AGENT_INTEGRATION.md",
+    "INSTALL.md",
+    "LICENSE",
+    "PROTOCOL.md",
+    "README.md",
+    "llms.txt"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "postinstall": "node scripts/npm-postinstall-check.js",
+    "test": "python3 -m unittest discover -s tests -v"
+  },
+  "keywords": [
+    "agentic",
+    "ai-agents",
+    "cli",
+    "gates",
+    "llms",
+    "machine-readable",
+    "open-research-protocol",
+    "orp",
+    "research-automation",
+    "research-workflow"
+  ]
+}

package/packs/README.md

@@ -0,0 +1,16 @@
+# ORP Packs
+
+This directory contains optional downloadable ORP profile packs.
+
+- ORP core remains generic.
+- Packs provide domain-specific profile templates.
+
+Available packs:
+
+- `erdos-open-problems/` — sunflower/Erdos workflow templates (857/20/367 compare, discovery profiles, mathlib PR governance profiles, and Erdos catalog sync profile).
+- `external-pr-governance/` — generic local-first external OSS contribution governance pack with adapter examples.
+
+Install through ORP CLI:
+
+- `orp pack list`
+- `orp pack install --pack-id erdos-open-problems`