open-research-protocol 0.4.26 → 0.4.27

package/docs/AGENT_LOOP.md

@@ -12,6 +12,11 @@ read:
 
 - Read `llms.txt`.
 - Run `orp about --json`.
+- Run `orp hygiene --json` before long delegation, after material writeback,
+  before API/remote/paid compute, and whenever dirty state grows unexpectedly.
+  If it reports `dirty_unclassified`, stop long-running expansion and classify
+  the paths, refresh generated surfaces, canonicalize useful scratch, or write a
+  blocker before continuing.
 - If the task benefits from fresh concepting, tasteful interface work, or
   exploratory reframing, run:
   - `orp mode nudge sleek-minimal-progressive --json`
@@ -32,6 +37,10 @@ read:
 ## 2. Select Work
 
 - Identify the target profile and canonical artifact paths.
+- Treat worktree hygiene as a default-on self-healing loop. Dirty state is okay
+  when it is owned; invisible or unclassified dirt is not. The command is
+  non-destructive, so never reset, checkout, or delete files merely to make the
+  report look clean.
 - If the task depends on the current highest-leverage action slice, refresh ORP's agenda first:
   - `orp agenda refresh --json`
   - `orp agenda refresh-status --json`

package/docs/RESEARCH_COUNCIL.md

@@ -28,6 +28,52 @@ The built-in `openai-council` profile defines three OpenAI API lanes:
 
 This follows OpenAI's current model guidance: `gpt-5.4` is the default for general-purpose, coding, reasoning, and agentic workflows; web search is enabled through the Responses API `tools` array when current information is needed; and Deep Research is available through the Responses endpoint with `o3-deep-research-2025-06-26`.
 
+## Staged Deep Research Template
+
+ORP also includes a built-in `deep-think-web-think-deep` profile for a strict sequence:
+
+```text
+Deep Research -> think -> think/web search -> think -> Deep Research
+```
+
+Inspect the template before using it:
+
+```bash
+orp research profile show deep-think-web-think-deep --json
+```
+
+Run a dry plan with form-like fields filled by a human or an agent:
+
+```bash
+orp research ask "Should this product use a staged research loop?" \
+  --profile deep-think-web-think-deep \
+  --field goal="Decide whether to adopt the staged loop" \
+  --field audience="Platform team" \
+  --field decision_to_support="Choose the default research workflow" \
+  --field project_context="ORP owns durable artifacts and secret resolution" \
+  --field constraints="Use one OpenAI API key first" \
+  --field deliverable_format="Decision memo with risks and next steps" \
+  --json
+```
+
+The prompt form is intentionally general. It gives an agent a reusable customization surface, similar to filling out a product intake form for a company:
+
+- `goal`
+- `audience`
+- `decision_to_support`
+- `project_context`
+- `constraints`
+- `known_inputs`
+- `source_preferences`
+- `recency_requirements`
+- `excluded_assumptions`
+- `success_criteria`
+- `deliverable_format`
+
+Dry runs persist the generated prompt for every lane under `orp/research/<run_id>/lanes/`. Later lanes include earlier lane outputs when those outputs exist, whether they came from live calls or `--lane-fixture` files. This makes the sequence inspectable before spending live provider calls. In live mode, later staged lanes skip their provider call if an earlier required lane did not complete with text.
+
+The staged profile keeps Deep Research foreground by default so the next lane can receive actual output. Deep Research can take a long time; pass a larger `--timeout-sec` for live runs or provide a custom profile file that sets `background=true` if you want asynchronous Deep Research behavior.
+
 ## API Call Moments
 
 ORP records when API keys are intended to be used:
@@ -117,6 +163,8 @@ command = "/path/to/orp/scripts/orp-mcp"
 It exposes:
 
 - `orp_research_ask`
+- `orp_research_profile_list`
+- `orp_research_profile_show`
 - `orp_research_status`
 - `orp_research_show`
 

package/docs/START_HERE.md

@@ -739,6 +739,7 @@ The guiding rule is simple:
 
 - recover the saved workspace
 - inspect repo safety
