fix(ci): preserve policy command contract coverage

.github/actions/ci-cli-coverage-merge/action.yaml

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 name: ci-cli-coverage-merge
-description: Merge shared CLI coverage shard blob reports and run the coverage ratchet.
+description: Merge shared source-test and policy command contract blobs and run the CLI coverage ratchet.
 
 inputs:
   shard-count:
@@ -66,6 +66,11 @@ runs:
         CLI_SHARD_COUNT: ${{ inputs.shard-count }}
       run: |
         set -euo pipefail
+        contract_blob=".vitest-reports/blob-policy-command-contract.json"
+        if [ ! -s "$contract_blob" ]; then
+          echo "::error title=Missing policy command contract blob::Expected non-empty ${contract_blob}"
+          exit 1
+        fi
         for shard in $(seq 1 "$CLI_SHARD_COUNT"); do
           blob=".vitest-reports/blob-${shard}-${CLI_SHARD_COUNT}.json"
           if [ ! -s "$blob" ]; then
@@ -79,6 +84,13 @@ runs:
           find .vitest-reports -maxdepth 1 -type f -print
           exit 1
         fi
+        total_blob_count=$(find .vitest-reports -maxdepth 1 -type f -name 'blob-*.json' | wc -l | tr -d ' ')
+        expected_total=$((CLI_SHARD_COUNT + 1))
+        if [ "$total_blob_count" != "$expected_total" ]; then
+          echo "::error title=Unexpected CLI coverage blob count::Expected ${expected_total} blob reports, found ${total_blob_count}"
+          find .vitest-reports -maxdepth 1 -type f -print
+          exit 1
+        fi
 
     - name: Merge CLI coverage
       shell: bash

.github/actions/ci-cli-coverage-shard/action.yaml

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 name: ci-cli-coverage-shard
-description: Run one shared CLI, integration, and E2E-support shard and upload its Vitest blob report.
+description: Run one shared source-test shard, preserve the policy command contract, and upload Vitest blob reports.
 
 inputs:
   shard:
@@ -176,11 +176,49 @@ runs:
           --coverage.exclude="test/**/*.js" \
           --coverage.exclude="test/**/*.ts"
 
+    - name: Run policy command coverage contract
+      if: ${{ inputs.shard == '1' }}
+      shell: bash
+      run: |
+        npx vitest run --project policy-command-contract \
+          --reporter=github-actions \
+          --reporter=blob \
+          --outputFile.blob=".vitest-reports/blob-policy-command-contract.json" \
+          --coverage \
+          --coverage.reporter=json-summary \
+          --coverage.reportsDirectory="coverage/cli/policy-command-contract" \
+          --coverage.include="src/lib/policy/commands.ts"
+
+    - name: Verify CLI shard blob reports
+      shell: bash
+      env:
+        CLI_SHARD: ${{ inputs.shard }}
+        CLI_SHARD_COUNT: ${{ inputs.shard-count }}
+      run: |
+        set -euo pipefail
+        shard_blob=".vitest-reports/blob-${CLI_SHARD}-${CLI_SHARD_COUNT}.json"
+        contract_blob=".vitest-reports/blob-policy-command-contract.json"
+        if [ ! -s "$shard_blob" ]; then
+          echo "::error title=Missing CLI shard blob::Expected non-empty ${shard_blob}"
+          exit 1
+        fi
+        if [ "$CLI_SHARD" = "1" ]; then
+          if [ ! -s "$contract_blob" ]; then
+            echo "::error title=Missing policy command contract blob::Expected non-empty ${contract_blob}"
+            exit 1
+          fi
+        elif [ -e "$contract_blob" ]; then
+          echo "::error title=Unexpected policy command contract blob::Only shard 1 may upload ${contract_blob}"
+          exit 1
+        fi
+
     - name: Upload CLI shard blob report
       if: ${{ always() && steps.validate-shard-inputs.outcome == 'success' }}
       uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
       with:
         name: cli-blob-report-${{ inputs.shard }}
