ci(openshell): accept optional SDK package decision (#10568)

<!-- markdownlint-disable MD041 -->
## Outcome

Pull request CI now treats a valid base-controlled `required: false` SDK
package decision as a successful no-package result. Invalid inspector
output still stops the locator before it writes workflow output.

Unblocks PR #10562.

## Reason

`jq -e` treated Boolean `false` as a command failure. This blocked PR
#10562 before its dependency jobs could run. The locator must preserve
`false` as valid data while keeping the trusted decision boundary fail
closed.

## Changes

- Require exactly one trusted inspector JSON object with a Boolean
`required` field, then convert that Boolean to a string before `jq -e`
evaluates it.
- Add workflow-shell regression tests for valid `false`, non-Boolean,
empty, and multiple-document inspector output.

## Verification

- `/Users/rsliter/Projects/NemoClaw/node_modules/.bin/vitest run
--project integration
test/automation/pull-requests/pr-workflow-contract.test.ts`: 1 file
passed, 39 tests passed.
- Normal `pre-commit` and `commit-msg` hooks passed, including YAML
validation, repository checks, source-shape budgets, growth guardrails,
secret scanning, formatting, linting, and commitlint.
- `git diff --check origin/main...HEAD`: passed.
- The diff contains no secrets, API keys, or credentials.

## Documentation Writer Review

- [x] Documentation writer subagent reviewed the completed
implementation
- Result: `no-docs-needed`
- Evidence: The change is limited to internal pull request CI parsing
and workflow-shell regression tests. It does not change user commands,
configuration, supported product behavior, or documentation routes.
- Agent: Codex Desktop
<!-- docs-review-head-sha: f1f683d -->
<!-- docs-review-agents-blob-sha: dd3528f -->

## Review notes

Independent security review passed all nine categories. The
base-controlled checkout, same-repository gate, artifact identity
checks, job permissions, and credential isolation remain unchanged.
Negative tests confirm that invalid inspector output does not write
workflow state.

---
Signed-off-by: Rebecca Sliter <571084+rsliter@users.noreply.github.com>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **Bug Fixes**
- Improved SDK package decision handling by requiring a single, valid
JSON decision with a boolean requirement.
- Invalid, empty, or ambiguous decisions now fail clearly instead of
being misinterpreted.
  - Artifact lookup is skipped when no SDK package is required.
- **Tests**
- Added coverage for valid custom inspection results, non-boolean
requirements, missing decisions, and multiple decision outputs.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Signed-off-by: Rebecca Sliter <571084+rsliter@users.noreply.github.com>
Co-authored-by: Rebecca Sliter <571084+rsliter@users.noreply.github.com>

Author: rsliter

.github/workflows/pr.yaml

@@ -214,7 +214,15 @@ jobs:
               NEMOCLAW_CI_TARGET_ROOT="$GITHUB_WORKSPACE" \
               node --experimental-strip-types "$trusted_inspector"
           )"
-          required="$(jq -er '.required | select(type == "boolean")' <<<"$decision")"
+          required="$(
+            jq -ser '
+              if length == 1 and (.[0] | type) == "object" and (.[0].required | type) == "boolean" then
+                .[0].required | tostring
+              else
+                error("decision must contain one object with a boolean required field")
+              end
+            ' <<<"$decision"
+          )"
           if [ "$required" != "true" ]; then
             echo "required=false" >> "$GITHUB_OUTPUT"
             exit 0

test/automation/pull-requests/pr-workflow-contract.test.ts

@@ -160,6 +160,8 @@ function runWorkflowShellStep(
 type SdkPackageLocatorFixture = Readonly<{
   artifactFailureRunId?: number;
   artifactsByRunId?: Readonly<Record<string, unknown>>;
+  inspectorOutput?: string;
+  inspectorRequired?: unknown;
   runs: readonly unknown[];
   step: WorkflowStep;
   workflowRunFailure?: boolean;
@@ -178,9 +180,15 @@ function runSdkPackageLocator(fixture: SdkPackageLocatorFixture): Readonly<{
     mkdirSync(inspectorDirectory, { recursive: true });
     mkdirSync(workflowDirectory, { recursive: true });
     mkdirSync(fakeBin);
+    const inspectorDecision =
+      fixture.inspectorOutput ??
+      JSON.stringify({
+        artifactName: "reviewed-sdk.tgz",
+        required: fixture.inspectorRequired ?? true,
+      });
     writeFileSync(
       join(inspectorDirectory, "prepare-ci-npm-install.mts"),
-      'process.stdout.write(JSON.stringify({ required: true, artifactName: "reviewed-sdk.tgz" }));\n',
+      `process.stdout.write(${JSON.stringify(inspectorDecision)});\n`,
     );
     writeFileSync(join(workflowDirectory, "openshell-sdk-package-pr.yaml"), "name: test\n");
     writeFileSync(join(fakeBin, "seq"), "#!/bin/sh\nprintf '1\\n'\n", { mode: 0o755 });
@@ -674,6 +682,51 @@ describe("pull request and main workflow contracts", () => {
     }
   });
 
+  it("skips SDK artifact lookup when the trusted inspector does not require a package", () => {
+    const { githubOutput, result } = runSdkPackageLocator({
+      inspectorRequired: false,
+      runs: [],
+      step: requiredWorkflowStep(
+        prWorkflow.jobs["openshell-sdk-package"],
+        "Locate exact base-controlled SDK package run",
+      ),
+    });
+
+    expect(result).toMatchObject({ status: 0, stderr: "" });
+    expect(githubOutput).toBe("required=false\n");
+  });
+
+  it("rejects a non-boolean package requirement from the trusted inspector", () => {
+    const { githubOutput, result } = runSdkPackageLocator({
+      inspectorRequired: "false",
+      runs: [],
+      step: requiredWorkflowStep(
+        prWorkflow.jobs["openshell-sdk-package"],
+        "Locate exact base-controlled SDK package run",
+      ),
+    });
+
+    expect(result.status).not.toBe(0);
+    expect(githubOutput).toBe("");
+  });
+
+  it.each([
+    ["empty output", ""],
+    ["multiple JSON documents", '{"required":false}\n{"required":true}'],
+  ])("rejects %s from the trusted inspector", (_description, inspectorOutput) => {
+    const { githubOutput, result } = runSdkPackageLocator({
+      inspectorOutput,
+      runs: [],
+      step: requiredWorkflowStep(
+        prWorkflow.jobs["openshell-sdk-package"],
+        "Locate exact base-controlled SDK package run",
+      ),
+    });
+
+    expect(result.status).not.toBe(0);
+    expect(githubOutput).toBe("");
+  });
+
   it("explains how to recover when the exact SDK package artifact expired", () => {
     const { githubOutput, result } = runSdkPackageLocator({
       artifactsByRunId: {