open-research-protocol 0.4.25 → 0.4.27

package/AGENT_INTEGRATION.md

@@ -40,20 +40,24 @@ If the agent only remembers one ORP loop, it should be this:
    ```bash
    orp status --json
    ```
-3. resolve the right secret
+3. classify dirty worktree state before expansion
+   ```bash
+   orp hygiene --json
+   ```
+4. resolve the right secret
    ```bash
    orp secrets ensure --alias <alias> --provider <provider> --current-project --json
    ```
-4. inspect the current frontier
+5. inspect the current frontier
    ```bash
    orp frontier state --json
    ```
-5. if the work feels confusing or too large, break it down before moving
+6. if the work feels confusing or too large, break it down before moving
    ```bash
    orp mode breakdown granular-breakdown --json
    ```
-6. do the next honest move
-7. checkpoint it honestly
+7. do the next honest move
+8. checkpoint it honestly
    ```bash
    orp checkpoint create -m "checkpoint note" --json
    ```
@@ -62,6 +66,7 @@ That is the ORP rhythm in one line:
 
 - recover continuity
 - inspect repo safety
+- classify dirty state and stop if anything is unowned
 - resolve access
 - inspect context
 - break down complexity when comprehension would help
@@ -98,6 +103,11 @@ artifact paths (code/data/proofs/logs/papers).
 - Treat **failed paths** as assets: record dead ends as a `Failed Path Record` with the blocking reason/counterexample and a
   next hook.
 - Resolve disputes by **verification or downgrade**, not argument.
+- Run `orp hygiene --json` before long delegation, after material writeback, before API/remote/paid compute, and when dirty
+  state grows unexpectedly.
+- Stop long-running expansion while hygiene reports `dirty_unclassified`; classify, refresh generated surfaces, canonicalize
+  useful scratch, or write a blocker before continuing.
+- Hygiene is non-destructive: never reset, checkout, or delete files merely to hide dirty state.
 
 ### How to work in an ORP repo
 

package/CHANGELOG.md

@@ -6,6 +6,66 @@ There was no prior in-repo changelog file, so the first formal entry starts
 with the currently shipped `v0.4.4` release and summarizes the full release
 delta reflected in this repo.
 
+## v0.4.27 - 2026-04-18
+
+This release adds a staged OpenAI research profile and default-on worktree
+hygiene for agent loops. ORP-initialized repos now teach agents when to stop,
+classify dirty paths, refresh generated surfaces, canonicalize scratch, or
+write a blocker instead of letting unowned worktree state become invisible.
+
+### Added
+
+- Added the built-in `deep-think-web-think-deep` research profile: Deep
+  Research, high-reasoning think, think plus web synthesis, high-reasoning
+  think, and a final Deep Research pass.
+- Added profile listing/show commands and MCP exposure so Codex-like clients
+  can discover staged research templates and fill project-specific fields.
+- Added `orp hygiene --json` and the `orp workspace hygiene --json` alias for
+  non-destructive worktree classification with dirty counts, categories,
+  unclassified and scratch counts, required action, and recommended next checks.
+- Added `orp/hygiene-policy.json` scaffolding during `orp init` so each project
+  can customize canonical surfaces, artifact roots, scratch paths, and
+  classification rules.
+
+### Changed
+
+- Updated ORP agent docs, generated handoffs, agent policy, project context,
+  home/about metadata, and workspace help to include the hygiene stop rule:
+  no long-running expansion while dirty paths are unclassified.
+- Research runs now persist generated lane prompts and can pass prior lane
+  outputs into later staged prompts while skipping live later-stage calls when
+  prerequisites are incomplete.
+
+## v0.4.26 - 2026-04-17
+
+This release adds ORP-native project context and OpenAI research-loop support,
+so agents can initialize a directory, keep its operating lens refreshed, and
+use explicit high-reasoning or web-synthesis API calls only when the local
+loop needs them.
+
+### Added
+
+- Added `orp project refresh` and `orp project show` for `orp/project.json`,
+  a process-only project context lens that records authority surfaces,
+  directory signals, evolution policy, and research call timing.
+- Added `orp research ask`, `orp research status`, and `orp research show` for
+  durable OpenAI research runs with dry-run planning by default and explicit
+  `--execute` live calls.
+- Added a tiny `scripts/orp-mcp` stdio wrapper exposing the research commands
+  as MCP tools for Codex-like clients.
+- Added versioned schemas for research runs and project context artifacts.
+- Added `orp secrets keychain-add` so users can save a local machine OpenAI key
+  or other provider credential without relying on hosted secret storage.
+
+### Changed
+
+- Updated `orp init`, `orp status`, `orp about`, and `orp home` to expose the
+  project context lifecycle as a first-class ORP surface.
+- Documented the research timing rule: decompose locally first, call high
+  reasoning for ambiguous decision gates, call web synthesis for current public
+  facts and citations, and reserve Deep Research for heavier source conflicts
+  or literature-scale synthesis.
+
 ## v0.4.25 - 2026-04-16
 
 This release strengthens ORP continuation handling for long-running delegated

