Refactor CLI root flag boundaries

.github/workflows/devflow-contract.yml

@@ -40,4 +40,4 @@ jobs:
       - run: uv sync --locked
       - run: uv run python -m compileall -q src tests
       - run: uv run --locked pytest -q -m devflow
-      - run: uv run clawops devflow plan --repo-root . --goal "contract smoke"
+      - run: uv run clawops devflow plan --project-root . --goal "contract smoke"

.github/workflows/memory-plugin-verification.yml

@@ -36,7 +36,7 @@ jobs:
           version: "0.10.9"
           enable-cache: true
       - run: uv sync --locked
-      - run: PYTHONPATH=src uv run python -m clawops config --repo-root . memory --set-profile memory-lancedb-pro --output "$RUNNER_TEMP/openclaw.json"
+      - run: PYTHONPATH=src uv run python -m clawops config --asset-root . memory --set-profile memory-lancedb-pro --output "$RUNNER_TEMP/openclaw.json"
       - run: python3 ./tests/scripts/memory_plugin_verification.py run-vendored-host-checks --repo-root . --package-spec "openclaw@2026.3.13"
   verify-hypermemory-qdrant:
     name: Run Hypermemory Qdrant Checks

README.md

@@ -90,6 +90,13 @@ The wheel now ships the runtime `platform` asset bundle, so package-safe
 commands such as `clawops render-openclaw-config`, `clawops setup`, and
 `clawops verify-platform ...` work outside a cloned StrongClaw checkout.
 
+Boundary override flags are now literal:
+
+- use `--asset-root` only to override the packaged/source runtime asset bundle
+- use `--project-root` for orchestration state surfaces such as `clawops devflow`
+- use `--source-root` for source-tree-only verification such as `clawops baseline`
+- use `--repo-root` only for repo-contract tooling such as `clawops repo`, `clawops worktree`, and `clawops supply-chain`
+
 By default, StrongClaw now renders and provisions the
 `hypermemory` stack. Set one embedding model name before you run
 the no-arg setup path:

platform/docs/DEVFLOW.md

@@ -11,6 +11,9 @@ clawops devflow cancel
 clawops devflow audit
 ```
 
+Use `--project-root <path>` when the control root for run state, journals, and
+audit artifacts is not the current working directory.
+
 ## Operator Flow
 
 Plan a run:

platform/launchd/ai.openclaw.browserlab.plist.template

@@ -10,7 +10,7 @@
       <string>-m</string>
       <string>clawops</string>
       <string>ops</string>
-      <string>--repo-root</string>
+      <string>--asset-root</string>
       <string>__REPO_ROOT__</string>
       <string>browser-lab</string>
       <string>up</string>

platform/launchd/ai.openclaw.gateway.plist.template

@@ -10,7 +10,7 @@
       <string>-m</string>
       <string>clawops</string>
       <string>ops</string>
-      <string>--repo-root</string>
+      <string>--asset-root</string>
       <string>__REPO_ROOT__</string>
       <string>gateway</string>
       <string>start</string>

platform/launchd/ai.openclaw.sidecars.plist.template

@@ -10,7 +10,7 @@
       <string>-m</string>
       <string>clawops</string>
       <string>ops</string>
-      <string>--repo-root</string>
+      <string>--asset-root</string>
       <string>__REPO_ROOT__</string>
       <string>sidecars</string>
       <string>up</string>

platform/systemd/openclaw-browserlab.service

@@ -9,8 +9,8 @@ RemainAfterExit=true
 WorkingDirectory=__REPO_ROOT__
 Environment=OPENCLAW_STATE_DIR=__STATE_DIR__
 Environment=PATH=%h/.config/varlock/bin:%h/.local/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
-ExecStart=__REPO_ROOT__/.venv/bin/python -m clawops ops --repo-root __REPO_ROOT__ browser-lab up
-ExecStop=__REPO_ROOT__/.venv/bin/python -m clawops ops --repo-root __REPO_ROOT__ browser-lab down
+ExecStart=__PYTHON_EXECUTABLE__ -m clawops ops --asset-root __REPO_ROOT__ browser-lab up
+ExecStop=__PYTHON_EXECUTABLE__ -m clawops ops --asset-root __REPO_ROOT__ browser-lab down
 
 [Install]
 WantedBy=default.target

platform/systemd/openclaw-gateway.service

@@ -8,7 +8,7 @@ Type=simple
 WorkingDirectory=__REPO_ROOT__
 Environment=OPENCLAW_STATE_DIR=__STATE_DIR__
 Environment=PATH=%h/.config/varlock/bin:%h/.local/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
-ExecStart=__PYTHON_EXECUTABLE__ -m clawops ops --repo-root __REPO_ROOT__ gateway start
+ExecStart=__PYTHON_EXECUTABLE__ -m clawops ops --asset-root __REPO_ROOT__ gateway start
 Restart=always
 RestartSec=5
 NoNewPrivileges=true

platform/systemd/openclaw-sidecars.service

@@ -9,8 +9,8 @@ RemainAfterExit=true
 WorkingDirectory=__REPO_ROOT__
 Environment=OPENCLAW_STATE_DIR=__STATE_DIR__
 Environment=PATH=%h/.config/varlock/bin:%h/.local/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
-ExecStart=__PYTHON_EXECUTABLE__ -m clawops ops --repo-root __REPO_ROOT__ sidecars up
-ExecStop=__PYTHON_EXECUTABLE__ -m clawops ops --repo-root __REPO_ROOT__ sidecars down
+ExecStart=__PYTHON_EXECUTABLE__ -m clawops ops --asset-root __REPO_ROOT__ sidecars up
+ExecStop=__PYTHON_EXECUTABLE__ -m clawops ops --asset-root __REPO_ROOT__ sidecars down
 
 [Install]
 WantedBy=default.target

src/clawops/acp_runner.py

@@ -19,6 +19,7 @@
 )
 from clawops.app_paths import scoped_state_dir
 from clawops.backend_registry import BackendDefinition, resolve_backend
+from clawops.cli_roots import add_project_root_argument, resolve_project_root_argument
 from clawops.common import dump_json, sha256_hex, write_json, write_text
 from clawops.credential_broker import CredentialBroker, CredentialStatus
 from clawops.op_journal import LeaseConflictError, OperationJournal
@@ -30,7 +31,6 @@
     build_lock_identity,
     build_session_identity,
 )
-from clawops.root_detection import resolve_project_root
 
 
 class SessionLockError(RuntimeError):
@@ -579,12 +579,9 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
     parser.add_argument("--role", default=None)
     parser.add_argument("--lane", default="default")
     parser.add_argument("--operation-kind", default="worker_dispatch")
-    parser.add_argument(
-        "--project-root",
-        "--repo-root",
-        dest="project_root",
-        type=pathlib.Path,
-        default=None,
+    add_project_root_argument(
+        parser,
+        help_text="Control project root for ACP state, journals, and derived worktrees.",
     )
     parser.add_argument("--project-id")
     parser.add_argument(
@@ -611,7 +608,7 @@ def _resolve_session_spec(args: argparse.Namespace) -> SessionSpec:
     """Resolve CLI arguments into a typed session spec."""
     role = args.role or args.session_type or "developer"
     project = ProjectDescriptor.resolve(
-        resolve_project_root(args.project_root),
+        resolve_project_root_argument(args, command_name="clawops acp-runner"),
         project_id=args.project_id,
         trusted_roots=tuple(args.allowed_workspace_root),
     )

src/clawops/assets/platform/docs/DEVFLOW.md

@@ -11,6 +11,9 @@ clawops devflow cancel
 clawops devflow audit
 ```
 
