feat(devx): gate the os package publish example set against its documented block (#15721)

* feat(devx): gate the `os package publish` example set against its documented block

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012zGPuVVX3deAx9LdjK8jCk

* fix(devx): spell two self-test fixtures so they are not command-id literals

`check:cli-command-ids` reads any quoted run opening with a real oclif bin name
as a command-id literal, and reds when it resolves to nothing. Two fixtures in
the new parity gate's self-test were deliberately-unresolvable phrases.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012zGPuVVX3deAx9LdjK8jCk

* fix(devx): let the self-test's failure branch reach the verdict handshake

The handshake guards a `return` that skips the verdict block, not the verdict's
direction; leaving the flag false on a red printed "never finished" over a run
that finished and failed.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012zGPuVVX3deAx9LdjK8jCk

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.github/workflows/lint.yml

@@ -2386,6 +2386,23 @@ jobs:
       - name: CLI command-id literals resolve
         run: pnpm check:cli-command-ids
 
+      # #15393. `os package publish` ships its example set TWICE — the oclif
+      # `examples` array in packages/cli/src/commands/package/publish.ts, printed
+      # verbatim under `EXAMPLES`, and a fenced block under
+      # `#### os package publish` in content/docs/deployment/cli.mdx. Two
+      # hand-maintained copies, and they drifted: the CLI line pointed at a
+      # directory deleted from this repo while the docs line for the same example
+      # was correct, for as long as it took a customer-simulation run to notice.
+      # ⛔ NOT an extension of check:cli-command-ids above — that gate's recorded
+      # refusal to reach into prose stands, and its population is 811 `os ...`
+      # mentions with no delimiter. This one's population is a TABLE: one fenced
+      # block under one exact heading against one named `examples` array. It
+      # compares the SET of invocations modulo the `$ ` prompt, trailing comments,
+      # whitespace and ORDER — the two voices may differ, the invocations may not.
+      # Reads two source files; no build, no install.
+      - name: CLI examples match the documented block
+        run: pnpm check:cli-examples-parity
+
       # #4093 follow-up. Discovery tells a consumer an absent capability is
       # absent AND what to install. The first half has been carefully honest
       # since #2462/#4000; the second was invented from the slot name, so ten

package.json

@@ -92,6 +92,7 @@
     "check:cli-test-child-env": "node scripts/check-cli-test-child-env.mjs --self-test && node scripts/check-cli-test-child-env.mjs",
     "check:vendor-version-stamps": "node scripts/check-vendor-version-stamps.mjs --self-test && node scripts/check-vendor-version-stamps.mjs",
     "check:cli-command-ids": "node scripts/check-cli-command-ids.mjs --self-test && node scripts/check-cli-command-ids.mjs",
+    "check:cli-examples-parity": "node scripts/check-cli-examples-parity.mjs --self-test && node scripts/check-cli-examples-parity.mjs",
     "check:authz-resolver": "node scripts/check-single-authz-resolver.mjs --self-test && node scripts/check-single-authz-resolver.mjs",
     "check:slot-lookup": "node scripts/check-slot-lookup-ratchet.mjs --self-test && node scripts/check-slot-lookup-ratchet.mjs",
     "check:query-options-erasure": "node scripts/check-query-options-erasure-ratchet.mjs --self-test && node scripts/check-query-options-erasure-ratchet.mjs",