feat(FN-3366): document CI shard contract in contributing guide

Documentation update to `docs/contributing.md` adding details on the CI shard contract (FN-3366 Step 3).

Fusion-Task-Id: FN-3366

packages/cli/src/__tests__/root-test-command.test.ts

@@ -4,6 +4,7 @@ import {
   resolveAffectedPackages,
   shouldForceFullSuite,
 } from "../../../../scripts/test-changed.mjs";
+import { parseShardArgs, selectShardPackages } from "../../../../scripts/ci-test-shard.mjs";
 
 describe("root test command changed-only planning", () => {
   it("uses changed mode when package-only changes are detected", () => {
@@ -55,3 +56,25 @@ describe("root test command changed-only planning", () => {
     expect(shouldForceFullSuite(["packages/core/src/store.ts"])).toBe(false);
   });
 });
+
+describe("CI shard test planner", () => {
+  it("parses valid shard args", () => {
+    expect(parseShardArgs(["--shard", "2", "--total", "3"], {} as NodeJS.ProcessEnv)).toEqual({
+      shard: 2,
+      total: 3,
+    });
+  });
+
+  it("rejects invalid shard args", () => {
+    expect(() => parseShardArgs(["--shard", "4", "--total", "3"], {} as NodeJS.ProcessEnv)).toThrow(
+      "Usage: node scripts/ci-test-shard.mjs --shard <1..N> --total <N>",
+    );
+  });
+
+  it("selects deterministic package partitions", () => {
+    const packages = ["a", "b", "c", "d", "e"];
+    expect(selectShardPackages(packages, 1, 3)).toEqual(["a", "d"]);
+    expect(selectShardPackages(packages, 2, 3)).toEqual(["b", "e"]);
+    expect(selectShardPackages(packages, 3, 3)).toEqual(["c"]);
+  });
+});