open-research-protocol 0.3.0

package/packs/issue-smashers/bootstrap/README.md

@@ -0,0 +1,19 @@
+# Issue Smashers Bootstrap
+
+This pack bootstraps a small operator-facing workspace scaffold into the install
+target.
+
+Generated by default:
+
+- `issue-smashers/README.md`
+- `issue-smashers/WORKSPACE_RULES.md`
+- `issue-smashers/setup-issue-smashers.sh`
+- `issue-smashers/analysis/PR_DRAFT_BODY.md`
+- `issue-smashers/analysis/ISSUE_SMASHERS_WATCHLIST.json`
+- `issue-smashers/analysis/ISSUE_SMASHERS_STATUS.md`
+- directory placeholders under `repos/`, `worktrees/`, `scratch/`, and
+  `archive/`
+
+The bootstrap intentionally does not clone repos automatically. It creates the
+workspace shape and leaves repo-specific cloning, remotes, hooks, and adapter
+commands to the operator or higher-level tooling.

package/packs/issue-smashers/bootstrap/setup-issue-smashers.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -eu
+
+ROOT="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+
+mkdir -p \
+  "$ROOT/analysis" \
+  "$ROOT/repos" \
+  "$ROOT/worktrees" \
+  "$ROOT/scratch" \
+  "$ROOT/archive"
+
+printf 'workspace_root=%s\n' "$ROOT"
+printf 'ensured=analysis\n'
+printf 'ensured=repos\n'
+printf 'ensured=worktrees\n'
+printf 'ensured=scratch\n'
+printf 'ensured=archive\n'

package/packs/issue-smashers/examples/issue-smashers.workspace.yml

@@ -0,0 +1,24 @@
+workspace:
+  root: issue-smashers
+  analysis_dir: issue-smashers/analysis
+  repos_dir: issue-smashers/repos
+  worktrees_dir: issue-smashers/worktrees
+  scratch_dir: issue-smashers/scratch
+  archive_dir: issue-smashers/archive
+
+watch_targets:
+  - repo: leanprover-community/mathlib4
+    issue: "5617"
+    lane: mathlib4/issue-5617
+    state: watch
+  - repo: google-deepmind/formal-conjectures
+    issue: "erdos-857"
+    lane: formal-conjectures/erdos-857
+    state: backlog
+
+policy:
+  workspace_git_repo: false
+  one_worktree_per_issue: true
+  fork_remote_name: origin
+  upstream_remote_name: upstream
+  process_only: true

package/packs/issue-smashers/pack.yml

