open-research-protocol 0.3.0

package/docs/PRESENTATION_BOW.md

@@ -0,0 +1,100 @@
+# ORP + Instruments — A Calm Introduction
+
+> *A protocol for truth under pressure, with optional ways of seeing.*
+
+This short document ties together ORP and Instruments for presentation. It is not exhaustive. It is meant to orient, reassure, and invite.
+
+---
+
+## What ORP Is
+
+ORP (Open Research Protocol) governs **what happens after a claim is made**:
+
+- claims must be explicit
+- verification must be concrete
+- failures are recorded, not hidden
+- disagreement resolves by evidence, not argument
+
+ORP is intentionally minimal. It does not tell you *what to think* or *how to explore*.
+
+---
+
+## Why Instruments Exist
+
+Most disagreement begins **before** claims — at framing.
+
+Instruments are optional, process-only tools that help choose a reference frame *before* making a claim. They influence questions, not outcomes.
+
+- ORP governs truth
+- Instruments explore reality
+
+Verification is blind to instruments.
+
+---
+
+## The Relationship (One Glance)
+
+Curiosity
+↓
+[ Instrument (optional) ]  →  predictions / focus
+↓
+Claim (ORP)
+↓
+Verification
+↓
+✓ Accepted  |  ✗ Downgraded / Failed (recorded)
+
+You may enter at any point. Instruments are never required.
+
+---
+
+## The Initial Instrument Set
+
+These instruments are **examples**, not requirements:
+
+- **Orbit Lens** — persistence, balance, gradients, stability
+- **Compression Lens** — essence, invariants, minimal description
+- **Adversarial Lens** — failure modes, counterexamples, robustness
+
+They are orthogonal. Use one, several, or none.
+
+---
+
+## How to Choose (or Not)
+
+- If the problem feels unclear → try an instrument
+- If the claim is obvious → skip instruments
+- If framing helps → use it
+- If it doesn’t → ignore it
+
+ORP works either way.
+
+---
+
+## Invitation
+
+If you notice a repeatable way of seeing that:
+- reveals structure,
+- generates predictions,
+- or exposes failure modes,
+
+that may be a new instrument.
+
+Create it. Share it. Discard it if it fails.
+
+ORP will still work.
+
+---
+
+## Closing
+
+This system is designed to:
+- reduce ego
+- increase clarity
+- preserve failed work
+- allow multiple perspectives without multiple truths
+
+It offers a place to stand, not a path to follow.
+
+*Use what helps. Ignore the rest.*
+

package/docs/PROFILE_PACKS.md

