orro --help must show the surface it actually has (0.2.25)

README.md

@@ -17,9 +17,9 @@ Today:
 - ORRO is the product and workflow surface for observed run and review.
 - This repository keeps ORRO docs, product boundary, locks, thin wrapper package metadata, assurance contract checks, and integration-surface policy.
 - The runnable `orro` command is ORRO-owned and delegates to witnessd.
-- The ORRO product line is published on PyPI through 0.2.21, while this repository
-  packages the 0.2.24 release candidate. The post-release target state is: `orro`
-  0.2.24 is published on PyPI. It becomes true only after `v0.2.24` is tagged and
+- The ORRO product line is published on PyPI through 0.2.24, while this repository
+  packages the 0.2.25 release candidate. The post-release target state is: `orro`
+  0.2.25 is published on PyPI. It becomes true only after `v0.2.25` is tagged and
   the Trusted-Publishing workflow completes. Until then, a normal
   `pip install orro` installs the latest published product-line release.
 - The local wrapper package exposes both `orro` and `orro-wrapper`.
@@ -33,7 +33,7 @@ Current focus:
 ## Can I use ORRO today?
 
 Yes. The published ORRO product line is installable from PyPI; see Current Status
-for the latest published version. Development dogfood can run the 0.2.24 source
+for the latest published version. Development dogfood can run the 0.2.25 source
 directly against pinned Depone and witnessd checkouts.
 
 Current split:
@@ -74,7 +74,7 @@ migration.
 Current command source: the `orro` command is exposed by this ORRO package and
 delegates to `python -m orro`.
 
-The 0.2.24 package metadata declares `witnessd>=2.40.0,<3.0.0` while keeping Depone and
+The 0.2.25 package metadata declares `witnessd>=2.40.0,<3.0.0` while keeping Depone and
 witnessd as separate engine repositories.
 
 ## Pinned Engine E2E
@@ -98,9 +98,9 @@ Engine-lock update discipline is documented in
 [`docs/engine-lock-update-process.md`](docs/engine-lock-update-process.md), and
 validated engine pairs are listed in
 [`docs/compatibility-matrix.md`](docs/compatibility-matrix.md). The published PyPI
-version is documented in Current Status; this repository sources 0.2.24,
+version is documented in Current Status; this repository sources 0.2.25,
 whose publication will be completed as a separate release step after the
-`v0.2.24` tag triggers the
+`v0.2.25` tag triggers the
 Trusted-Publishing workflow. Repository metadata changes do not publish or
 rewrite an artifact.
 
@@ -137,7 +137,7 @@ not assurance.
 
 The current command source is the ORRO-owned `orro` console script. The published
 PyPI version is documented in Current Status, and this repository prepares source
-version 0.2.24 with a `witnessd>=2.40.0,<3.0.0` dependency. The wrapper contains no
+version 0.2.25 with a `witnessd>=2.40.0,<3.0.0` dependency. The wrapper contains no
 engine code and must not
 implement proofrun, proofcheck, scheduler, observer, fan-in, team-ledger, or
 verifier logic.
