open-research-protocol 0.3.0

package/scripts/orp-agent-integrate.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env sh
+set -eu
+
+# orp-agent-integrate.sh — install/check/sync the ORP agent instructions snippet in a target Markdown file.
+#
+# Usage:
+#   ./scripts/orp-agent-integrate.sh [--check|--sync] /path/to/your/agent/instructions.md
+
+usage() {
+  cat <<EOF
+usage:
+  $0 /path/to/agent/instructions.md
+  $0 --check /path/to/agent/instructions.md
+  $0 --sync  /path/to/agent/instructions.md
+
+default behavior:
+  Append the ORP snippet if missing (never overwrites).
+
+--check:
+  Exit 0 if the ORP snippet exists and matches the canonical snippet in AGENT_INTEGRATION.md.
+  Exit 1 if missing or out of date.
+
+--sync:
+  Ensure the target contains the canonical ORP snippet (append if missing; replace if present but out of date).
+EOF
+}
+
+MODE="append"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --check) MODE="check"; shift ;;
+    --sync) MODE="sync"; shift ;;
+    --help|-h) usage; exit 0 ;;
+    --) shift; break ;;
+    -*) usage; exit 2 ;;
+    *) break ;;
+  esac
+done
+
+if [ "${1:-}" = "" ]; then
+  usage
+  exit 2
+fi
+
+TARGET="$1"
+MARKER_BEGIN="<!-- ORP:BEGIN -->"
+MARKER_END="<!-- ORP:END -->"
+
+SNIPPET_TMP=""
+TARGET_SNIPPET_TMP=""
+OUT_TMP=""
+cleanup() {
+  if [ -n "${SNIPPET_TMP:-}" ] && [ -f "$SNIPPET_TMP" ]; then
+    rm -f "$SNIPPET_TMP"
+  fi
+  if [ -n "${TARGET_SNIPPET_TMP:-}" ] && [ -f "$TARGET_SNIPPET_TMP" ]; then
+    rm -f "$TARGET_SNIPPET_TMP"
+  fi
+  if [ -n "${OUT_TMP:-}" ] && [ -f "$OUT_TMP" ]; then
+    rm -f "$OUT_TMP"
+  fi
+  :
+}
+trap cleanup EXIT
+
+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)"
+SNIPPET_FILE="$ROOT_DIR/AGENT_INTEGRATION.md"
+
+if [ ! -f "$SNIPPET_FILE" ]; then
+  echo "error: missing $SNIPPET_FILE"
+  exit 4
+fi
+
+SNIPPET_TMP="$(mktemp)"
+awk '
+  $0=="<!-- ORP:BEGIN -->" {p=1}
+  p {print}
+  $0=="<!-- ORP:END -->" {exit}
+' "$SNIPPET_FILE" > "$SNIPPET_TMP"
+
+if ! grep -q "$MARKER_BEGIN" "$SNIPPET_TMP" || ! grep -q "$MARKER_END" "$SNIPPET_TMP"; then
+  echo "error: ORP snippet markers not found in $SNIPPET_FILE"
+  exit 4
+fi
+
+cksum2() {
+  cksum "$1" | awk '{print $1 " " $2}'
+}
+
+canonical_sig="$(cksum2 "$SNIPPET_TMP")"
+
+has_begin="0"
+has_end="0"
+if [ -f "$TARGET" ]; then
+  if grep -q "$MARKER_BEGIN" "$TARGET"; then has_begin="1"; fi
+  if grep -q "$MARKER_END" "$TARGET"; then has_end="1"; fi
+fi
+
+if [ "$has_begin" = "1" ] && [ "$has_end" = "0" ]; then
+  echo "error: $TARGET contains $MARKER_BEGIN but not $MARKER_END"
+  exit 4
+fi
+if [ "$has_begin" = "0" ] && [ "$has_end" = "1" ]; then
+  echo "error: $TARGET contains $MARKER_END but not $MARKER_BEGIN"
+  exit 4
+fi
+
+target_sig=""
+if [ "$has_begin" = "1" ]; then
+  TARGET_SNIPPET_TMP="$(mktemp)"
+  awk '
+    $0=="<!-- ORP:BEGIN -->" {p=1}
+    p {print}
+    $0=="<!-- ORP:END -->" {exit}
+  ' "$TARGET" > "$TARGET_SNIPPET_TMP"
+  target_sig="$(cksum2 "$TARGET_SNIPPET_TMP")"
+fi
+
+if [ "$MODE" = "check" ]; then
+  if [ "$has_begin" = "0" ]; then
+    echo "ORP snippet missing in: $TARGET"
+    echo "Fix: $0 --sync $TARGET"
+    exit 1
+  fi
+  if [ "$target_sig" = "$canonical_sig" ]; then
+    echo "OK: ORP snippet is up to date in: $TARGET"
+    exit 0
+  fi
+  echo "OUT OF DATE: ORP snippet differs from $SNIPPET_FILE"
+  echo "Fix: $0 --sync $TARGET"
+  exit 1
+fi
+
+if [ "$MODE" = "append" ] && [ "$has_begin" = "1" ]; then
+  echo "ORP snippet already present in: $TARGET (not modifying)"
+  echo "Tip: $0 --check $TARGET  (detect drift)"
+  echo "Tip: $0 --sync  $TARGET  (update in place)"
+  exit 0
+fi
+
+mkdir -p "$(dirname "$TARGET")"
+
+if [ "$MODE" = "append" ]; then
+  if [ -f "$TARGET" ] && [ -s "$TARGET" ]; then
+    printf '\n' >> "$TARGET"
+  fi
+  cat "$SNIPPET_TMP" >> "$TARGET"
+  echo "ORP snippet appended to: $TARGET"
+  echo "Next: ensure your agent uses that file as its primary instructions."
+  exit 0
+fi
+
+if [ "$MODE" = "sync" ]; then
+  if [ "$has_begin" = "0" ]; then
+    if [ -f "$TARGET" ] && [ -s "$TARGET" ]; then
+      printf '\n' >> "$TARGET"
+    fi
+    cat "$SNIPPET_TMP" >> "$TARGET"
+    echo "ORP snippet appended to: $TARGET"
+    echo "Next: ensure your agent uses that file as its primary instructions."
+    exit 0
+  fi
+
+  OUT_TMP="$(mktemp)"
+  awk -v begin="$MARKER_BEGIN" -v end="$MARKER_END" -v snippet="$SNIPPET_TMP" '
+    BEGIN {in_old=0}
+    {
+      if ($0==begin) {
+        in_old=1
+        while ((getline line < snippet) > 0) print line
+        close(snippet)
+        next
+      }
+      if (in_old) {
+        if ($0==end) in_old=0
+        next
+      }
+      print
+    }
+  ' "$TARGET" > "$OUT_TMP"
+
+  mv "$OUT_TMP" "$TARGET"
+  OUT_TMP=""
+
+  echo "ORP snippet synced in: $TARGET"
+  echo "Next: ensure your agent uses that file as its primary instructions."
+  exit 0
+fi
+
+echo "error: unknown mode"
+exit 4