@@ -0,0 +1,178 @@
+schema_version: "1.0.0"
+pack_id: issue-smashers
+name: Issue Smashers Pack
+version: "0.1.0"
+description: >
+  Opinionated ORP workspace pack for organized multi-repo external contribution
+  work, combining an issue-smashers directory convention with reusable PR
+  governance and feedback-hardening profiles.
+orp_version_min: "0.3.0"
+
+variables:
+  TARGET_REPO_ROOT:
+    description: Absolute path to the install target that will contain the issue-smashers workspace.
+    required: true
+  ISSUE_SMASHERS_ROOT:
+    description: Workspace root relative to TARGET_REPO_ROOT.
+    required: false
+    default: "issue-smashers"
+  ISSUE_SMASHERS_REPOS_DIR:
+    description: Base clone directory relative to TARGET_REPO_ROOT.
+    required: false
+    default: "issue-smashers/repos"
+  ISSUE_SMASHERS_WORKTREES_DIR:
+    description: Active issue worktree directory relative to TARGET_REPO_ROOT.
+    required: false
+    default: "issue-smashers/worktrees"
+  ISSUE_SMASHERS_SCRATCH_DIR:
+    description: Disposable scratch directory relative to TARGET_REPO_ROOT.
+    required: false
+    default: "issue-smashers/scratch"
+  ISSUE_SMASHERS_ARCHIVE_DIR:
+    description: Optional archive directory relative to TARGET_REPO_ROOT.
+    required: false
+    default: "issue-smashers/archive"
+  WATCHLIST_FILE:
+    description: Watchlist JSON path relative to TARGET_REPO_ROOT.
+    required: false
+    default: "issue-smashers/analysis/ISSUE_SMASHERS_WATCHLIST.json"
+  STATUS_FILE:
+    description: Human-readable status board path relative to TARGET_REPO_ROOT.
+    required: false
+    default: "issue-smashers/analysis/ISSUE_SMASHERS_STATUS.md"
+  WORKSPACE_RULES_FILE:
+    description: Workspace rules document path relative to TARGET_REPO_ROOT.
+    required: false
+    default: "issue-smashers/WORKSPACE_RULES.md"
+  DEFAULT_PR_BODY_FILE:
+    description: Default PR body file path relative to TARGET_REPO_ROOT.
+    required: false
+    default: "issue-smashers/analysis/PR_DRAFT_BODY.md"
+  TARGET_GITHUB_REPO:
+    description: GitHub repo receiving the contribution, for example leanprover-community/mathlib4.
+    required: false
+    default: "owner/repo"
+  TARGET_GITHUB_AUTHOR:
+    description: GitHub login used for coordination and overlap checks.
+    required: false
+    default: "your-login"
+  ORP_TIMEOUT_SEC:
+    description: Default gate timeout in seconds.
+    required: false
+    default: "1200"
+  WATCH_SELECT_COMMAND:
+    description: Command that selects a contribution target and records why it is worth pursuing.
+    required: false
+    default: "printf 'configure WATCH_SELECT_COMMAND\\n' >&2; exit 2"
+  WATCH_SELECT_PASS_TOKEN:
+    description: Stdout token indicating the watch/select gate passed.
+    required: false
+    default: "selection=PASS"
+  VIABILITY_COMMAND:
+    description: Command that decides whether starting work is etiquette-safe.
+    required: false
+    default: "printf 'configure VIABILITY_COMMAND\\n' >&2; exit 2"
+  VIABILITY_PASS_TOKEN:
+    description: Stdout token indicating the viability gate passed.
+    required: false
+    default: "decision=PASS"
+  OVERLAP_COMMAND:
+    description: Command that checks external overlap or confirms coordination is clear.
+    required: false
+    default: "printf 'configure OVERLAP_COMMAND\\n' >&2; exit 2"
+  OVERLAP_PASS_TOKEN:
+    description: Stdout token indicating the overlap gate passed.
+    required: false
+    default: "overlap=PASS"
+  LOCAL_GATE_COMMAND:
+    description: Command that performs the local-first verification gate.
+    required: false
+    default: "printf 'configure LOCAL_GATE_COMMAND\\n' >&2; exit 2"
+  LOCAL_GATE_PASS_TOKEN:
+    description: Stdout token indicating the local gate passed.
+    required: false
+    default: "gate=PASS"
+  READY_TO_DRAFT_COMMAND:
+    description: Command that freezes the branch as ready to open or update a draft PR on the same HEAD.
+    required: false
+    default: "printf 'configure READY_TO_DRAFT_COMMAND\\n' >&2; exit 2"
+  READY_TO_DRAFT_PASS_TOKEN:
+    description: Stdout token indicating the ready-to-draft gate passed.
+    required: false
+    default: "ready_to_draft=PASS"
+  PR_BODY_PREFLIGHT_COMMAND:
+    description: Command that validates portable public PR text.
+    required: false
+    default: "printf 'configure PR_BODY_PREFLIGHT_COMMAND\\n' >&2; exit 2"
+  PR_BODY_PASS_TOKEN:
+    description: Stdout token indicating PR body preflight passed.
+    required: false
+    default: "gate=PASS"
+  DRAFT_PR_TRANSITION_COMMAND:
+    description: Command that opens or updates the draft PR and refuses if ready markers no longer match the current HEAD.
+    required: false
+    default: "printf 'configure DRAFT_PR_TRANSITION_COMMAND\\n' >&2; exit 2"
+  DRAFT_PR_TRANSITION_PASS_TOKEN:
+    description: Stdout token indicating the draft PR open/update transition passed.
+    required: false
+    default: "draft_pr=PASS"
+  DRAFT_CI_COMMAND:
+    description: Command that checks draft CI or draft lifecycle readiness.
+    required: false
+    default: "printf 'configure DRAFT_CI_COMMAND\\n' >&2; exit 2"
+  DRAFT_CI_PASS_TOKEN:
+    description: Stdout token indicating draft CI is green or otherwise acceptable.
+    required: false
+    default: "draft_ci=PASS"
+  READY_FOR_REVIEW_COMMAND:
+    description: Command that decides whether the PR can be promoted from draft to ready.
+    required: false
+    default: "printf 'configure READY_FOR_REVIEW_COMMAND\\n' >&2; exit 2"
+  READY_FOR_REVIEW_PASS_TOKEN:
+    description: Stdout token indicating ready-for-review conditions are satisfied.
+    required: false
+    default: "ready_for_review=PASS"
+  FEEDBACK_RECORD_COMMAND:
+    description: Command that records what maintainer feedback slipped and why.
+    required: false
+    default: "printf 'configure FEEDBACK_RECORD_COMMAND\\n' >&2; exit 2"
+  FEEDBACK_RECORD_PASS_TOKEN:
+    description: Stdout token indicating maintainer-feedback recording passed.
+    required: false
+    default: "feedback_recorded=PASS"
+  GUARD_VALIDATION_COMMAND:
+    description: Command that validates the new or updated guard with PASS and FAIL coverage.
+    required: false
+    default: "printf 'configure GUARD_VALIDATION_COMMAND\\n' >&2; exit 2"
+  GUARD_VALIDATION_PASS_TOKEN:
+    description: Stdout token indicating guard validation passed.
+    required: false
+    default: "guard_validation=PASS"
+  DOC_SYNC_COMMAND:
+    description: Command that confirms docs, templates, and agent instructions were updated with the guard.
+    required: false
+    default: "printf 'configure DOC_SYNC_COMMAND\\n' >&2; exit 2"
+  DOC_SYNC_PASS_TOKEN:
+    description: Stdout token indicating governance docs were synced.
+    required: false
+    default: "docs_sync=PASS"
+
+templates:
+  issue_smashers_workspace:
+    path: profiles/issue-smashers.yml.tmpl
+    description: Opinionated issue-smashers workspace and external contribution governance profiles.
+    output_hint: orp.issue-smashers.yml
+    default_profiles:
+      - issue_smashers_watch_select
+      - issue_smashers_pre_open
+      - issue_smashers_local_readiness
+      - issue_smashers_draft_transition
+      - issue_smashers_draft_lifecycle
+      - issue_smashers_full_flow
+
+  issue_smashers_feedback_hardening:
+    path: profiles/issue-smashers-feedback-hardening.yml.tmpl
+    description: Issue-smashers maintainer-feedback hardening profile.
+    output_hint: orp.issue-smashers-feedback-hardening.yml
+    default_profiles:
+      - issue_smashers_feedback_hardening