@@ -241,6 +241,10 @@ orro boundary
 orro-wrapper self-test
 ```
 
+The installed `orro` console script is the only supported operator entrypoint.
+Do not use `uv run python3 -m orro`: ambient uv project discovery can select an
+unrelated environment and produce a misleading `No module named orro` error.
+
 The wrapper is product/distribution metadata and a thin delegation surface. It
 is not proof, not verifier truth, not package publish, not approval, and not
 assurance.

docs/bootstrap.md

@@ -94,10 +94,10 @@ that the installed metadata points to `orro_wrapper.cli:main`, `orro boundary`
 reports `contains_engine_logic: false`, `orro flowplan --help` delegates to
 witnessd, and both `orro-wrapper` and `python -m orro` remain usable.
 
-The post-release target state is: `orro` 0.2.24 is published on PyPI. It becomes
-true only after `v0.2.24` is tagged and the Trusted-Publishing workflow completes;
-until then, PyPI contains the ORRO product line through 0.2.22. This repository is
-the canonical 0.2.24 source, whose metadata declares `witnessd>=2.40.0,<3.0.0`.
+The post-release target state is: `orro` 0.2.25 is published on PyPI. It becomes
+true only after `v0.2.25` is tagged and the Trusted-Publishing workflow completes;
+until then, PyPI contains the ORRO product line through 0.2.24. This repository is
+the canonical 0.2.25 source, whose metadata declares `witnessd>=2.40.0,<3.0.0`.
 
 The wrapper distribution smoke is separate from bootstrap:
 

docs/compatibility-matrix.md

@@ -5,10 +5,10 @@ proof, not verifier truth, not approval, and not assurance. It does not replace
 Depone or witnessd engine tests, and it does not imply that unlisted future
 commits are compatible.
 
-The post-release target state is: `orro` 0.2.24 is published on PyPI. It becomes
-true only after `v0.2.24` is tagged and the Trusted-Publishing workflow completes;
-until then, PyPI contains the ORRO product line through 0.2.22. This repository is
-the canonical 0.2.24 source.
+The post-release target state is: `orro` 0.2.25 is published on PyPI. It becomes
+true only after `v0.2.25` is tagged and the Trusted-Publishing workflow completes;
+until then, PyPI contains the ORRO product line through 0.2.24. This repository is
+the canonical 0.2.25 source.
 
 ```text
 Depone verifies; witnessd executes; ORRO exposes the workflow.
@@ -22,7 +22,7 @@ Depone verifies; witnessd executes; ORRO exposes the workflow.
 | orro-rc-locked-triplet | `f93f31fa09f5eb6133c508547f8e0f5e0636b930` | `c9559008427ab16a12a9002ffc27c434f8e5c6d6` | `b471b47ceb8cc2460e7221375526f63553c18353` | pass | Matches witnessd v2.40.0, `engine-lock/orro-e2e-engine-lock.json`, `release/orro-release-manifest.v0.json`, and `release/compatibility-matrix.v0.json`. |
 
 The locked witnessd revision is release `v2.40.0` (source version 2.40.0). It
-satisfies the ORRO 0.2.24 package requirement `witnessd>=2.40.0,<3.0.0`.
+satisfies the ORRO 0.2.25 package requirement `witnessd>=2.40.0,<3.0.0`.
 
 Related files:
 

docs/e2e-runner.md

@@ -78,4 +78,4 @@ separate pinned-engine e2e CI checks out the pinned witnessd and Depone commits
 from the e2e lock, then runs the full smoke.
 
 The ORRO product line is published on PyPI through 0.2.6. This pinned-engine
-smoke validates the 0.2.24 source package without publishing a new release.
+smoke validates the 0.2.25 source package without publishing a new release.

docs/install.md

@@ -1,17 +1,23 @@
 # Install
 
-The ORRO product line is published on PyPI through 0.2.22, while this repository
-packages 0.2.24. The post-release target state is: `orro` 0.2.24 is published on
-PyPI. It becomes true only after `v0.2.24` is tagged and the Trusted-Publishing
-workflow completes. The 0.2.24 package metadata declares `witnessd>=2.40.0,<3.0.0`, and
+The ORRO product line is published on PyPI through 0.2.24, while this repository
+packages 0.2.25. The post-release target state is: `orro` 0.2.25 is published on
+PyPI. It becomes true only after `v0.2.25` is tagged and the Trusted-Publishing
+workflow completes. The 0.2.25 package metadata declares `witnessd>=2.40.0,<3.0.0`, and
 the package exposes `orro` plus the `orro-wrapper` compatibility alias.
 
 ```bash
 python3 -m pip install orro
 ```
 
-Until the `v0.2.24` workflow completes, that command installs `orro` 0.2.22.
-Development dogfood may instead use the 0.2.24 source checkout and pinned engine
+Use the installed `orro` console script for every operator-facing command. It is
+the only supported entrypoint. Do not probe or run ORRO with
+`uv run python3 -m orro`: uv may discover an unrelated ambient project
+environment and report `No module named orro` even when the installed console
+script and its pinned environment are healthy.
+
+Until the `v0.2.25` workflow completes, that command installs `orro` 0.2.24.
+Development dogfood may instead use the 0.2.25 source checkout and pinned engine
 repositories directly.
 
 For the shared pinned-engine development layout, run bootstrap with the shared