package/scripts/orp-checkpoint.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env sh
+set -eu
+
+# orp-checkpoint.sh — lightweight ORP checkpoint for agentic workflows (process-only).
+#
+# Typical usage (agent knows its instruction file path):
+#   ./scripts/orp-checkpoint.sh --agent-file /path/to/agent/instructions.md "pre-push checkpoint"
+#
+# Modes:
+#   --status  : print last checkpoint + current git status summary (no write)
+#   --check   : run checks only (no write)
+#   --sync    : sync ORP snippet into agent files before checking (requires --agent-file)
+#
+# Exit codes:
+#   0 = OK
+#   1 = ORP snippet missing/out of date in one or more agent files (or check failed)
+#   2 = usage error
+#   4 = internal/config error
+
+usage() {
+  cat <<EOF
+usage:
+  $0 [--status|--check] [--sync] [--agent-file PATH ...] [--log-file PATH] [NOTE]
+
+examples:
+  $0 --status
+  $0 --agent-file CLAUDE.md "compaction checkpoint"
+  $0 --sync --agent-file CLAUDE.md --agent-file AGENTS.md "pre-push checkpoint"
+  $0 --check --agent-file CLAUDE.md
+EOF
+}
+
+MODE="write"
+DO_SYNC="0"
+LOG_FILE=""
+NOTE=""
+AGENT_FILES=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --status) MODE="status"; shift ;;
+    --check) MODE="check"; shift ;;
+    --sync) DO_SYNC="1"; shift ;;
+    --agent-file)
+      shift
+      if [ "${1:-}" = "" ]; then usage; exit 2; fi
+      AGENT_FILES="${AGENT_FILES}${AGENT_FILES:+
+}$1"
+      shift
+      ;;
+    --log-file)
+      shift
+      if [ "${1:-}" = "" ]; then usage; exit 2; fi
+      LOG_FILE="$1"
+      shift
+      ;;
+    --help|-h) usage; exit 0 ;;
+    --) shift; break ;;
+    -*) usage; exit 2 ;;
+    *) NOTE="${NOTE}${NOTE:+ }$1"; shift ;;
+  esac
+done
+
+SCRIPT_PATH="$0"
+case "$SCRIPT_PATH" in
+  */*) : ;;
+  *) SCRIPT_PATH="$(command -v "$SCRIPT_PATH" 2>/dev/null || printf '%s' "$SCRIPT_PATH")" ;;
+esac
+
+ORP_ROOT="$(cd "$(dirname "$SCRIPT_PATH")/.." && pwd)"
+cd "$ORP_ROOT"
+
+if [ "$LOG_FILE" = "" ]; then
+  LOG_FILE="$ORP_ROOT/cone/CONTEXT_LOG.md"
+fi
+
+timestamp_utc="$(date -u "+%Y-%m-%dT%H:%M:%SZ")"
+
+git_inside="0"
+git_root=""
+git_branch=""
+git_head=""
+staged_count="0"
+unstaged_count="0"
+untracked_count="0"
+
+if git_root="$(git rev-parse --show-toplevel 2>/dev/null)"; then
+  git_inside="1"
+  git_branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+  git_head="$(git rev-parse --short HEAD 2>/dev/null || true)"
+  status="$(git status --porcelain=v1 2>/dev/null || true)"
+  if [ "$status" != "" ]; then
+    staged_count="$(printf '%s\n' "$status" | awk 'substr($0,1,2)!="??" && substr($0,1,1)!=" " {c++} END{print c+0}')"
+    unstaged_count="$(printf '%s\n' "$status" | awk 'substr($0,1,2)!="??" && substr($0,2,1)!=" " {c++} END{print c+0}')"
+    untracked_count="$(printf '%s\n' "$status" | awk 'substr($0,1,2)=="??" {c++} END{print c+0}')"
+  fi
+fi
+
+last_checkpoint="(none)"
+if [ -f "$LOG_FILE" ]; then
+  last_line="$(awk '/^## Checkpoint — /{x=$0} END{print x}' "$LOG_FILE")"
+  if [ "${last_line:-}" != "" ]; then
+    last_checkpoint="${last_line#\#\# Checkpoint — }"
+  fi
+fi
+
+echo "ORP root: $ORP_ROOT"
+echo "Checkpoint log: $LOG_FILE"
+echo "Last checkpoint: $last_checkpoint"
+if [ "$git_inside" = "1" ]; then
+  echo "Git: branch=$git_branch head=$git_head staged=$staged_count unstaged=$unstaged_count untracked=$untracked_count"
+else
+  echo "Git: (not a git repo)"
+fi
+
+orp_check_status="skipped"
+orp_check_exit="0"
+agent_checked=""
+
+if [ "$AGENT_FILES" != "" ]; then
+  orp_check_status="PASS"
+  agent_checked="$(printf '%s' "$AGENT_FILES" | tr '\n' ' ')"
+  while IFS= read -r f; do
+    [ "$f" = "" ] && continue
+    if [ "$DO_SYNC" = "1" ]; then
+      "$ORP_ROOT/scripts/orp-agent-integrate.sh" --sync "$f" >/dev/null
+    fi
+    if "$ORP_ROOT/scripts/orp-agent-integrate.sh" --check "$f" >/dev/null; then
+      :
+    else
+      orp_check_status="FAIL"
+      orp_check_exit="1"
+    fi
+  done <<EOF
+$AGENT_FILES
+EOF
+fi
+
+echo "ORP snippet sync: $orp_check_status"
+
+if [ "$MODE" = "status" ]; then
+  exit 0
+fi
+
+if [ "$MODE" = "check" ]; then
+  exit "$orp_check_exit"
+fi
+
+mkdir -p "$(dirname "$LOG_FILE")"
+if [ ! -f "$LOG_FILE" ]; then
+  cat >"$LOG_FILE" <<'EOF'
+# 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.
+EOF
+  printf '\n' >> "$LOG_FILE"
+fi
+
+{
+  echo
+  echo "## Checkpoint — $timestamp_utc"
+  echo "- Note: ${NOTE:-}"
+  echo "- Repo state:"
+  if [ "$git_inside" = "1" ]; then
+    echo "  - Branch: $git_branch"
+    echo "  - Head: $git_head"
+    echo "  - Git status: staged=$staged_count, unstaged=$unstaged_count, untracked=$untracked_count"
+  else
+    echo "  - Branch:"
+    echo "  - Head:"
+    echo "  - Git status: staged=?, unstaged=?, untracked=?"
+  fi
+  echo "- ORP snippet sync:"
+  echo "  - Agent instruction files checked: ${agent_checked:-}"
+  echo "  - Result: $orp_check_status"
+  echo "- Canonical artifacts touched (paths only):"
+  echo "- Next hook:"
+} >> "$LOG_FILE"
+
+echo "Wrote checkpoint entry."
+
+exit "$orp_check_exit"
+