-        path: .vitest-reports/blob-${{ inputs.shard }}-${{ inputs.shard-count }}.json
+        path: |
+          .vitest-reports/blob-${{ inputs.shard }}-${{ inputs.shard-count }}.json
+          .vitest-reports/blob-policy-command-contract.json
         if-no-files-found: error
         retention-days: 1

AGENTS.md

@@ -93,14 +93,16 @@ The `bin/` directory uses CommonJS intentionally for the launcher and a few comp
 
 Tests are organized into disjoint Vitest projects defined in `vitest.config.ts`:
 
-1. **`cli`** — `src/**/*.test.ts` — CLI unit tests importing source
-2. **`integration`** — `test/**/*.test.{js,ts}` — root integration tests importing source; excludes the explicit lanes below
-3. **`installer-integration`** — `test/installer-integration/**/*.test.ts` — installer tests that spawn real `install.sh` processes
-4. **`package-contract`** — `test/package-contract/**/*.test.ts` — the only non-live lane that imports compiled CLI/plugin artifacts
-5. **`plugin`** — `nemoclaw/src/**/*.test.ts` — plugin unit tests co-located with source
-6. **`e2e-support`** — fast tests for the E2E fixture/support layer; this project runs in the
-   aggregate checks for code-changing PRs and code-changing pushes to `main`
-7. **`e2e-live`** — opt-in live targets that mutate real external state
+1. **`cli`**: `src/**/*.test.ts`, except the policy command contract below, contains CLI unit tests importing source.
+2. **`policy-command-contract`**: `src/lib/policy/commands.test.ts` verifies the pure policy command `argv` contract.
+   Its separate project converts the V8 map before the CLI coverage job combines project coverage.
+3. **`integration`**: `test/**/*.test.{js,ts}` contains root integration tests importing source and excludes the explicit lanes below.
+4. **`installer-integration`**: `test/installer-integration/**/*.test.ts` contains installer tests that spawn real `install.sh` processes.
+5. **`package-contract`**: `test/package-contract/**/*.test.ts` is the only non-live lane that imports compiled CLI or plugin artifacts.
+6. **`plugin`**: `nemoclaw/src/**/*.test.ts` contains plugin unit tests co-located with source.
+7. **`e2e-support`**: Fast tests for the E2E fixture and support layer.
+   This project runs in aggregate checks for code-changing PRs and code-changing pushes to `main`.
+8. **`e2e-live`**: Opt-in live targets that mutate real external state.
 
 When writing tests:
 
@@ -109,7 +111,8 @@ When writing tests:
 - Import CLI source from ordinary tests. Put genuine compiled-artifact assertions under `test/package-contract/`.
 - Keep project globs disjoint and exhaustive; `npm run test:projects:check` compares filesystem candidates with Vitest and rejects missing, overlapping, or unexpected membership.
 - Deterministic projects clear mock calls, restore `vi.spyOn`, and undo `vi.stubEnv` and `vi.stubGlobal` before each test. Create those spies and stubs in `beforeEach` or the test body unless a documented import-time stub must run before module evaluation. Restore direct environment or global mutations yourself, and reset mock implementations explicitly when needed. Live E2E and automatic `mockReset` are intentionally excluded.
-- Use `npm run test:changed` or `npm run test:watch` for focused CLI, plugin, and E2E-support feedback. Add only concrete opaque-input mappings to `test/helpers/vitest-watch-triggers.ts` when the import graph cannot see a YAML, Python, shell, generated, or workflow dependency.
+- Use `npm run test:changed` or `npm run test:watch` for focused CLI, policy command contract, plugin, and E2E-support feedback.
+  Add only concrete opaque-input mappings to `test/helpers/vitest-watch-triggers.ts` when the import graph cannot see a YAML, Python, shell, generated, or workflow dependency.
 - Use `npm run test:shuffle -- --sequence.seed=<seed>` to replay a printed test-order seed. Use `npm run test:diagnose:leaks` for async-resource or shutdown-hang diagnostics; both commands keep coverage disabled, and leak diagnostics can accompany exit code 0 when assertions pass.
 - Write behavior-oriented titles, put local issue references in a final `(#1234)` suffix, and use `npm run test:spec` for the hierarchical specification view.
 - Mock external dependencies; don't call real NVIDIA APIs in unit tests