@@ -102,7 +108,7 @@ The v0 packaging decision is documented in `docs/packaging-decision.md` and
 verifier truth, and not package publish.
 
 Current installs use the ORRO-owned thin `orro` command. The ORRO product line is
-published on PyPI through 0.2.22, this repository prepares source 0.2.24 for the
+published on PyPI through 0.2.24, this repository prepares source 0.2.25 for the
 tag-triggered workflow, and the wrapper continues to contain no engine code.
 
 ## Wrapper Distribution Smoke

docs/packaging-decision.md

@@ -12,15 +12,15 @@ ORRO will remain product/distribution/wrapper only while Depone and witnessd
 stay separate engine repositories.
 
 Current command source is the ORRO-owned `orro` console script, which delegates
-to witnessd. The post-release target state is: `orro` 0.2.24 is published on PyPI.
-It becomes true only after `v0.2.24` is tagged and the Trusted-Publishing workflow
-completes; until then, PyPI contains the ORRO product line through 0.2.22. This
-repository is the canonical 0.2.24 source, whose metadata declares
+to witnessd. The post-release target state is: `orro` 0.2.25 is published on PyPI.
+It becomes true only after `v0.2.25` is tagged and the Trusted-Publishing workflow
+completes; until then, PyPI contains the ORRO product line through 0.2.24. This
+repository is the canonical 0.2.25 source, whose metadata declares
 `witnessd>=2.40.0,<3.0.0`.
 
 `published_package: true` means the ORRO product line has published PyPI
 releases; `published_package_scope: product-line` makes that scope explicit. It
-does not assert that the 0.2.24 source candidate is already published.
+does not assert that the 0.2.25 source candidate is already published.
 
 The package remains a thin wrapper that delegates to the existing engine
 command surface. It must contain no engine code.
@@ -58,7 +58,7 @@ The ORRO repository must not contain:
    `orro` and `orro-wrapper`, and contains no engine packages or engine
    implementation files.
 3. Published package: current phase. The ORRO product line is published through
-  0.2.1, and source 0.2.24 is prepared for the tag-triggered Trusted-Publishing
+   0.2.24, and source 0.2.25 is prepared for the tag-triggered Trusted-Publishing
    workflow. Any new release still requires pinned-engine e2e, boundary checks,
    bootstrap checks, and release metadata to remain green.
 

docs/pinned-engine-fallback.md

@@ -67,8 +67,8 @@ mismatched engines and point to bootstrap/setup commands, but it must not
 auto-select different engine commits or rewrite the engine lock outside an
 intentional update PR.
 
-The post-release target state is: `orro` 0.2.24 is published on PyPI. It becomes
-true only after `v0.2.24` is tagged and the Trusted-Publishing workflow completes;
-until then, PyPI contains the ORRO product line through 0.2.22. This repository is
-the canonical 0.2.24 source, whose metadata declares `witnessd>=2.40.0,<3.0.0`. The current
+The post-release target state is: `orro` 0.2.25 is published on PyPI. It becomes
+true only after `v0.2.25` is tagged and the Trusted-Publishing workflow completes;
+until then, PyPI contains the ORRO product line through 0.2.24. This repository is
+the canonical 0.2.25 source, whose metadata declares `witnessd>=2.40.0,<3.0.0`. The current
 engine lock pins witnessd 2.40.0 at tag `v2.40.0`, satisfying that dependency.

docs/release-notes/0.2.25.md

@@ -0,0 +1,14 @@
+# ORRO 0.2.25
+
+ORRO 0.2.25 makes the thin wrapper's public surface match the workflow surface
+that it delegates to witnessd.
+
+- `orro --help` shows the delegated public commands in `usage:` and explains
+  the delegation boundary on the first screen.
+- `orro self-test` fails when the packaged ORRO skill documents name a command
+  absent from witnessd's `ORRO_COMMAND_MAP`.
+- Installation guidance requires the `orro` console script and warns that
+  `uv run python3 -m orro` can select an unrelated ambient environment.
+
+The wrapper remains a wrapper: no engine command, runtime behavior, verifier
+logic, or delegation semantics changed.

docs/repository-strategy.md