+Use `--project-root <path>` when the control root for run state, journals, and
+audit artifacts is not the current working directory.
+
 ## Operator Flow
 
 Plan a run:

src/clawops/assets/platform/launchd/ai.openclaw.browserlab.plist.template

@@ -10,7 +10,7 @@
       <string>-m</string>
       <string>clawops</string>
       <string>ops</string>
-      <string>--repo-root</string>
+      <string>--asset-root</string>
       <string>__REPO_ROOT__</string>
       <string>browser-lab</string>
       <string>up</string>

src/clawops/assets/platform/launchd/ai.openclaw.gateway.plist.template

@@ -10,7 +10,7 @@
       <string>-m</string>
       <string>clawops</string>
       <string>ops</string>
-      <string>--repo-root</string>
+      <string>--asset-root</string>
       <string>__REPO_ROOT__</string>
       <string>gateway</string>
       <string>start</string>

src/clawops/assets/platform/launchd/ai.openclaw.sidecars.plist.template

@@ -10,7 +10,7 @@
       <string>-m</string>
       <string>clawops</string>
       <string>ops</string>
-      <string>--repo-root</string>
+      <string>--asset-root</string>
       <string>__REPO_ROOT__</string>
       <string>sidecars</string>
       <string>up</string>

src/clawops/assets/platform/systemd/openclaw-browserlab.service

@@ -9,8 +9,8 @@ RemainAfterExit=true
 WorkingDirectory=__REPO_ROOT__
 Environment=OPENCLAW_STATE_DIR=__STATE_DIR__
 Environment=PATH=%h/.config/varlock/bin:%h/.local/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
-ExecStart=__REPO_ROOT__/.venv/bin/python -m clawops ops --repo-root __REPO_ROOT__ browser-lab up
-ExecStop=__REPO_ROOT__/.venv/bin/python -m clawops ops --repo-root __REPO_ROOT__ browser-lab down
+ExecStart=__PYTHON_EXECUTABLE__ -m clawops ops --asset-root __REPO_ROOT__ browser-lab up
+ExecStop=__PYTHON_EXECUTABLE__ -m clawops ops --asset-root __REPO_ROOT__ browser-lab down
 
 [Install]
 WantedBy=default.target

src/clawops/assets/platform/systemd/openclaw-gateway.service

@@ -8,7 +8,7 @@ Type=simple
 WorkingDirectory=__REPO_ROOT__
 Environment=OPENCLAW_STATE_DIR=__STATE_DIR__
 Environment=PATH=%h/.config/varlock/bin:%h/.local/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
-ExecStart=__PYTHON_EXECUTABLE__ -m clawops ops --repo-root __REPO_ROOT__ gateway start
+ExecStart=__PYTHON_EXECUTABLE__ -m clawops ops --asset-root __REPO_ROOT__ gateway start
 Restart=always
 RestartSec=5
 NoNewPrivileges=true

src/clawops/assets/platform/systemd/openclaw-sidecars.service

@@ -9,8 +9,8 @@ RemainAfterExit=true
 WorkingDirectory=__REPO_ROOT__
 Environment=OPENCLAW_STATE_DIR=__STATE_DIR__
 Environment=PATH=%h/.config/varlock/bin:%h/.local/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
-ExecStart=__PYTHON_EXECUTABLE__ -m clawops ops --repo-root __REPO_ROOT__ sidecars up
-ExecStop=__PYTHON_EXECUTABLE__ -m clawops ops --repo-root __REPO_ROOT__ sidecars down
+ExecStart=__PYTHON_EXECUTABLE__ -m clawops ops --asset-root __REPO_ROOT__ sidecars up
+ExecStop=__PYTHON_EXECUTABLE__ -m clawops ops --asset-root __REPO_ROOT__ sidecars down
 
 [Install]
 WantedBy=default.target