@@ -0,0 +1,227 @@
+# ORP Profile Packs (v1 Draft)
+
+This is now an advanced/internal ORP surface.
+
+If you are using ORP normally, prefer:
+
+- `orp collaborate ...` for collaboration
+- `orp erdos ...` for Erdos-specific work
+
+Read this document when you are maintaining ORP, installing domain templates
+directly, or working on pack internals.
+
+Profile packs let ORP stay general while domain experts publish reusable workflows for specific problem sets.
+
+## Core principle
+
+- ORP core: generic runtime/spec/lifecycle.
+- Profile packs: optional domain bundles (gates, profiles, adapters, docs).
+
+This keeps one stable ORP runtime while enabling many ecosystems.
+
+## Pack layout
+
+```text
+packs/<pack-id>/
+  pack.yml
+  README.md
+  profiles/
+    *.yml.tmpl
+  adapters/           # optional
+  docs/               # optional
+```
+
+## `pack.yml` metadata
+
+Canonical fields:
+
+- `schema_version`: `1.0.0`
+- `pack_id`: stable id
+- `name`, `version`, `description`
+- `orp_version_min`: optional compatibility floor
+- `variables`: render-time variables (for example `TARGET_REPO_ROOT`)
+- `templates`: available config templates
+
+Schema:
+
+- `spec/v1/profile-pack.schema.json`
+
+## Template variables
+
+Templates use `{{VAR_NAME}}` placeholders.
+
+Example:
+
+```yaml
+working_dir: {{TARGET_REPO_ROOT}}
+```
+
+Render-time values are supplied via `--var KEY=VALUE`.
+
+## Install flow (fresh ORP -> pack adoption)
+
+Recommended via ORP CLI:
+
+```bash
+orp pack list
+
+orp pack install \
+  --pack-id erdos-open-problems
+```
+
+If developing ORP locally, the equivalent command is `./scripts/orp`.
+
+External pack source via CLI-only flow:
+
+```bash
+orp pack fetch \
+  --source https://github.com/example/orp-packs.git \
+  --pack-id erdos-open-problems \
+  --install-target /path/to/repo
+```
+
+This installs rendered config files and writes a dependency audit report:
+
+- `./orp.erdos-catalog-sync.yml`
+- `./orp.erdos-live-compare.yml`
+- `./orp.erdos-problem857.yml`
+- `./orp.erdos.pack-install-report.md`
+
+Issue Smashers workspace install:
+
+```bash
+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/README.md`
+- `./issue-smashers/WORKSPACE_RULES.md`
+- `./issue-smashers/setup-issue-smashers.sh`
+- `./issue-smashers/analysis/ISSUE_SMASHERS_WATCHLIST.json`
+- `./issue-smashers/analysis/ISSUE_SMASHERS_STATUS.md`
+- `./issue-smashers/analysis/PR_DRAFT_BODY.md`
+
+Use this pack when you want the generic external contribution lifecycle plus a
+standard workspace convention for multi-repo issue work. It does not clone repos
+automatically and it keeps command hooks install-and-adapt by default.
+
+Default install behavior is starter-friendly:
+
+- includes `catalog`, `live_compare`, and `problem857`,
+- scaffolds starter 857/20/367 board scripts + board JSON seeds for install-and-go,
+- keeps `governance` optional.
+
+Public-only setup (no private adapters yet):
+
+```bash
+orp pack install \
+  --pack-id erdos-open-problems \
+  --include catalog
+```
+
+Clean-room public pack cycle:
+
+```bash
+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 path has been validated against the published npm package in a fresh directory and is the recommended first pack workflow.
+
+Clean-room public Problem 857 cycle:
+
+```bash
+orp pack install \
+  --pack-id erdos-open-problems \
+  --include problem857
+
+orp erdos sync \
+  --problem-id 857 \
+  --out-problem-dir analysis/erdos_problems/selected
+
+orp --config orp.erdos-problem857.yml \
+  gate run --profile sunflower_problem857_discovery
+
+orp report summary
+```
+
+This lane remains starter-heavy overall, but `spec_faithfulness` now performs a real public consistency check against the synced Problem 857 payload.
+
+If you want a fresh repo to pull the real public `sunflower-lean` repo instead of starter-only 857 scaffolding, install with:
+
+```bash
+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 that the discovery workflow needs.
+
+Strict mode for private adapter readiness:
+
+```bash
+./scripts/orp pack install \
+  --pack-id erdos-open-problems \
+  --target-repo-root /path/to/sunflower-coda/repo \
+  --include live_compare \
+  --include problem857 \
+  --include governance \
+  --no-bootstrap \
+  --strict-deps
+```
+
+Manual render path (advanced):
+
+```bash
+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
+```
+
+Then run ORP with the rendered config:
+
+```bash
+orp --repo-root /path/to/scratch-repo --config /path/to/repo/orp.erdos-live-compare.yml \
+  gate run --profile sunflower_live_compare_857
+
+orp --repo-root /path/to/scratch-repo report summary --run-id <run_id>
+
+export ORP_ISSUE_NUMBER=34959
+export ORP_BRANCH_NAME=cody/issue-34959-cancellation-bounds
+export ORP_NATURALITY_MODULE=Mathlib/Combinatorics/SetFamily/Shade
+export ORP_PR_BODY_FILE=/path/to/repo/analysis/MATHLIB_DRAFT_PR_BODY.md
+
+orp --repo-root /path/to/scratch-repo --config /path/to/repo/orp.erdos-mathlib-pr-governance.yml \
+  gate run --profile sunflower_mathlib_full_flow
+
+orp --repo-root /path/to/scratch-repo --config /path/to/repo/orp.erdos-catalog-sync.yml \
+  gate run --profile erdos_catalog_sync_active
+
+orp erdos sync --problem-id 857 --problem-id 20
+```
+
+## Publishing model
+
+- Packs can live in this repo (`packs/`) or external repos.
+- Users can copy/install packs without changing ORP core.
+- Version packs independently (for example `0.1.0`, `0.2.0`).
+
+## Quality guidance
+
+- Keep templates repo-agnostic (no personal absolute paths).
+- Keep required variables minimal.
+- Document assumptions in pack README.
+- Prefer profile variants over hardcoded behavior in ORP core.

package/docs/SUNFLOWER_CODA_PR_GOVERNANCE_MAPPING.md

