docs(job-array-one-based-index): document the supported array syntax (task 9.3)

src/docs/xce.md gains a 'Job arrays' section: name[1-N] and name[1],
numbering from 1, the API-server limit (default 1000, at most 32767),
<array-id>[k] and <array-id>[a-b] selection (with the peek/restart
caveat), XCE_JOBINDEX, the harness jobsub -a N / $jobid[k], and every
LSF array feature this release does not support. The superseded
statements in job-array-single-wal-record and xce-test-e2e-primitives
are annotated (history kept), the controller-job-cleanup and
job-dependency briefs describe 1-based numbering, and the roadmap gains
an entry.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

.kiro/specs/xce-test-e2e-primitives/design.md

@@ -75,6 +75,7 @@ graph TD
   - **Session/verdict state** (file-scope): `g_session_failed` (int), `g_continue_on_error` (bool), and auto-vars `g_last_status` (int), `g_last_jobid[XCE_MAXNAME_LEN]` (string), `g_last_jobcount` (int).
   - **`preprocess_and_run(char* line)`** (new): handle blank/`#`; leading `!` → `system(rest)`, set `g_last_status` from `WEXITSTATUS`; else substitute auto-vars then call `execute_line`. Update `g_session_failed`/`g_last_status` from the result; honor abort-vs-continue. Called from the main loop in place of the direct `execute_line`.
   - **`substitute_autovars(line) → expanded`** (new): replace whole-token `$?`, `$jobid`, `$jobcount` with current values; a reference with no current value yields a command failure (Req 3.6).
+    > **Superseded by job-array-one-based-index (2026-10-01):** whole-token-only substitution is relaxed: a token that is `$jobid` followed immediately by `[` (e.g. `$jobid[3]`) now has `$jobid` replaced and the rest of the token copied unchanged, and fails like an unset `$jobid` when it is unset (job-array-one-based-index Requirement 4.10, 4.11). Kept for history.
   - **New command handlers**: `cmd_wait_primary`, `cmd_expect_jobs`, `cmd_expect_job`, `cmd_echo`, registered in the command table(s).
   - **`cmd_set`**: add `continue-on-error` toggle.
   - **`cmd_jobsub`**: gate the "ok" report on a successful reply status + valid JobId; on success set `g_last_jobid`; otherwise print a typed error and return `<0` (bug-786).

.kiro/specs/xce-test-e2e-primitives/requirements.md

@@ -42,6 +42,8 @@ This feature adds a small set of scripting primitives to the `xce_test` client s
 1. When any command completes, the xce_test client shall set `$?` to that command's status (zero on success, non-zero on failure).
 2. When a `jobsub` command receives a successful acknowledgment, the xce_test client shall set `$jobid` to the acknowledged JobId.
 3. When a subsequent command references `$jobid` (e.g. `expect-job $jobid`), the xce_test client shall substitute the most recently acknowledged JobId.
+
+> **Superseded by job-array-one-based-index (2026-10-01):** 3.2/3.3 no longer hold for array submissions. After `jobsub -a N` (N >= 2) the acknowledged identity is the array identity (no element number), `$jobid` is set to it, and elements are named `$jobid[k]`, k = 1..N; `$jobid` followed immediately by `[` is now substituted too (see job-array-one-based-index Requirement 4.5, 4.10, 4.11). Ordinary `jobsub` is unchanged. Kept for history.
 4. Where the `$jobcount` auto-variable is provided, when a `joblist` command completes, the xce_test client shall set `$jobcount` to the number of jobs returned.
 5. The xce_test client shall not provide user-assignable variables, arithmetic, or expression evaluation beyond substituting this fixed set of auto-variables.
 6. If a command references an auto-variable that has no current value, then the xce_test client shall fail that command rather than substitute an undefined or garbage value.
@@ -66,6 +68,8 @@ This feature adds a small set of scripting primitives to the `xce_test` client s
 3. When `expect-job <jobid>` is issued and the given JobId is present in the job list, the xce_test client shall treat the assertion as passed.
 4. If `expect-job <jobid>` is issued and the given JobId is absent, then the xce_test client shall fail the assertion and report the missing JobId.
 
+> **Superseded by job-array-one-based-index (2026-10-01):** for arrays, `expect-job <jobid>` no longer matches text: it compares job numbers, an identity without `[k]` that no job has fails with a hint that elements must be named `<array-id>[k]`, `<array-id>[k]` checks element k, and a range `<array-id>[a-b]` is refused (job-array-one-based-index Requirement 4.7-4.9, 5.13, 5.15). Kept for history.
+
 ### Requirement 6: Script ergonomics
 
 **Objective:** As an E2E script author, I want comments, blank lines, and progress messages, so that scenario scripts are readable and self-documenting.
@@ -81,6 +85,8 @@ This feature adds a small set of scripting primitives to the `xce_test` client s
 
 #### Acceptance Criteria
 1. When `jobsub` receives a successful acknowledgment carrying a valid JobId, the xce_test client shall report success and set `$jobid` to that JobId.
+
+> **Superseded by job-array-one-based-index (2026-10-01):** for `jobsub -a N` (N >= 2) the reported identity and `$jobid` are the array identity, not an element JobId; elements are `$jobid[1]`..`$jobid[N]` (job-array-one-based-index Requirement 4.1, 4.5). Kept for history.
 2. If `jobsub` does not receive a successful acknowledgment with a valid JobId, then the xce_test client shall report a typed failure (e.g. redirect, no-master, not-ready, or timeout) and set a non-zero status.
 3. The xce_test client shall never report `jobsub` success with a malformed or uninitialized JobId.