@@ -32,9 +32,9 @@ The release manifest and compatibility matrix are product/distribution
 metadata. They record which pinned engine pair has passed ORRO e2e CI, but they
 are not proof, not verifier truth, not approval, and not assurance. Engine-lock
 update process is intentional and PR-reviewed. The post-release target state is:
-`orro` 0.2.24 is published on PyPI. It becomes true only after `v0.2.24` is tagged
+`orro` 0.2.25 is published on PyPI. It becomes true only after `v0.2.25` is tagged
 and the Trusted-Publishing workflow completes; until then, PyPI contains the ORRO
-product line through 0.2.22. This repository is the canonical 0.2.24 source.
+product line through 0.2.24. This repository is the canonical 0.2.25 source.
 
 The packaging decision in `docs/packaging-decision.md` and
 `packaging/wrapper-package-plan.v0.json` is also product metadata, not package

docs/thin-wrapper-plan.md

@@ -1,9 +1,9 @@
 # Thin Wrapper Plan
 
-The post-release target state is: `orro` 0.2.24 is published on PyPI. It becomes
-true only after `v0.2.24` is tagged and the Trusted-Publishing workflow completes;
-until then, PyPI contains the ORRO product line through 0.2.22. The ORRO repository
-is the canonical 0.2.24 source, whose metadata declares `witnessd>=2.40.0,<3.0.0`.
+The post-release target state is: `orro` 0.2.25 is published on PyPI. It becomes
+true only after `v0.2.25` is tagged and the Trusted-Publishing workflow completes;
+until then, PyPI contains the ORRO product line through 0.2.24. The ORRO repository
+is the canonical 0.2.25 source, whose metadata declares `witnessd>=2.40.0,<3.0.0`.
 
 ## Current State
 

docs/thin-wrapper.md

@@ -46,10 +46,10 @@ the engine command the operator explicitly invoked. The wrapper only delegates.
 
 ## Relationship To Packaging
 
-The post-release target state is: `orro` 0.2.24 is published on PyPI. It becomes
-true only after `v0.2.24` is tagged and the Trusted-Publishing workflow completes;
-until then, PyPI contains the ORRO product line through 0.2.22. This repository is
-the canonical 0.2.24 source, whose metadata declares `witnessd>=2.40.0,<3.0.0`.
+The post-release target state is: `orro` 0.2.25 is published on PyPI. It becomes
+true only after `v0.2.25` is tagged and the Trusted-Publishing workflow completes;
+until then, PyPI contains the ORRO product line through 0.2.24. This repository is
+the canonical 0.2.25 source, whose metadata declares `witnessd>=2.40.0,<3.0.0`.
 
 Package work must keep:
 
@@ -60,15 +60,20 @@ Package work must keep:
 
 ## Self-Test
 
-The self-test does not call engine repositories:
+The self-test does not execute an engine command:
 
 ```bash
 python3 -m pip install -e .
 orro-wrapper self-test
 ```
 
 It verifies the wrapper boundary, default delegation command parsing, and that
-empty delegate invocations fail closed.
+empty delegate invocations fail closed. It also reads the pinned witnessd
+distribution's `ORRO_COMMAND_MAP` and packaged skill documents, then fails if a
+public command named by either skill is absent from the engine map. An
+intentional wrapper-only `--no-deps` packaging smoke reports that parity was not
+checked because the engine metadata is absent; normal installs include witnessd
+through the declared package dependency and run the parity check.
 
 ## Install Smoke
 
@@ -82,8 +87,9 @@ python3 scripts/check_orro_wrapper_install.py --json
 
 The install smoke checks that both commands are installed, that boundary and
 self-test commands pass, and that explicit delegation works with a harmless
-Python command. It does not call Depone or witnessd, does not run proofrun, does
-not run proofcheck, and does not publish a package.
+Python command. The self-test reads witnessd's packaged command/skill metadata,
+but the smoke does not run proofrun, run proofcheck, call Depone, or publish a
+package.
 
 The install smoke result is setup/test metadata, not proof, not verifier truth,
 not package publish, not approval, and not assurance.

docs/wrapper-distribution.md

@@ -57,7 +57,7 @@ This is local distribution smoke only. It builds and installs a local wheel, but
 it does not publish a package, upload artifacts, create a marketplace release,
 or claim verifier truth.
 