@@ -0,0 +1,77 @@
+# Sunflower-Coda PR Governance Mapping (ORP)
+
+Date analyzed: 2026-03-05
+
+For the generalized cross-ecosystem version, read:
+
+- `docs/EXTERNAL_CONTRIBUTION_GOVERNANCE.md`
+
+This note maps live `sunflower-coda/repo` PR-governance flow into ORP profile-pack gates without hardwiring ORP core to one team.
+
+## Sources reviewed
+
+- `docs/MATHLIB_SUBMISSION_CHECKLIST.md`
+- `docs/MATHLIB_ISSUE_VIABILITY_GATE.md`
+- `docs/MATHLIB_DRAFT_PR_TEMPLATE.md`
+- `docs/UPSTREAM_PR_LANE.md`
+- `docs/UPSTREAM_SCOUT_LOOP.md`
+- `scripts/mathlib-issue-viability-gate.py`
+- `scripts/mathlib-issue-local-gate.sh`
+- `scripts/mathlib-tighten-fine-tooth-gate.sh`
+- `scripts/mathlib-ready-to-draft-gate.sh`
+- `scripts/mathlib-pr-body-preflight.py`
+- `scripts/upstream-pr-lane.sh`
+- `scripts/upstream-pr-plan.py`
+
+## Live contract extracted
+
+- Viability decision contract:
+  - `PASS`, `COORDINATE`, `CLOSE_CANDIDATE`, `BLOCKED_NOT_OPEN`
+  - gate output key: `decision=<...>`
+- Queue policy contract (anti-spam):
+  - `policy.submission_mode=<...>`
+  - `policy.max_prs_per_session=<...>`
+  - `policy.require_explicit_approval=<...>`
+- Local gate contract:
+  - `gate=PASS`
+  - marker output: `marker_file=...`
+- Tighten gate contract:
+  - `tighten_fine_tooth=PASS`
+- Ready-to-draft contract:
+  - `ready_to_draft=PASS`
+- PR body preflight contract:
+  - `gate=PASS`
+  - includes metrics line (`metrics: ...`)
+
+## ORP representation
+
+Added template:
+
+- `packs/erdos-open-problems/profiles/sunflower-mathlib-pr-governance.yml.tmpl`
+
+Profiles:
+
+- `sunflower_mathlib_pre_open`
+  - checklist presence
+  - queue policy guard
+  - lane checklist snapshot
+  - issue viability decision
+  - naturality snippet
+- `sunflower_mathlib_draft_readiness`
+  - local issue gate (core build/lint only)
+  - tighten/fine-tooth
+  - ready-to-draft freeze
+  - PR body preflight
+- `sunflower_mathlib_full_flow`
+  - combined pre-open + draft-readiness gates
+
+## Why this stays general
+
+- ORP core remains unchanged (`spec + runtime + packets`).
+- Sunflower/mathlib details live in an optional pack template.
+- The same runtime can execute different packs for different ecosystems.
+- Runtime inputs are parameterized:
+  - `TARGET_REPO_ROOT`, `MATHLIB_REPO_ROOT`, policy defaults
+  - per-run env (`ORP_ISSUE_NUMBER`, `ORP_BRANCH_NAME`, `ORP_NATURALITY_MODULE`, `ORP_PR_BODY_FILE`, `ORP_READY_NOTE`)
+
+This keeps ORP broadly reusable while preserving high-rigor local gate behavior for your active workflow.

package/docs/WHY_INSTRUMENTS.md

@@ -0,0 +1,118 @@
+# Why Instruments
+
+> *No single lens owns understanding.*
+
+ORP was built to govern **truth under pressure**.
+Instruments exist to explore reality *before* truth is claimed.
+
+This document explains why instruments matter — and invites you to create your own.
+
+---
+
+## Why Instruments Exist
+
+Most disagreements do not begin at verification.
+They begin much earlier — at framing.
+
+Two people can look at the same system and ask different questions:
+- one looks for balance,
+- another looks for failure,
+- another looks for essence.
+
+None of these are wrong.
+They are **different instruments**.
+
+ORP makes room for this reality instead of fighting it.
+
+---
+
+## What Instruments Are (and Are Not)
+
+Instruments are:
+- ways of choosing a reference frame
+- tools for generating better questions
+- methods for producing testable predictions
+
+Instruments are not:
+- claims
+- evidence
+- conclusions
+- authorities
+
+ORP governs claims.
+Instruments guide curiosity.
+
+---
+
+## Why Modularity Matters
+
+If ORP required a single framing, it would eventually fail.
+
+Truth survives by being:
+- approached from multiple angles
+- stressed by incompatible questions
+- verified independently of framing
+
+Modular instruments allow this without chaos.
+
+You may:
+- use one instrument
+- use several
+- ignore them entirely
+
+ORP still works.
+
+---
+
+## A Place to Stand, Not a Path to Follow
+
+Instruments do not tell you where to go.
+They give you a place to stand and look.
+
+You are free to:
+- discard an instrument
+- combine instruments
+- invent a new one
+
+What matters is what happens **after** claims are made.
+
+---
+
+## Invitation: Create an Instrument
+
+If you notice a repeatable way of seeing that:
+- reveals new structure,
+- generates predictions,
+- or exposes hidden failure modes,
+
+that may be an instrument.
+
+You are invited to:
+- write it down
+- make it process-only
+- define its forces and invariants
+- share it as a module
+
+No permission required.
+
+---
+
+## The Only Constraint
+
+Every instrument must ultimately answer to verification.
+
+If it helps generate true claims, it belongs.
+If it does not, it will naturally fall away.
+
+---
+
+## Closing
+
+Truth does not come from unanimity.
+It comes from well-governed interaction between perspectives.
+
+ORP is the harbor.
+Instruments are the vessels.
+
+*Bring the one you need — or build a new one.*
+