+- classify dirty state before expansion
 - resolve the right secret
 - inspect the current frontier
 - do the next honest move
@@ -756,16 +757,20 @@ If you only want the irreducible ORP loop, it is 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. do the next honest move
-6. checkpoint it
+6. do the next honest move
+7. checkpoint it
    ```bash
    orp checkpoint create -m "describe completed unit" --json
    ```
@@ -774,6 +779,7 @@ That is the shortest version of the protocol:
 
 - recover continuity
 - inspect safety
+- classify dirty state
 - resolve access
 - inspect context
 - do the work
@@ -786,6 +792,7 @@ If you want the agent to stay aligned with ORP, the default check sequence shoul
 ```bash
 orp workspace tabs main
 orp status --json
+orp hygiene --json
 orp secrets ensure --alias <alias> --provider <provider> --current-project --json
 orp frontier state --json
 ```
@@ -800,17 +807,18 @@ That is the practical ORP loop:
 
 1. recover the workspace ledger
 2. inspect repo safety
-3. resolve the right key
-4. inspect the current frontier
-5. do the work
-6. checkpoint it honestly
+3. classify dirty state and stop if anything is unowned
+4. resolve the right key
+5. inspect the current frontier
+6. do the work
+7. checkpoint it honestly
 
 The key point is that ORP should become the lens:
 
 - not "something we remember to use sometimes"
 - but the operating frame the agent checks before and after meaningful work
 
-## If You Only Remember 8 Commands
+## If You Only Remember 9 Commands
 
 ```bash
 orp home
@@ -818,6 +826,7 @@ orp init
 orp workspace create main-cody-1
 orp workspace tabs main
 orp workspace add-tab main --path /absolute/path/to/project --resume-command "codex resume <id>"
+orp hygiene --json
 orp secrets ensure --alias openai-primary --provider openai --current-project --json
 orp status --json
 orp checkpoint create -m "capture loop state" --json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-research-protocol",
-  "version": "0.4.26",
+  "version": "0.4.27",
   "description": "ORP CLI (Open Research Protocol): workspace ledgers, secrets, scheduling, governed execution, and agent-friendly research workflows.",
   "license": "MIT",
   "author": "Fractal Research Group <cody@frg.earth>",

package/packages/orp-workspace-launcher/src/orp-command.js

@@ -1,9 +1,55 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
 import { runWorkspaceAddTab, runWorkspaceCreate, runWorkspaceRemoveTab } from "./ledger.js";
 import { runWorkspaceList } from "./list.js";
 import { runWorkspaceSlot } from "./slot.js";
 import { runWorkspaceSync } from "./sync.js";
 import { runWorkspaceTabs } from "./tabs.js";
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pythonCliPath = path.resolve(__dirname, "..", "..", "..", "cli", "orp.py");
+
+function pythonCandidates() {
+  const candidates = [];
+  if (process.env.ORP_PYTHON && process.env.ORP_PYTHON.trim() !== "") {
+    candidates.push(process.env.ORP_PYTHON.trim());
+  }
+  if (process.platform === "win32") {
+    candidates.push("py");
+  }
+  candidates.push("python3", "python");
+  return candidates;
+}
+
+function runWorkspaceHygiene(args = []) {
+  let lastErr = null;
+  for (const py of pythonCandidates()) {
+    const pyArgs = py === "py" ? ["-3", pythonCliPath, "hygiene", ...args] : [pythonCliPath, "hygiene", ...args];
+    const result = spawnSync(py, pyArgs, { encoding: "utf8" });
+    if (!result.error) {
+      if (result.stdout) {
+        process.stdout.write(result.stdout);
+      }
+      if (result.stderr) {
+        process.stderr.write(result.stderr);
+      }
+      return result.status == null ? 1 : result.status;
+    }
+    if (result.error && result.error.code === "ENOENT") {
+      continue;
+    }
+    lastErr = result.error;
+  }
+  process.stderr.write("ORP workspace hygiene requires Python 3 on PATH.\n");
+  process.stderr.write("Tried: " + pythonCandidates().join(", ") + "\n");
+  if (lastErr) {
+    process.stderr.write(String(lastErr) + "\n");
+  }
+  return 1;
+}
+
 function printWorkspaceHelp() {
   console.log(`ORP workspace
 