-The post-release target state is: `orro` 0.2.24 is published on PyPI. It becomes
-true only after `v0.2.24` is tagged and the Trusted-Publishing workflow completes;
-until then, PyPI contains the ORRO product line through 0.2.22. This repository is
-the canonical 0.2.24 source, whose metadata declares `witnessd>=2.40.0,<3.0.0`.
+The post-release target state is: `orro` 0.2.25 is published on PyPI. It becomes
+true only after `v0.2.25` is tagged and the Trusted-Publishing workflow completes;
+until then, PyPI contains the ORRO product line through 0.2.24. This repository is
+the canonical 0.2.25 source, whose metadata declares `witnessd>=2.40.0,<3.0.0`.

packaging/plugin-manifest.draft.json

@@ -7,7 +7,7 @@
   "entrypoint_plan": {
     "current": "ORRO-owned orro console script delegating to witnessd",
     "compatibility_alias": "orro-wrapper",
-    "distribution": "orro 0.2.24 source package"
+    "distribution": "orro 0.2.25 source package"
   },
   "engine_dependencies": {
     "witnessd": {

packaging/wrapper-package-plan.v0.json

@@ -4,7 +4,7 @@
   "status": "release-candidate",
   "package_goal": "single user-facing ORRO install that prepares and invokes pinned Depone and witnessd engines",
   "distribution_name": "orro",
-  "source_version": "0.2.24",
+  "source_version": "0.2.25",
   "published_pypi_versions": [
     "0.0.1",
     "0.0.2",
@@ -33,7 +33,8 @@
     "0.2.19",
     "0.2.20",
     "0.2.21",
-    "0.2.22"
+    "0.2.22",
+    "0.2.24"
   ],
   "current_command_source": "ORRO-owned orro console script",
   "published_package": true,
@@ -60,7 +61,7 @@
     {
       "phase": "published-package",
       "status": "current",
-      "description": "Track the published ORRO product line through 0.2.22 and prepare source 0.2.24 for the tag-triggered Trusted-Publishing workflow.",
+      "description": "Track the published ORRO product line through 0.2.24 and prepare source 0.2.25 for the tag-triggered Trusted-Publishing workflow.",
       "contains_engine_logic": false
     }
   ],

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "orro"
-version = "0.2.24"
+version = "0.2.25"
 description = "Published ORRO product/distribution wrapper for pinned Depone and witnessd engines."
 readme = "README.md"
 requires-python = ">=3.10"

scripts/check_orro_fallback_policy.py

@@ -100,7 +100,7 @@ def check_docs() -> None:
     require_contains("fallback docs", text, "intentional engine-lock update PR")
     require_contains("fallback docs", text, "proofrun")
     require_contains("fallback docs", text, "proofcheck")
-    require_contains("fallback docs", text, "`orro` 0.2.24 is published on PyPI")
+    require_contains("fallback docs", text, "`orro` 0.2.25 is published on PyPI")
 
 
 def main() -> int:

scripts/check_orro_packaging_decision.py

@@ -67,8 +67,8 @@ def check_plan() -> None:
         fail("wrapper package plan status must be release-candidate")
     if plan.get("distribution_name") != "orro":
         fail("wrapper package plan distribution_name must be orro")
-    if plan.get("source_version") != "0.2.24":
-        fail("wrapper package plan source_version must be 0.2.24")
+    if plan.get("source_version") != "0.2.25":
+        fail("wrapper package plan source_version must be 0.2.25")
     if plan.get("current_command_source") != "ORRO-owned orro console script":
         fail("current command source must be ORRO-owned")
 
@@ -123,7 +123,7 @@ def check_docs() -> None:
     require_contains("packaging decision doc", text, "not package publish")
     require_contains("packaging decision doc", text, "witnessd-hosted")
     require_contains("packaging decision doc", text, "no engine code")
-    require_contains("packaging decision doc", text, "`orro` 0.2.24 is published on PyPI")
+    require_contains("packaging decision doc", text, "`orro` 0.2.25 is published on PyPI")
     require_contains("packaging decision doc", text, WITNESSD_REQUIREMENT)
     require_contains("packaging decision doc", text, "proofrun")
     require_contains("packaging decision doc", text, "proofcheck")