package/packs/issue-smashers/profiles/issue-smashers-feedback-hardening.yml.tmpl

@@ -0,0 +1,102 @@
+version: "1"
+
+project:
+  name: issue-smashers-feedback-hardening
+  repo_root: .
+  canonical_paths:
+    workspace_root: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_ROOT}}
+    watchlist_json: {{TARGET_REPO_ROOT}}/{{WATCHLIST_FILE}}
+    status_md: {{TARGET_REPO_ROOT}}/{{STATUS_FILE}}
+    workspace_rules_md: {{TARGET_REPO_ROOT}}/{{WORKSPACE_RULES_FILE}}
+    default_pr_body_file: {{TARGET_REPO_ROOT}}/{{DEFAULT_PR_BODY_FILE}}
+
+runtime:
+  shell: /bin/bash
+  default_timeout_sec: {{ORP_TIMEOUT_SEC}}
+  artifacts_root: orp/artifacts
+
+packet:
+  default_kind: verification
+  output_dir: orp/packets
+  write_markdown: true
+  deterministic_mode: true
+
+lifecycle:
+  claim_status_map:
+    Draft: draft
+    In review: ready
+    Verified: reviewed
+    Blocked: blocked
+    Retracted: retracted
+  atom_status_map:
+    todo: draft
+    in_progress: ready
+    blocked: blocked
+    done: reviewed
+  claim_level_values:
+    - Exact
+    - Verified
+    - Heuristic
+    - Conjecture
+
+gates:
+  - id: feedback_record
+    description: Record what slipped, why it slipped, and how the workspace should prevent it next time.
+    phase: verification
+    command: >
+      {{FEEDBACK_RECORD_COMMAND}}
+    working_dir: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_ROOT}}
+    pass:
+      exit_codes: [0]
+      stdout_must_contain:
+        - {{FEEDBACK_RECORD_PASS_TOKEN}}
+    evidence:
+      include_stdout: true
+      include_stderr: true
+      paths:
+        - {{TARGET_REPO_ROOT}}/{{WATCHLIST_FILE}}
+        - {{TARGET_REPO_ROOT}}/{{STATUS_FILE}}
+    on_fail: mark_blocked
+
+  - id: guard_validation
+    description: Validate the new or updated guard with explicit PASS and FAIL coverage.
+    phase: verification
+    command: >
+      {{GUARD_VALIDATION_COMMAND}}
+    working_dir: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_ROOT}}
+    pass:
+      exit_codes: [0]
+      stdout_must_contain:
+        - {{GUARD_VALIDATION_PASS_TOKEN}}
+    evidence:
+      include_stdout: true
+      include_stderr: true
+    on_fail: stop
+
+  - id: docs_sync
+    description: Confirm workspace docs and operator notes were updated in the same pass.
+    phase: verification
+    command: >
+      {{DOC_SYNC_COMMAND}}
+    working_dir: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_ROOT}}
+    pass:
+      exit_codes: [0]
+      stdout_must_contain:
+        - {{DOC_SYNC_PASS_TOKEN}}
+    evidence:
+      include_stdout: true
+      include_stderr: true
+      paths:
+        - {{TARGET_REPO_ROOT}}/{{WORKSPACE_RULES_FILE}}
+        - {{TARGET_REPO_ROOT}}/{{STATUS_FILE}}
+    on_fail: mark_blocked
+
+profiles:
+  issue_smashers_feedback_hardening:
+    description: Convert maintainer feedback into a reusable issue-smashers guard plus synced docs.
+    mode: collaboration
+    packet_kind: verification
+    gate_ids:
+      - feedback_record
+      - guard_validation
+      - docs_sync