@@ -18,6 +64,7 @@ Usage:
   orp workspace remove-tab <name-or-id> (--index <n> | --path <absolute-path> | --title <title> | --resume-session-id <id> | --resume-command <text>) [--all] [--json]
   orp workspace slot <list|set|clear> ...
   orp workspace sync <name-or-id> [--workspace-file <path> | --notes-file <path>] [--dry-run] [--json]
+  orp workspace hygiene [--json]
   orp workspace ledger <name-or-id> [--json]
   orp workspace ledger add <name-or-id> (--path <absolute-path> | --here) [--title <title>] [--remote-url <git-url>] [--remote-branch <branch>] [--bootstrap-command <text>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id> | --current-codex] [--append] [--json]
   orp workspace ledger remove <name-or-id> (--index <n> | --path <absolute-path> | --title <title> | --resume-session-id <id> | --resume-command <text>) [--all] [--json]
@@ -31,6 +78,7 @@ Commands:
   remove-tab Remove one or more saved tabs from the workspace ledger directly
   slot    Assign and inspect named workspace slots like main and offhand
   sync    Post a CLI-authored workspace manifest back to the hosted ORP idea
+  hygiene Classify dirty worktree paths before long agent expansion
   ledger  Compatibility alias for the same tabs/add/remove ledger flow
 
 Notes:
@@ -41,6 +89,7 @@ Notes:
   - Use \`orp workspace add-tab ... --remote-url ... --bootstrap-command ...\` when you want ORP to remember how to recreate the repo on another machine.
   - Use \`orp workspace add-tab ...\` and \`orp workspace remove-tab ...\` when you want to edit the saved workspace ledger explicitly from Terminal.app or any other shell.
   - If you prefer the older ledger-prefixed wording, \`orp workspace ledger\`, \`orp workspace ledger add\`, and \`orp workspace ledger remove\` stay available as aliases.
+  - \`orp workspace hygiene --json\` is a wrapper alias for \`orp hygiene --json\`; it reports dirty path categories without resetting, checking out, or deleting files.
   - \`main\` and \`offhand\` are reserved slot selectors; use \`orp workspace slot set ...\` to assign them.
   - Syncing or editing a hosted workspace writes a managed local cache on this Mac.
   - \`<name-or-id>\` can be a saved workspace title, workspace id, idea id, or local tracked workspace title/id.
@@ -51,6 +100,7 @@ Examples:
   orp workspace create mac-main --machine-label "Mac Studio" --path /absolute/path/to/orp --remote-url git@github.com:SproutSeeds/orp.git --bootstrap-command "npm install"
   orp workspace list
   orp workspace tabs main-cody-1
+  orp workspace hygiene --json
   orp workspace add-tab main --here --current-codex
   orp workspace add-tab main --path /absolute/path/to/new-project --resume-command "codex resume 019d..."
   orp workspace add-tab main --path /absolute/path/to/new-project --remote-url git@github.com:org/new-project.git --bootstrap-command "npm install"
@@ -126,5 +176,9 @@ export async function runOrpWorkspaceCommand(argv = []) {
     return runWorkspaceSync(rest);
   }
 
+  if (subcommand === "hygiene") {
+    return runWorkspaceHygiene(rest);
+  }
+
   throw new Error(`unknown workspace subcommand: ${subcommand}`);
 }

package/packages/orp-workspace-launcher/test/orp-command.test.js

@@ -38,6 +38,7 @@ test("runOrpWorkspaceCommand shows the ledger-first help surface", async () => {
   assert.match(stdout, /orp workspace ledger add <name-or-id>/);
   assert.match(stdout, /orp workspace ledger remove <name-or-id>/);
   assert.match(stdout, /orp workspace tabs <name-or-id>/);
+  assert.match(stdout, /orp workspace hygiene \[--json\]/);
   assert.match(stdout, /Compatibility alias for the same tabs\/add\/remove ledger flow/);
 });
 

package/scripts/orp-mcp

@@ -25,6 +25,11 @@ TOOLS: list[dict[str, Any]] = [
                 "run_id": {"type": "string"},
                 "profile": {"type": "string", "default": "openai-council"},
                 "profile_file": {"type": "string"},
+                "fields": {
+                    "type": "object",
+                    "description": "Prompt-template fields passed as key/value pairs.",
+                    "additionalProperties": {"type": "string"},
+                },
                 "execute": {"type": "boolean", "default": False},
                 "lane_fixtures": {
                     "type": "object",
@@ -32,7 +37,28 @@ TOOLS: list[dict[str, Any]] = [
                     "additionalProperties": {"type": "string"},
                 },
                 "chimera_bin": {"type": "string", "default": "chimera"},
-                "timeout_sec": {"type": "integer", "minimum": 1, "default": 120},
+                "timeout_sec": {"type": "integer", "minimum": 1, "description": "Override the profile per-lane timeout policy."},
+            },
+        },
+    },
+    {
+        "name": "orp_research_profile_list",
+        "description": "List built-in ORP research profiles and prompt-template surfaces.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "repo_root": {"type": "string", "description": "Repository root. Defaults to current directory."},
+            },
+        },
+    },
+    {
+        "name": "orp_research_profile_show",
+        "description": "Show a built-in ORP research profile, including its lane sequence and prompt form.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "repo_root": {"type": "string", "description": "Repository root. Defaults to current directory."},
+                "profile_id": {"type": "string", "default": "openai-council"},
             },
         },
     },
@@ -111,6 +137,10 @@ def _call_research_ask(args: dict[str, Any]) -> dict[str, Any]:
     run_id = str(args.get("run_id", "") or "").strip()
     if run_id:
         cmd.extend(["--run-id", run_id])
+    fields = args.get("fields")
+    if isinstance(fields, dict):
+        for key, value in fields.items():
+            cmd.extend(["--field", f"{key}={value}"])
     if bool(args.get("execute", False)):
         cmd.append("--execute")
     lane_fixtures = args.get("lane_fixtures")
@@ -130,6 +160,23 @@ def _call_research_ask(args: dict[str, Any]) -> dict[str, Any]:
     return _text_result(stdout.strip())
 
 
+def _call_research_profile_list(args: dict[str, Any]) -> dict[str, Any]:
+    cmd = ["--repo-root", _repo_root(args), "research", "profile", "list", "--json"]
+    code, stdout, stderr = _run_orp(cmd)
+    if code != 0:
+        return _text_result((stderr or stdout or f"orp exited {code}").strip(), is_error=True)
+    return _text_result(stdout.strip())
+
+
+def _call_research_profile_show(args: dict[str, Any]) -> dict[str, Any]:
+    profile_id = str(args.get("profile_id", "") or "openai-council").strip() or "openai-council"
+    cmd = ["--repo-root", _repo_root(args), "research", "profile", "show", profile_id, "--json"]
+    code, stdout, stderr = _run_orp(cmd)
+    if code != 0:
+        return _text_result((stderr or stdout or f"orp exited {code}").strip(), is_error=True)
+    return _text_result(stdout.strip())
+
+
 def _call_research_status(args: dict[str, Any]) -> dict[str, Any]:
     run_id = str(args.get("run_id", "") or "latest").strip() or "latest"
     cmd = ["--repo-root", _repo_root(args), "research", "status", run_id, "--json"]
@@ -174,6 +221,10 @@ def _handle(request: dict[str, Any]) -> dict[str, Any] | None:
             arguments = {}
         if name == "orp_research_ask":
             return _json_response(request_id, _call_research_ask(arguments))
+        if name == "orp_research_profile_list":
+            return _json_response(request_id, _call_research_profile_list(arguments))
+        if name == "orp_research_profile_show":
+            return _json_response(request_id, _call_research_profile_show(arguments))
         if name == "orp_research_status":
             return _json_response(request_id, _call_research_status(arguments))
         if name == "orp_research_show":