package/README.md

@@ -307,7 +307,7 @@ The practical model is:
 
 ## Secrets Quick Start
 
-Today, ORP secrets use the hosted ORP secret inventory as the canonical store, with optional local macOS Keychain caching. That means the real first step for secrets is:
+ORP secrets can live in the hosted ORP secret inventory, with optional local macOS Keychain caching, or directly in the local ORP Keychain registry when you need a machine-local store immediately. For hosted secrets, start with:
 
 ```bash
 orp auth login
@@ -335,6 +335,18 @@ For an agent or script, use stdin:
 printf '%s' 'sk-...' | orp secrets add --alias openai-primary --label "OpenAI Primary" --provider openai --value-stdin
 ```
 
+For a local-only machine secret, use the ORP Keychain path:
+
+```bash
+printf '%s' 'sk-...' | orp secrets keychain-add --alias openai-primary --label "OpenAI Primary" --provider openai --env-var-name OPENAI_API_KEY --value-stdin
+```
+
+If the key is already in the current process environment:
+
+```bash
+orp secrets keychain-add --alias openai-primary --label "OpenAI Primary" --provider openai --env-var-name OPENAI_API_KEY --from-env
+```
+
 If a service needs both a username and a secret, store the username with it:
 
 ```bash
@@ -376,6 +388,7 @@ For secrets, the simplest plain-English rule is:
 - `orp secrets show ...` = inspect one saved key record
 - `orp secrets resolve ...` = get the key value for use right now
 - `orp secrets ensure ...` = use the saved key if it exists, otherwise create it
+- `orp secrets keychain-add ...` = save or update a machine-local ORP secret in macOS Keychain
 - `orp secrets sync-keychain ...` = keep a secure local Mac copy too
 
 You can ignore `--env-var-name` at first. It is optional metadata like `OPENAI_API_KEY`, not the key itself.
@@ -444,6 +457,7 @@ orp workspace remove-tab main --path /absolute/path/to/project
 orp workspace sync main
 orp secrets list --json
 orp secrets ensure --alias openai-primary --provider openai --current-project --json
+orp secrets keychain-add --alias openai-primary --provider openai --env-var-name OPENAI_API_KEY --value-stdin --json
 orp secrets sync-keychain openai-primary --json
 orp schedule add codex --name morning-summary --prompt "Summarize this repo" --json
 ```
@@ -530,6 +544,7 @@ The bridge package lives at `packages/lifeops-orp/`.
 Stable artifact paths:
 
 - `orp/state.json`
+- `orp/project.json`
 - `orp/artifacts/<run_id>/RUN.json`
 - `orp/artifacts/<run_id>/RUN_SUMMARY.md`
 - `orp/packets/<packet_id>.json`
@@ -542,26 +557,28 @@ Stable artifact paths:
 1. Copy this folder into your repo (recommended location: `orp/`).
 2. Link to `orp/PROTOCOL.md` from your repo `README.md`.
 3. Customize **Canonical Paths** inside `orp/PROTOCOL.md` to match your repo layout.
-4. Run `orp init` in the repo root to establish ORP governance.
+4. Run `orp init` in the repo root to establish ORP governance and create `orp/project.json`.
 5. If you keep many repos under one umbrella directory, run `orp agents root set /absolute/path/to/projects` once and let `orp init --projects-root /absolute/path/to/projects` link each child repo back to that parent guidance.
 6. Use `orp agents audit` whenever you want to confirm `AGENTS.md` and `CLAUDE.md` are still aligned without overwriting human notes.