package/packs/issue-smashers/profiles/issue-smashers.yml.tmpl

@@ -0,0 +1,258 @@
+version: "1"
+
+project:
+  name: issue-smashers
+  repo_root: .
+  canonical_paths:
+    workspace_root: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_ROOT}}
+    repos_root: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_REPOS_DIR}}
+    worktrees_root: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_WORKTREES_DIR}}
+    scratch_root: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_SCRATCH_DIR}}
+    archive_root: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_ARCHIVE_DIR}}
+    watchlist_json: {{TARGET_REPO_ROOT}}/{{WATCHLIST_FILE}}
+    status_md: {{TARGET_REPO_ROOT}}/{{STATUS_FILE}}
+    workspace_rules_md: {{TARGET_REPO_ROOT}}/{{WORKSPACE_RULES_FILE}}
+    default_pr_body_file: {{TARGET_REPO_ROOT}}/{{DEFAULT_PR_BODY_FILE}}
+
+runtime:
+  shell: /bin/bash
+  default_timeout_sec: {{ORP_TIMEOUT_SEC}}
+  artifacts_root: orp/artifacts
+
+packet:
+  default_kind: pr
+  output_dir: orp/packets
+  write_markdown: true
+  deterministic_mode: true
+
+lifecycle:
+  claim_status_map:
+    Draft: draft
+    In review: ready
+    Verified: reviewed
+    Blocked: blocked
+    Retracted: retracted
+  atom_status_map:
+    todo: draft
+    in_progress: ready
+    blocked: blocked
+    done: reviewed
+  claim_level_values:
+    - Exact
+    - Verified
+    - Heuristic
+    - Conjecture
+
+gates:
+  - id: watch_select
+    description: Select a target issue lane and record why it belongs in the issue-smashers workspace.
+    phase: scope_lock
+    command: >
+      {{WATCH_SELECT_COMMAND}}
+    working_dir: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_ROOT}}
+    pass:
+      exit_codes: [0]
+      stdout_must_contain:
+        - {{WATCH_SELECT_PASS_TOKEN}}
+    evidence:
+      include_stdout: true
+      include_stderr: true
+      paths:
+        - {{TARGET_REPO_ROOT}}/{{WATCHLIST_FILE}}
+        - {{TARGET_REPO_ROOT}}/{{STATUS_FILE}}
+    on_fail: mark_blocked
+
+  - id: viability_gate
+    description: Decide whether work is viable and etiquette-safe before creating noise.
+    phase: scope_lock
+    command: >
+      {{VIABILITY_COMMAND}}
+    working_dir: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_ROOT}}
+    pass:
+      exit_codes: [0]
+      stdout_must_contain:
+        - {{VIABILITY_PASS_TOKEN}}
+    evidence:
+      include_stdout: true
+      include_stderr: true
+      paths:
+        - {{TARGET_REPO_ROOT}}/{{WATCHLIST_FILE}}
+        - {{TARGET_REPO_ROOT}}/{{STATUS_FILE}}
+    on_fail: mark_blocked
+
+  - id: overlap_gate
+    description: Confirm overlap is clear or coordination is already complete.
+    phase: scope_lock
+    command: >
+      {{OVERLAP_COMMAND}}
+    working_dir: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_ROOT}}
+    pass:
+      exit_codes: [0]
+      stdout_must_contain:
+        - {{OVERLAP_PASS_TOKEN}}
+    evidence:
+      include_stdout: true
+      include_stderr: true
+      paths:
+        - {{TARGET_REPO_ROOT}}/{{WATCHLIST_FILE}}
+        - {{TARGET_REPO_ROOT}}/{{STATUS_FILE}}
+    on_fail: mark_blocked
+
+  - id: local_gate
+    description: Run the host-repo local verification gate before any draft PR update.
+    phase: verification
+    command: >
+      {{LOCAL_GATE_COMMAND}}
+    working_dir: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_ROOT}}
+    timeout_sec: {{ORP_TIMEOUT_SEC}}
+    pass:
+      exit_codes: [0]
+      stdout_must_contain:
+        - {{LOCAL_GATE_PASS_TOKEN}}
+    evidence:
+      include_stdout: true
+      include_stderr: true
+      paths:
+        - {{TARGET_REPO_ROOT}}/{{WORKSPACE_RULES_FILE}}
+    on_fail: stop
+
+  - id: ready_to_draft
+    description: Freeze the branch or lane as ready to open or update a draft PR on the same HEAD.
+    phase: verification
+    command: >
+      {{READY_TO_DRAFT_COMMAND}}
+    working_dir: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_ROOT}}
+    pass:
+      exit_codes: [0]
+      stdout_must_contain:
+        - {{READY_TO_DRAFT_PASS_TOKEN}}
+    evidence:
+      include_stdout: true
+      include_stderr: true
+      paths:
+        - {{TARGET_REPO_ROOT}}/{{STATUS_FILE}}
+    on_fail: stop
+
+  - id: pr_body_preflight
+    description: Enforce portable, reviewer-friendly public PR text for the current issue-smashers lane.
+    phase: verification
+    command: >
+      {{PR_BODY_PREFLIGHT_COMMAND}}
+    working_dir: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_ROOT}}
+    pass:
+      exit_codes: [0]
+      stdout_must_contain:
+        - {{PR_BODY_PASS_TOKEN}}
+    evidence:
+      include_stdout: true
+      include_stderr: true
+      paths:
+        - {{TARGET_REPO_ROOT}}/{{DEFAULT_PR_BODY_FILE}}
+    on_fail: mark_blocked
+
+  - id: draft_pr_transition
+    description: Open or update the draft PR only after the same-head readiness chain is satisfied.
+    phase: verification
+    command: >
+      {{DRAFT_PR_TRANSITION_COMMAND}}
+    working_dir: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_ROOT}}
+    pass:
+      exit_codes: [0]
+      stdout_must_contain:
+        - {{DRAFT_PR_TRANSITION_PASS_TOKEN}}
+    evidence:
+      include_stdout: true
+      include_stderr: true
+      paths:
+        - {{TARGET_REPO_ROOT}}/{{DEFAULT_PR_BODY_FILE}}
+        - {{TARGET_REPO_ROOT}}/{{STATUS_FILE}}
+    on_fail: stop
+
+  - id: draft_ci
+    description: Confirm draft CI is green or otherwise acceptable for promotion.
+    phase: verification
+    command: >
+      {{DRAFT_CI_COMMAND}}
+    working_dir: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_ROOT}}
+    pass:
+      exit_codes: [0]
+      stdout_must_contain:
+        - {{DRAFT_CI_PASS_TOKEN}}
+    evidence:
+      include_stdout: true
+      include_stderr: true
+      paths:
+        - {{TARGET_REPO_ROOT}}/{{STATUS_FILE}}
+    on_fail: mark_blocked
+
+  - id: ready_for_review
+    description: Confirm the PR can move from draft to ready-for-review.
+    phase: verification
+    command: >
+      {{READY_FOR_REVIEW_COMMAND}}
+    working_dir: {{TARGET_REPO_ROOT}}/{{ISSUE_SMASHERS_ROOT}}
+    pass:
+      exit_codes: [0]
+      stdout_must_contain:
+        - {{READY_FOR_REVIEW_PASS_TOKEN}}
+    evidence:
+      include_stdout: true
+      include_stderr: true
+      paths:
+        - {{TARGET_REPO_ROOT}}/{{STATUS_FILE}}
+    on_fail: mark_blocked
+
+profiles:
+  issue_smashers_watch_select:
+    description: Choose a candidate lane and record why it belongs in the workspace.
+    mode: collaboration
+    packet_kind: pr
+    gate_ids:
+      - watch_select
+
+  issue_smashers_pre_open:
+    description: Viability and overlap checks before implementation or draft creation.
+    mode: collaboration
+    packet_kind: pr
+    gate_ids:
+      - viability_gate
+      - overlap_gate
+
+  issue_smashers_local_readiness:
+    description: Local verification, same-head freeze, and PR-body hygiene before draft open/update.
+    mode: collaboration
+    packet_kind: pr
+    gate_ids:
+      - local_gate
+      - ready_to_draft
+      - pr_body_preflight
+
+  issue_smashers_draft_transition:
+    description: Open or update the draft PR once the readiness chain has passed.
+    mode: collaboration
+    packet_kind: pr
+    gate_ids:
+      - draft_pr_transition
+
+  issue_smashers_draft_lifecycle:
+    description: Draft CI and ready-for-review checks after a draft PR exists.
+    mode: collaboration
+    packet_kind: pr
+    gate_ids:
+      - draft_ci
+      - ready_for_review
+
+  issue_smashers_full_flow:
+    description: End-to-end issue-smashers lifecycle from watch/select through ready-for-review.
+    mode: collaboration
+    packet_kind: pr
+    gate_ids:
+      - watch_select
+      - viability_gate
+      - overlap_gate
+      - local_gate
+      - ready_to_draft
+      - pr_body_preflight
+      - draft_pr_transition
+      - draft_ci
+      - ready_for_review