CONTRIBUTING.md

@@ -226,9 +226,9 @@ These are the primary npm scripts for day-to-day development:
 | `npm --prefix nemoclaw run typecheck` | Type-check plugin production and test sources without emitting files |
 | `npm test` | Build package artifacts and run every non-live Vitest project for broad changes |
 | `npm run test:spec` | Run every non-live test with hierarchical behavior-oriented output |
-| `npm run test:fast` | Clean `dist/` and run source CLI, plugin, and E2E-support tests |
-| `npm run test:changed` | Run tests affected by staged, unstaged, or untracked changes in the CLI, plugin, and E2E-support projects |
-| `npm run test:watch` | Watch the CLI, plugin, and E2E-support projects and rerun affected tests |
+| `npm run test:fast` | Clean `dist/` and run the `cli`, `policy-command-contract`, `plugin`, and `e2e-support` projects |
+| `npm run test:changed` | Run tests affected by staged, unstaged, or untracked changes in the `cli`, `policy-command-contract`, `plugin`, and `e2e-support` projects |
+| `npm run test:watch` | Watch the `cli`, `policy-command-contract`, `plugin`, and `e2e-support` projects and rerun affected tests |
 | `npm run test:shuffle` | Shuffle test order in the focused source projects without collecting coverage |
 | `npm run test:diagnose:leaks` | Report async-resource leaks and diagnose a Vitest process that hangs during shutdown |
 | `npm run test:e2e-phases:check` | Validate semantic phase plans for every live E2E test and workflow-selected credential-free integration test without executing test bodies |
@@ -357,12 +357,10 @@ between the two digest fields.
 
 ### Focused Vitest Feedback
 
-Use `npm run test:changed` for the staged, unstaged, and untracked changes in the current checkout,
-or keep `npm run test:watch` running while editing. Both commands select only the source-backed
-`cli`, `plugin`, and `e2e-support` projects. Watch mode also maps the repository's current opaque
-YAML, Python, shell, generated, and workflow inputs to the concrete contract tests that read or
-execute them outside Vitest's import graph. Add a narrow mapping in
-`test/helpers/vitest-watch-triggers.ts` when a new opaque input needs the same treatment.
+Use `npm run test:changed` for staged, unstaged, and untracked changes, or keep `npm run test:watch` running while editing.
+Both commands select the source-backed `cli`, `policy-command-contract`, `plugin`, and `e2e-support` projects.
+Watch mode also maps opaque YAML, Python, shell, generated, and workflow inputs to contract tests outside Vitest's import graph.
+Add a narrow mapping in `test/helpers/vitest-watch-triggers.ts` when a new opaque input needs the same treatment.
 
 Use `npm run test:shuffle` to expose order dependencies in those focused projects. The command
 shuffles tests within files and leaves coverage disabled. Vitest prints the chosen seed at the
@@ -384,9 +382,9 @@ receives test annotations.
 
 ### Test State Isolation
 
-The `cli`, `integration`, `installer-integration`, `package-contract`, `plugin`, and `e2e-support`
-projects clear mock call history, restore `vi.spyOn` descriptors, and undo `vi.stubEnv` and
-`vi.stubGlobal` before each test.
+The `cli`, `policy-command-contract`, `integration`, `installer-integration`, `package-contract`,
+`plugin`, and `e2e-support` projects clear mock call history, restore `vi.spyOn` descriptors, and
+undo `vi.stubEnv` and `vi.stubGlobal` before each test.
 Create those spies and stubs in `beforeEach` or the test body. A documented import-time stub may
 remain at module scope when the imported module must capture it during evaluation.
 These projects do not enable `mockReset`, and Vitest does not track direct `process.env` or global

package.json

@@ -24,18 +24,18 @@
     "dev:setup": "bash scripts/dev-setup.sh",
     "dev:doctor": "bash scripts/dev-setup.sh --doctor",
     "agent": "pi",