-7. Use `orp status`, `orp branch start`, `orp checkpoint create`, and `orp backup` as the default implementation loop.
-8. Use the templates for all new claims and verifications.
-9. Optional (agent users): integrate ORP into your agent’s primary instruction file (see `orp/AGENT_INTEGRATION.md`).
+7. Use `orp project refresh --json` after adding or changing roadmap, spec, agent-guidance, docs, manifest, or command-surface files.
+8. Use `orp status`, `orp branch start`, `orp checkpoint create`, and `orp backup` as the default implementation loop.
+9. Use the templates for all new claims and verifications.
+10. Optional (agent users): integrate ORP into your agent’s primary instruction file (see `orp/AGENT_INTEGRATION.md`).
 
 ## Quick start (new project)
 
 1. Copy this folder into a new project directory.
 2. If you keep projects under one umbrella directory, run `orp agents root set /absolute/path/to/projects` once from anywhere.
-3. Run `orp init` immediately so the repo starts ORP-governed and scaffolds or updates `AGENTS.md` and `CLAUDE.md`.
+3. Run `orp init` immediately so the repo starts ORP-governed, scaffolds or updates `AGENTS.md` and `CLAUDE.md`, and creates `orp/project.json`.
 4. Edit `PROTOCOL.md` to define your canonical paths and claim labels.
-5. Run `orp agents audit` to confirm the repo-level agent files are aligned and still preserving human notes.
-6. Start implementation on a work branch with `orp branch start`.
-7. Create regular checkpoint commits with `orp checkpoint create`.
-8. Use `orp backup` whenever you want ORP to capture current work to a dedicated remote backup ref.
-9. Validate promotable task/decision/hypothesis artifacts with `orp kernel validate <path> --json`.
-10. Start by adding one small claim + verification record using the templates.
-11. Optional (agent users): integrate ORP into your agent’s primary instruction file (see `AGENT_INTEGRATION.md`).
+5. Run `orp project refresh --json` whenever the directory gains new roadmap, spec, docs, manifest, or command-surface files.
+6. Run `orp agents audit` to confirm the repo-level agent files are aligned and still preserving human notes.
+7. Start implementation on a work branch with `orp branch start`.
+8. Create regular checkpoint commits with `orp checkpoint create`.
+9. Use `orp backup` whenever you want ORP to capture current work to a dedicated remote backup ref.
+10. Validate promotable task/decision/hypothesis artifacts with `orp kernel validate <path> --json`.
+11. Start by adding one small claim + verification record using the templates.
+12. Optional (agent users): integrate ORP into your agent’s primary instruction file (see `AGENT_INTEGRATION.md`).
 
 **Activation is procedural/social, not runtime:** nothing “turns on” automatically. ORP works only if contributors follow it.
 

package/bin/orp.js

@@ -36,24 +36,14 @@ async function runWorkspace(args) {
   process.exit(code == null ? 0 : code);
 }
 
-async function main() {
-  if (argv[0] === "compute") {
-    await runCompute(argv.slice(1));
-    return;
-  }
-  if (argv[0] === "workspace") {
-    await runWorkspace(argv.slice(1));
-    return;
-  }
-
-  const captureOutput = isTopLevelHelp(argv);
+function runPythonCli(args, { captureOutput }) {
   let lastErr = null;
 
   for (const py of candidates) {
-    const args = py === "py" ? ["-3", cliPath, ...argv] : [cliPath, ...argv];
+    const pyArgs = py === "py" ? ["-3", cliPath, ...args] : [cliPath, ...args];
     const result = spawnSync(
       py,
-      args,
+      pyArgs,
       captureOutput
         ? { encoding: "utf8" }
         : { stdio: "inherit" },
@@ -68,7 +58,7 @@ async function main() {
           process.stderr.write(result.stderr);
         }
         if (result.status === 0) {
-          process.stdout.write("\nAdditional wrapper surface:\n  orp compute -h\n  orp workspace tabs -h\n");
+          process.stdout.write("\nAdditional wrapper surface:\n  orp compute -h\n  orp workspace tabs -h\n  orp workspace hygiene --json\n");
         }
       }
       process.exit(result.status == null ? 1 : result.status);
@@ -88,6 +78,23 @@ async function main() {
   process.exit(1);
 }
 
+async function main() {
+  if (argv[0] === "compute") {
+    await runCompute(argv.slice(1));
+    return;
+  }
+  if (argv[0] === "workspace" && argv[1] === "hygiene") {
+    runPythonCli(["hygiene", ...argv.slice(2)], { captureOutput: false });
+    return;
+  }
+  if (argv[0] === "workspace") {
+    await runWorkspace(argv.slice(1));
+    return;
+  }
+
+  runPythonCli(argv, { captureOutput: isTopLevelHelp(argv) });
+}
+
 main().catch((error) => {
   console.error(String(error && error.stack ? error.stack : error));
   process.exit(1);