package/scripts/npm-postinstall-check.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("child_process");
+
+function firstAvailable(candidates) {
+  for (const cmd of candidates) {
+    const probe = spawnSync(cmd, ["--version"], { encoding: "utf8" });
+    if (!probe.error && probe.status === 0) {
+      return cmd;
+    }
+  }
+  return null;
+}
+
+const pythonCandidates = process.platform === "win32" ? ["py", "python", "python3"] : ["python3", "python"];
+const py = firstAvailable(pythonCandidates);
+
+if (!py) {
+  console.warn("[orp] warning: Python 3 not found on PATH.");
+  console.warn("[orp] install Python 3 to use the `orp` CLI binary.");
+  process.exit(0);
+}
+
+const yamlCheckArgs = py === "py" ? ["-3", "-c", "import yaml"] : ["-c", "import yaml"];
+const yamlCheck = spawnSync(py, yamlCheckArgs, { encoding: "utf8" });
+
+if (yamlCheck.error || yamlCheck.status !== 0) {
+  console.warn("[orp] warning: PyYAML not detected in your Python environment.");
+  console.warn("[orp] run: python3 -m pip install pyyaml");
+}
+

package/scripts/orp

@@ -0,0 +1,11 @@
+#!/usr/bin/env sh
+set -eu
+
+SCRIPT_PATH="$0"
+case "$SCRIPT_PATH" in
+  */*) : ;;
+  *) SCRIPT_PATH="$(command -v "$SCRIPT_PATH" 2>/dev/null || printf '%s' "$SCRIPT_PATH")" ;;
+esac
+
+ROOT_DIR="$(cd "$(dirname "$SCRIPT_PATH")/.." && pwd)"
+exec python3 "$ROOT_DIR/cli/orp.py" "$@"