package/examples/README.md

@@ -0,0 +1,21 @@
+# Examples (non-exhaustive)
+
+These files are intentionally **minimal** and **illustrative**.
+
+- Treat `templates/` as the canonical spec for fields/structure.
+- Treat `PROTOCOL.md` as the canonical spec for workflow rules.
+- Do not treat examples as checklists or requirements.
+
+Additional v1 runtime draft examples:
+
+- `orp.sunflower-coda.atomic.yml` — discovery-first profile for atomic board workflows.
+- `orp.sunflower-coda.live-compare.yml` — side-by-side gate-compare profiles for sunflower Problems 857/20/367.
+- `orp.sunflower-coda.pr-governance.yml` — local-first PR governance profile set (pre-open, draft-readiness, full flow).
+- `orp.external-pr-governance.yml` — generic external OSS contribution governance example.
+- `orp.erdos-problems.catalog.yml` — Erdos catalog sync profile (all/open/closed + open-default active set).
+- `packet.problem_scope.example.json` — example `problem_scope` packet with board/ticket/gate/atom context.
+- `reports/` — example one-page run summaries for sunflower live-compare profiles.
+
+Pack install flow can generate these config files automatically:
+
+- `orp pack install --pack-id erdos-open-problems`

package/examples/example_claim.md

@@ -0,0 +1,33 @@
+# Example Claim (Heuristic)
+
+## Title
+Observed improvement from optimization pass
+
+## Claim ID
+`CLAIM-20260120-optimizer-speedup`
+
+## Claim Level
+Heuristic
+
+## Statement
+After tuning parameters X/Y, runtime appears ~25% faster on workload W on machine M.
+
+## Scope / Assumptions
+Single machine, single dataset; no cross-hardware validation yet.
+
+## Canonical Artifacts
+- `analysis/benchmarks/run_20260120.json`
+- `analysis/benchmarks/log_20260120.txt`
+
+## Verification Hook
+- Command(s):
+  - `python3 analysis/benchmarks/run.py --config analysis/benchmarks/config.json`
+- Expected outputs:
+  - A benchmark JSON and log file with comparable metrics.
+
+## Status
+In review
+
+## Next Hook
+Run the same benchmark on a second machine and upgrade to Verified if consistent.
+

package/examples/example_failed.md

@@ -0,0 +1,24 @@
+# Example Failed Path Record
+
+## Topic
+Attempted proof strategy based on assumption A
+
+## Summary
+The approach fails because assumption A does not hold in general (counterexample found).
+
+## What was attempted
+Tried to derive property P from assumption A using lemma L and case split.
+
+## Why it failed
+Counterexample: artifact `analysis/counterexamples/case_001.json` violates lemma precondition.
+
+## Evidence
+- `analysis/counterexamples/case_001.json`
+- `analysis/notes/attempt_20260120.md`
+
+## What this rules out
+Any proof relying on assumption A as a global invariant.
+
+## What might still work (next hook)
+Restrict to a narrower class where assumption A holds, or replace A with weaker condition A'.
+

package/examples/example_verification.md

@@ -0,0 +1,36 @@
+# Example Verification Record (INCONCLUSIVE → downgrade)
+
+## Verified Claim ID
+`CLAIM-20260120-optimizer-speedup`
+
+## Verifier
+`someone-else`
+
+## Date
+2026-01-20
+
+## Environment
+- OS / hardware: Linux x86_64
+- Python: 3.12
+
+## Inputs
+- `analysis/benchmarks/config.json`
+
+## Commands Run
+`python3 analysis/benchmarks/run.py --config analysis/benchmarks/config.json`
+
+## Outputs
+- `analysis/benchmarks/run_20260120_verifier.json`
+
+## Result
+INCONCLUSIVE
+
+## Notes
+Verifier could not reproduce the claimed speedup because the benchmark uses a non-deterministic source and lacks fixed seeds.
+
+## Default action if FAIL/INCONCLUSIVE
+Downgrade the claim to Conjecture (or keep Heuristic but mark “blocked by determinism”).
+
+## Next Hook
+Add deterministic seeding and re-run the benchmark.
+