-    "test": "npm run clean:cli && npm --prefix nemoclaw run clean && npm run build:cli && npm --prefix nemoclaw run build && vitest run --project cli --project integration --project installer-integration --project package-contract --project plugin --project e2e-support",
+    "test": "npm run clean:cli && npm --prefix nemoclaw run clean && npm run build:cli && npm --prefix nemoclaw run build && vitest run --project cli --project policy-command-contract --project integration --project installer-integration --project package-contract --project plugin --project e2e-support",
     "test:spec": "npm test -- --reporter=tree",
-    "test:fast": "npm run clean:cli && npm run catalog:compile && vitest run --project cli --project plugin --project e2e-support",
-    "test:changed": "npm run catalog:compile && vitest run --project integration test/automation/pull-requests/growth-guardrails.test.ts && vitest run --changed --project cli --project plugin --project e2e-support",
-    "test:watch": "npm run catalog:compile && vitest watch --project cli --project plugin --project e2e-support",
-    "test:shuffle": "npm run catalog:compile && vitest run --project cli --project plugin --project e2e-support --sequence.shuffle.tests --coverage=false",
-    "test:diagnose:leaks": "npm run catalog:compile && vitest run --project cli --project plugin --project e2e-support --detectAsyncLeaks --coverage=false --reporter=default --reporter=hanging-process",
+    "test:fast": "npm run clean:cli && npm run catalog:compile && vitest run --project cli --project policy-command-contract --project plugin --project e2e-support",
+    "test:changed": "npm run catalog:compile && vitest run --project integration test/automation/pull-requests/growth-guardrails.test.ts && vitest run --changed --project cli --project policy-command-contract --project plugin --project e2e-support",
+    "test:watch": "npm run catalog:compile && vitest watch --project cli --project policy-command-contract --project plugin --project e2e-support",
+    "test:shuffle": "npm run catalog:compile && vitest run --project cli --project policy-command-contract --project plugin --project e2e-support --sequence.shuffle.tests --coverage=false",
+    "test:diagnose:leaks": "npm run catalog:compile && vitest run --project cli --project policy-command-contract --project plugin --project e2e-support --detectAsyncLeaks --coverage=false --reporter=default --reporter=hanging-process",
     "test:e2e-phases:check": "npm run catalog:compile && npm run build:policy-boundary && node --experimental-strip-types --no-warnings tools/e2e/check-semantic-phases.mts",
     "test:runtime-audit": "tsx scripts/audit-test-runtime.mts",
     "test:integration": "npm run clean:cli && npm run build:cli && vitest run --project integration --project installer-integration",
     "test:package": "npm run clean:cli && npm --prefix nemoclaw run clean && npm run build:cli && npm --prefix nemoclaw run build && vitest run --project package-contract",
-    "test:coverage:cli": "npm run clean:cli && npm run build:cli && tsx scripts/check-dist-sourcemaps.mts dist && vitest run --project cli --project integration --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary --coverage.reportsDirectory=coverage/cli --coverage.include=\"bin/**/*.js\" --coverage.include=\"src/**/*.ts\" --coverage.exclude=\"test/**/*.js\" --coverage.exclude=\"test/**/*.ts\" && tsx scripts/check-coverage-ratchet.mts coverage/cli/coverage-summary.json ci/coverage-threshold-cli.json \"CLI coverage\"",
+    "test:coverage:cli": "npm run clean:cli && npm run build:cli && tsx scripts/check-dist-sourcemaps.mts dist && vitest run --project cli --project policy-command-contract --project integration --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary --coverage.reportsDirectory=coverage/cli --coverage.include=\"bin/**/*.js\" --coverage.include=\"src/**/*.ts\" --coverage.exclude=\"test/**/*.js\" --coverage.exclude=\"test/**/*.ts\" && tsx scripts/check-coverage-ratchet.mts coverage/cli/coverage-summary.json ci/coverage-threshold-cli.json \"CLI coverage\"",
     "test:coverage:plugin": "vitest run --project plugin --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary --coverage.reportsDirectory=coverage/plugin --coverage.include=\"nemoclaw/src/**/*.ts\" --coverage.include=\"nemoclaw/src/**/*.cts\" --coverage.exclude=\"**/*.test.ts\" && tsx scripts/check-coverage-ratchet.mts coverage/plugin/coverage-summary.json ci/coverage-threshold-plugin.json \"Plugin coverage\"",
     "test:live-e2e": "npm run clean:cli && npm run build:cli && NEMOCLAW_RUN_LIVE_E2E=1 vitest run --project e2e-live",
     "e2e:unit-gaps": "tsx tools/e2e/unit-test-gaps.mts",

scripts/checks/vitest-project-overlap.mts

@@ -8,6 +8,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 export const EXPECTED_VITEST_PROJECTS = [
   "cli",
+  "policy-command-contract",
   "integration",
   "installer-integration",
   "package-contract",
@@ -65,6 +66,7 @@ export function discoverVitestCandidates(repoRoot: string = REPO_ROOT): Set<stri
 
 export function expectedProjectForTestPath(file: string): ExpectedVitestProject | undefined {
   const normalized = normalizeRepoPath(file);
+  if (normalized === "src/lib/policy/commands.test.ts") return "policy-command-contract";
   if (normalized.startsWith("src/")) return "cli";
   if (normalized.startsWith("nemoclaw/src/")) return "plugin";
   if (normalized.startsWith("test/installer-integration/")) return "installer-integration";

test/repository/cli-coverage-sequencer.test.ts

@@ -149,6 +149,7 @@ describe("stable CLI coverage sharding", () => {
     expect(shouldUseCliCoverageSharding(["cli", "integration", "e2e-support"])).toBe(true);
     expect(shouldUseCliCoverageSharding(["integration"])).toBe(true);
     expect(shouldUseCliCoverageSharding(["e2e-support"])).toBe(true);
+    expect(shouldUseCliCoverageSharding(["policy-command-contract"])).toBe(false);
     expect(shouldUseCliCoverageSharding(["plugin"])).toBe(false);
     expect(shouldUseCliCoverageSharding([])).toBe(false);
   });

test/repository/test-boundary-guards.test.ts

@@ -753,6 +753,7 @@ describe("Vitest project membership boundary", () => {
     Array.from(
       new Map<string, string | undefined>([
         ["src/example.spec.ts", "cli"],
+        ["src/lib/policy/commands.test.ts", "policy-command-contract"],
         ["nemoclaw/src/example.test.js", "plugin"],
         ["test/repository/coverage-ratchet.test.ts", "integration"],
         ["test/repository/vitest-coverage-thresholds.test.ts", "integration"],

test/repository/vitest-developer-feedback.test.ts

@@ -7,7 +7,8 @@ import { test as it } from "../helpers/owned-test-resources";
 import { resolveVitestFeedback } from "../helpers/vitest-feedback";
 import { runVitestNpmScript } from "../helpers/vitest-npm-script";
 
-const focusedProjects = "--project cli --project plugin --project e2e-support";
+const focusedProjects =
+  "--project cli --project policy-command-contract --project plugin --project e2e-support";
 
 describe("Vitest developer feedback", () => {
   it("selects passed-only Vitest output in CI (#6692)", () => {

vitest.config.ts

@@ -156,7 +156,30 @@ export default defineConfig({
             "test/helpers/onboard-script-mocks.cjs",
           ],
           include: ["src/**/*.test.ts"],
-          exclude: ["**/node_modules/**", "**/.claude/**"],
+          exclude: [
+            "**/node_modules/**",
+            "**/.claude/**",
+            "src/lib/policy/commands.test.ts",
+          ],
+        },
+      },
+      // Keep this pure command contract in a short-lived project. Exact CLI-only
+      // and integration-only CI shards both passed these tests but lost one
+      // executed function from their raw V8 maps before blob emission.
+      {
+        ...typedSourceTransform,
+        test: {
+          ...vitestStateIsolation,
+          name: "policy-command-contract",
+          alias: canonicalSourceAliases,
+          env: controlledNonLiveEnv,
+          testTimeout: testTimeout(),
+          setupFiles: [
+            fixtureUmaskSetup,
+            isolatedTestStateSetup,
+            "test/helpers/onboard-script-mocks.cjs",
+          ],
+          include: ["src/lib/policy/commands.test.ts"],
         },
       },
       {