TEST-SPEC.md

# Test Specification for loopx

## 1. Philosophy & Goals

### 1.1 Core Principles

1. **E2E black-box testing is the primary strategy.** Tests exercise the `loopx` binary and programmatic API exactly as users would — by spawning processes, creating fixture scripts, and asserting observable behavior (exit codes, stdout, stderr, file system state). Internal implementation details are not tested directly.

2. **Contract-driven.** Every test traces to a specific SPEC.md requirement. The test suite serves as an executable specification.

3. **Runtime coverage.** Tests run against both Node.js (>= 20.6) and Bun (>= 1.0). Where a test exercises runtime-specific behavior (e.g., module resolution), it is tagged accordingly.

4. **Verification before implementation.** Since the implementation doesn't exist yet, the test suite includes a verification strategy (section 3) to ensure tests are correctly constructed before they can pass.

5. **Fuzz testing for parsers.** The structured output parser and `.env` file parser are exercised with property-based tests to catch edge cases.

6. **Explicit internal test seams.** The implementation must expose certain pure functions as package-private imports for unit and fuzz testing. This is a deliberate design decision — without these seams, high-volume fuzz testing is limited to E2E (50–100 inputs) instead of direct function calls (1000+ inputs). See section 1.4 for details.

### 1.2 Test Priorities

| Priority | Category | Rationale |
|----------|----------|-----------|
| P0 | Loop state machine, structured output parsing, script execution, workflow discovery | Core functionality — if these break, nothing works |
| P1 | Environment variables, CLI options, subcommands, goto semantics | Essential user-facing features |
| P2 | Install command, CLI delegation, signal handling, version checking | Important but less frequently exercised |
| P3 | Edge cases, fuzz tests | Defense in depth |

### 1.3 Coverage Scope

This suite is the **implementation-driving** test suite — it defines the behavior that must pass before a feature is considered complete. It targets complete coverage of all SPEC.md requirements, including:

- **Spec 3.1 (Global Install):** Covered by T-INST-GLOBAL-01, which exercises the full `npm pack` → install into isolated global prefix → run against fixture project workflow. This runs in CI on every build.

- **Spec 7.3 (Signal Handling — between iterations):** Covered by T-SIG-07, which sends a signal between iterations by coordinating via marker files. Tagged `@flaky-retry(3)` due to inherent timing sensitivity. The active-child signal cases (T-SIG-01–06) are fully covered without retry.

- **Spec 9.1 (Async Generator Cancellation):** Multiple cancellation scenarios are tested: "break after yield" (T-API-06), "return during pending next" (T-API-09a), "abort signal during active child" (T-API-10a), "pre-aborted signal" (T-API-10b), and "abort between iterations" (T-API-10c).

### 1.4 Internal Test Seams

The implementation **must** expose the following pure functions as package-private imports for unit and fuzz testing. These are not part of the public API and are not documented in SPEC.md — they exist solely to enable high-volume testing.

**Required exports (via a subpath like `loopx/internal` or a `src/internal.ts` barrel):**

| Function | Signature | Purpose |
|----------|-----------|---------|
| `parseOutput` | `(stdout: string) => Output` | Parses raw stdout into structured Output per Spec 2.3 rules |
| `parseEnvFile` | `(content: string) => { vars: Record<string, string>, warnings: string[] }` | Parses `.env` file content per Spec 8.1 rules. Returns parsed variables and any warning messages for invalid lines |
| `classifySource` | `(source: string) => { type: "git" \| "tarball", url: string }` | Classifies an install source per Spec 10.1 rules. Throws for rejected sources (e.g., single-file URLs) |

**Design constraints:**

- These functions must be **pure** — no I/O, no process spawning, no side effects. They take a string and return a value.
- The `warnings` field in `parseEnvFile` returns the warning messages that would be printed to stderr during normal operation. This allows unit tests to assert on warning behavior without capturing stderr from a child process.
- The exact module path and export mechanism is an implementation detail, but the test suite must be able to `import { parseOutput } from "loopx/internal"` (or equivalent). The implementation may use TypeScript `paths` aliases, a `package.json` `exports` subpath, or a direct relative import from the test files.
- These exports are **not** part of the public semver contract. They may change shape between minor versions.

**These seams are a hard implementation requirement.** Unit tests (section 6.1, 6.2) and high-volume fuzz tests (section 5.1, 5.2) depend on them. The implementation is not considered complete until these exports are available and importable by the test suite.

**Install fault injection (environment variable seam):**

Install atomicity tests (T-INST-80c) must simulate commit-phase failures that are otherwise unreproducible in black-box tests (the commit phase involves only renames, which rarely fail on a healthy filesystem). The implementation must honor the following test-only environment variable:

| Variable | Values | Behavior |
|----------|--------|----------|
| `LOOPX_TEST_INSTALL_FAULT` | `commit-fail-after:<n>` | During the install commit phase, simulate a rename failure (reported as `EACCES`) after `n` successful workflow commits. |

This variable is only checked when `NODE_ENV=test` to prevent accidental use in production. Like the function seams above, this is not part of the public API and may change between versions.

---

## 2. Test Infrastructure

### 2.1 Framework & Tooling

| Tool | Purpose |
|------|---------|
| **Vitest** | Test runner and assertion library. Native ESM, TypeScript, fast. |
| **fast-check** | Property-based / fuzz testing for parsers. |
| **execa** (or `node:child_process`) | Spawning `loopx` CLI processes with fine-grained control over stdio, env, signals. |
| **get-port** | Acquiring free ports for local test servers. |
| **http** (Node built-in) | Local HTTP server for install tests (tarball downloads). |
| **Local bare git repos** | Testing git clone install source (no network dependency). |

### 2.2 Directory Layout

```
tests/
  harness/
    smoke.test.ts              Phase 0 harness validation
  e2e/
    cli-basics.test.ts         CLI invocation, help, version
    subcommands.test.ts        output, env, install subcommands
    discovery.test.ts          Workflow & script discovery, validation
    execution.test.ts          Script execution (bash, JS/TS, workflow cwd)
    output-parsing.test.ts     Structured output parsing
    loop-state.test.ts         Loop state machine, goto semantics, control flow
    env-vars.test.ts           Environment variable management
    module-resolution.test.ts  import from "loopx", output(), input()
    programmatic-api.test.ts   run(), runPromise()
    install.test.ts            loopx install from various sources
    signals.test.ts            Signal handling (SIGINT, SIGTERM)
    delegation.test.ts         Project-root CLI delegation
  fuzz/
    output-parsing.fuzz.test.ts
    env-parsing.fuzz.test.ts
  unit/
    parse-output.test.ts       Output parsing logic (supplementary)
    parse-env.test.ts          Env file parsing logic (supplementary)
    source-detection.test.ts   Install source classification
    types.test.ts              Compile-time type surface verification
  helpers/
    cli.ts                     CLI spawning utilities (runCLI, runCLIWithSignal)
    api-driver.ts              Programmatic API driver (runAPIDriver)
    fixtures.ts                Temp dir, workflow, script, and project creation
    servers.ts                 Local HTTP & git servers, git URL rewriting
    env.ts                     Env file creation, global config, isolated home
    runtime.ts                 Runtime detection & matrix helpers
    delegation.ts              Delegation fixture setup (withDelegationSetup)
```

### 2.3 Helper Library

The helper library provides reusable utilities for all tests. Each helper is designed to be self-cleaning (via Vitest `afterEach` hooks or explicit cleanup functions).

#### `createTempProject(options?): TempProject`

Creates an isolated temporary directory with an optional `.loopx/` subdirectory. Returns an object with:
- `dir`: absolute path to the temp directory
- `loopxDir`: absolute path to `.loopx/` within it
- `cleanup()`: removes the temp directory

All tests use this to avoid cross-contamination.

#### `createWorkflow(project, workflowName): string`

Creates a workflow directory at `.loopx/<workflowName>/` inside the project. Returns the absolute path to the workflow directory. Example:
```typescript
const wfDir = createWorkflow(project, "ralph");
// creates <project.dir>/.loopx/ralph/
```

#### `createWorkflowScript(project, workflowName, scriptName, ext, content): string`

Creates a script file inside a workflow directory. Creates the workflow directory if it does not already exist. Returns the full path to the created file. Example:
```typescript
createWorkflowScript(project, "ralph", "index", ".ts", `
  import { output } from "loopx";
  output({ result: "hello" });
`);
// creates <project.dir>/.loopx/ralph/index.ts
```

#### `createBashWorkflowScript(project, workflowName, scriptName, body): string`

Shorthand for creating a `.sh` script with `#!/bin/bash` header and executable permission inside a workflow. Creates the workflow directory if needed.

#### `createWorkflowPackageJson(project, workflowName, content): string`

Creates a `package.json` file inside a workflow directory. Returns the full path. Used for dependency management and version declaration tests.

#### `runCLI(args, options?): Promise<CLIResult>`

Spawns the `loopx` binary as a child process. Options include:
- `cwd`: working directory (defaults to temp project)
- `env`: additional environment variables
- `runtime`: `"node"` | `"bun"` — controls how the binary is invoked
- `timeout`: max execution time (default 30s)
- `input`: string to pipe to stdin

Returns:
```typescript
interface CLIResult {
  exitCode: number;
  stdout: string;
  stderr: string;
  signal: string | null;
}
```

For **Node.js**, the CLI is spawned as `node /path/to/loopx/bin.js [args]`.
For **Bun**, it is spawned as `bun /path/to/loopx/bin.js [args]`.

**Important:** The CLI never prints `result` to its own stdout (Spec 7.1). To observe parsed `Output` objects, use `runAPIDriver()` or the programmatic API. `runCLI` is for asserting exit codes, stderr output, filesystem side effects, and control flow.

#### `runAPIDriver(runtime, code, options?): Promise<{ stdout: string, stderr: string, exitCode: number }>`

Spawns a tiny driver script under the specified runtime (Node.js or Bun) that imports from the loopx package, runs the provided code string, and prints JSON results to stdout. This is the correct way to test programmatic API behavior under Bun — importing loopx directly inside a Node-hosted Vitest process does not exercise Bun's runtime.

**Import resolution:** The driver must import from the built loopx package as a real consumer would. The helper creates a temporary consumer directory with a `package.json` and a symlinked (or file-protocol-linked) `node_modules/loopx` pointing to the build output. This ensures that `import { run } from "loopx"` exercises the actual package exports, not test-internal paths.

Example:
```typescript
const result = await runAPIDriver("bun", `
  import { runPromise } from "loopx";
  const outputs = await runPromise("ralph", { cwd: "${project.dir}" });
  console.log(JSON.stringify(outputs));
`, { cwd: project.dir });
const outputs = JSON.parse(result.stdout);
```

#### `runCLIWithSignal(args, options): Promise<CLIResult>`

Like `runCLI`, but also returns a `sendSignal(signal)` function and a `waitForStderr(pattern)` function so the test can send SIGINT/SIGTERM at a controlled point during execution.

#### `createEnvFile(path, vars): void`

Writes a `.env` format file with the given key-value pairs. Produces well-formed `KEY=VALUE\n` lines. Suitable for tests that only need valid, simple env files.

#### `writeEnvFileRaw(path, content): void`

Writes raw text to a file at `path` with no transformation. This is the low-level helper for env parser tests that need to control exact file content — duplicate keys, malformed lines, unmatched quotes, comments, blank lines, missing trailing newlines, etc. `createEnvFile` cannot represent these cases.

#### `withGlobalEnv(vars, fn): Promise<void>`

Sets `XDG_CONFIG_HOME` to a temp directory, writes a global env file with the given vars, runs `fn`, then cleans up. This isolates global env tests from the user's real config.

#### `withIsolatedHome(fn): Promise<void>`

Sets `HOME` to a temp directory and optionally unsets `XDG_CONFIG_HOME`, then runs `fn`, then restores. This safely tests the `~/.config` default fallback path without touching the real home directory. Used for T-ENV-04 and related tests.

#### `withDelegationSetup(options): Promise<DelegationFixture>`

Provisions realistic delegation test fixtures: creates actual launcher files and symlinks in `node_modules/.bin/loopx` within a temp project. Returns paths and cleanup. This helper is used for T-DEL-* and LOOPX_BIN tests instead of `runCLI`, because `runCLI`'s `node /path/to/bin.js` invocation does not exercise delegation or realpath resolution.

```typescript
interface DelegationFixture {
  projectDir: string;
  globalBinPath: string;      // path to "global" loopx binary
  localBinPath: string;       // path to "local" loopx in node_modules/.bin/
  runGlobal(args: string[]): Promise<CLIResult>;  // spawns the global binary
  cleanup(): void;
}
```

#### `startLocalHTTPServer(routes): Promise<{ url: string, close: () => void }>`

Starts a local HTTP server serving the specified routes. Used for install tests (tarball downloads).

#### `startLocalGitServer(repos): Promise<{ url: string, close: () => void }>`

Creates local bare git repositories and serves them over a local protocol. Used for `loopx install` git tests. Implementation: create bare repos with `git init --bare`, then clone/commit/push fixture content, and serve via `git daemon` or direct file:// URLs.

#### `withGitURLRewrite(rewrites, fn): Promise<void>`

Sets up an isolated git configuration (via `GIT_CONFIG_GLOBAL` and isolated `HOME`) with `url.<base>.insteadOf` rules so that known-host URLs (e.g., `https://github.com/org/repo.git`) are transparently rewritten to local `file://` bare repos. This allows T-INST-01 through T-INST-04 to test known-host source detection without network access.

```typescript
await withGitURLRewrite({
  "https://github.com/myorg/my-workflow.git": "file:///tmp/bare-repos/my-workflow.git"
}, async () => {
  const result = await runCLI(["install", "myorg/my-workflow"], { cwd: project.dir });
  // Verifies org/repo shorthand expands to github URL, which is rewritten to local repo
});
```

#### `forEachRuntime(fn): void`

Test parameterization helper. Runs a test block once for each available runtime (Node.js, Bun). Skips a runtime if it's not installed. Example:
```typescript
forEachRuntime((runtime) => {
  it("runs a bash script", async () => {
    const result = await runCLI(["run", "-n", "1", "ralph"], { cwd: project.dir, runtime });
    expect(result.exitCode).toBe(0);
  });
});
```

### 2.4 Fixture Scripts

A catalog of reusable fixture scripts used across tests. Each is a function that returns the script content.

| Fixture | Type | Behavior |
|---------|------|----------|
| `emit-result(value)` | bash | `printf '{"result":"%s"}' '<value>'` — uses `printf` (not `echo`) to avoid trailing newline ambiguity |
| `emit-goto(target)` | bash | `printf '{"goto":"%s"}' '<target>'` |
| `emit-stop()` | bash | `printf '{"stop":true}'` |
| `emit-result-goto(value, target)` | bash | `printf '{"result":"%s","goto":"%s"}' '<value>' '<target>'` |
| `emit-raw(text)` | bash | `printf '%s' '<text>'` — exact bytes, no trailing newline unless explicitly included |
| `emit-raw-ln(text)` | bash | `printf '%s\n' '<text>'` — with trailing newline, for tests that need to verify newline handling |
| `exit-code(n)` | bash | `exit <n>` |
| `cat-stdin()` | bash | Reads stdin, echoes it as result |
| `write-stderr(msg)` | bash | `echo '<msg>' >&2` then produces output |
| `sleep-then-exit(seconds)` | bash | Sleeps for `<seconds>`, then exits 0. General-purpose long-running script. For signal tests, prefer the dedicated `signal-*` fixtures which follow the ready-protocol. |
| `write-env-to-file(varname, markerPath)` | bash | `printf '%s' "$VARNAME"` to a marker file. Uses `printf '%s'` (not `echo`) to avoid trailing newline and backslash interpretation. Observation via filesystem, not CLI stdout. |
| `observe-env(varname, markerPath)` | ts | Writes JSON `{ "present": true, "value": "..." }` or `{ "present": false }` to a marker file using `fs.writeFileSync`. Distinguishes unset from empty string. Use instead of `write-env-to-file` when the test must differentiate between a variable being absent vs set to `""`. |
| `write-cwd-to-file(markerPath)` | bash | `printf '%s' "$PWD"` to a marker file. Uses `printf '%s'` (not `echo`) for exact-byte safety. |
| `write-value-to-file(value, markerPath)` | bash | `printf '%s' '<value>'` to a marker file. Uses `printf '%s'` (not `echo`) for exact-byte safety — avoids trailing newlines, backslash interpretation, and issues with values starting with `-`. General-purpose observation helper. |
| `stdout-writer(payloadFile)` | ts | Reads `payloadFile` from disk and writes its contents to stdout via `process.stdout.write()`. Used for fuzz and exact-byte output tests. |
| `ts-output(fields)` | ts | Uses `import { output } from "loopx"` to emit structured output |
| `ts-input-echo()` | ts | Reads input(), outputs it as result |
| `ts-import-check()` | ts | Imports from "loopx", outputs success marker |
| `signal-ready-then-sleep(markerPath)` | bash | Writes `$$` (the script's PID) to a marker file using `printf '%s'`, then writes `"ready"` to stderr, then sleeps indefinitely. The stderr marker allows the test harness to `waitForStderr("ready")` before sending a signal, ensuring the child is alive. |
| `signal-trap-exit(markerPath, delay)` | bash | Traps SIGTERM with a handler that sleeps for `<delay>` seconds then exits 0. On startup, writes `$$` to a marker file using `printf '%s'` and writes `"ready"` to stderr. Used for grace-period tests — delay < 5s tests clean exit, delay > 5s tests SIGKILL escalation. |
| `signal-trap-ignore(markerPath)` | bash | Traps SIGTERM and ignores it (handler is a no-op). On startup, writes `$$` to a marker file using `printf '%s'` and writes `"ready"` to stderr, then sleeps indefinitely. Used for SIGKILL-after-grace-period tests (T-SIG-05). |
| `spawn-grandchild(markerPath)` | bash | Spawns a background subprocess (e.g., `sleep 3600 &`), writes both `$$` (script PID) and `$!` (grandchild PID) to a marker file (one per line) using `printf '%s\n'`, writes `"ready"` to stderr, then `wait`s. For process group signal tests (T-SIG-06). |
| `write-pid-to-file(markerPath)` | ts | Writes `process.pid` to a marker file using `fs.writeFileSync`, writes `"ready"` to stderr, then runs a long-running operation (e.g., `setTimeout(() => {}, 999999)`). Used for API cancellation tests (T-API-09a, T-API-10a) where a JS/TS script is needed. |
| `counter(file)` | bash | Appends "1" to a counter file each invocation, outputs count as result |

**Fixture naming note:** The `emit-*` fixtures replace the previous `echo-*` fixtures. `printf` is used instead of `echo` to provide exact byte control — `echo` appends a trailing newline which can mangle exact byte expectations in parser tests. For tests that specifically need to verify trailing-newline handling, use `emit-raw-ln`. The `write-*-to-file` fixtures observe values via the filesystem rather than CLI stdout, since the CLI never prints `result` to its own stdout (Spec 7.1). All bash `write-*-to-file` fixtures use `printf '%s'` (not `echo`) to write values, ensuring exact-byte safety for trailing spaces, backslashes, and values starting with `-`. The `observe-env` fixture is a TS-based alternative to `write-env-to-file` that writes structured JSON (`{ "present": boolean, "value"?: string }`) to a marker file using `fs.writeFileSync` for exact-byte safety. Use `observe-env` when a test must distinguish between a variable being unset vs set to an empty string — `write-env-to-file` (bash `printf '%s' "$VAR"`) produces identical output for both cases.

**Signal/cancellation fixtures:** The `signal-ready-then-sleep`, `signal-trap-exit`, `signal-trap-ignore`, `spawn-grandchild`, and `write-pid-to-file` fixtures are purpose-built for signal and cancellation tests. They all follow a common protocol: (1) write PID(s) to a marker file on startup, (2) write `"ready"` to stderr, (3) block. The stderr marker allows `waitForStderr("ready")` to synchronize the test harness before sending signals, preventing races. The marker file PIDs allow post-test verification that processes were actually killed.

**Bash JSON safety warning:** The `emit-result`, `emit-goto`, and `emit-result-goto` fixtures use `printf` with `%s` substitution to produce JSON. This is only safe for simple string values that do not contain double quotes (`"`), backslashes (`\`), newlines, or other JSON-special characters — these would produce malformed JSON. For tests that require exact-byte control, JSON-special characters in values, or arbitrary binary content, use the `stdout-writer` TS fixture (which reads a pre-written payload from disk) or `emit-raw`/`emit-raw-ln` (which output exact bytes without JSON framing).

**Workflow fixture convention:** All fixture scripts are created inside workflow directories using `createWorkflowScript` or `createBashWorkflowScript`. A typical single-script test creates a workflow (e.g., `myscript`) with an `index` script. A multi-script test creates multiple scripts within one or more workflows.

### 2.5 Runtime Matrix

Tests are parameterized over runtimes where applicable:

| Category | Node.js | Bun |
|----------|---------|-----|
| CLI basics, help, version | Yes | Yes |
| Subcommands (output, env) | Yes | Yes |
| Workflow & script discovery | Yes | Yes |
| Bash script execution | Yes | Yes |
| JS/TS script execution | Yes | Yes |
| Module resolution (`import from "loopx"`) | Yes (--import hook) | Yes (NODE_PATH) |
| Programmatic API | Yes | Yes |
| Install command | Yes | Yes |
| Signal handling | Yes | Yes |
| CLI delegation | Yes | Yes |

A test should be skipped (not failed) if its required runtime is not available in the environment.

### 2.6 Local Test Servers

#### HTTP Server

A lightweight `http.createServer` instance serves fixture files for install tests:
- **Tarball routes:** Serve `.tar.gz` archives created on-the-fly from fixture directories.
- **Query string routes:** Serve files at URLs with `?token=abc` to test query stripping.
- **Error routes:** Return 404, 500, etc. to test error handling.
- **Rejected URL routes:** Serve files at non-tarball, non-git URLs to test single-file URL rejection.

The server starts in `beforeAll` and closes in `afterAll` for the install test suite.

#### Git Server

For git install tests, use `file://` protocol URLs pointing to local bare repos:
1. Create a temp directory with `git init --bare`.
2. Clone it to a working directory, add fixture files (workflow scripts, optional `package.json`), commit, push.
3. Tests use `file:///path/to/bare/repo.git` as the install source.

This avoids any network dependency and is fast. The bare repos are created in `beforeAll` and cleaned up in `afterAll`.

---

## 3. Test Verification Strategy

The central challenge: tests are written before the implementation exists. We need confidence that when a test passes, it genuinely validates the spec requirement — not that it passes vacuously.

### 3.1 Phase 0: Harness Validation

**Purpose:** Verify the test infrastructure works correctly. These tests pass without any loopx implementation.

**Tests (`tests/harness/smoke.test.ts`):**

- **H-01: Temp project creation and cleanup.** `createTempProject()` creates a directory that exists, `cleanup()` removes it.
- **H-02: Workflow and script fixture creation.** `createWorkflowScript()` writes a file inside `.loopx/<workflow>/` with correct content and permissions.
- **H-03: Workflow directory creation.** `createWorkflow()` creates a workflow directory at `.loopx/<name>/`.
- **H-04: Bash script is executable.** A created `.sh` fixture has the execute permission bit set.
- **H-05: Env file creation.** `createEnvFile()` writes a file that can be read back and contains the expected content.
- **H-06: Process spawning captures exit code.** Spawn `node -e "process.exit(42)"` and assert exit code is 42.
- **H-07: Process spawning captures stdout.** Spawn `echo hello` and assert stdout is `"hello\n"`.
- **H-08: Process spawning captures stderr.** Spawn `node -e "console.error('err')"` and assert stderr contains `"err"`.
- **H-09: Process spawning respects cwd.** Spawn `pwd` with a specific cwd and assert the output matches.
- **H-10: Process spawning respects env.** Spawn `echo $MY_VAR` with `MY_VAR=hello` and assert output.
- **H-11: Signal delivery works.** Spawn a sleeping process, send SIGTERM, assert it terminates.
- **H-12: Local HTTP server starts and serves content.** Start server, fetch a route, assert response body.
- **H-13: Local git repo is cloneable.** Create a bare repo with fixture content, clone it, verify files exist.
- **H-14: Runtime detection.** `forEachRuntime` correctly detects available runtimes.
- **H-15: Global env isolation.** `withGlobalEnv` uses a temp directory and doesn't touch the real `~/.config`.

**All Phase 0 tests must pass before any Phase 1 tests are run.** If Phase 0 fails, the test infrastructure is broken and Phase 1 results are meaningless. Vitest's `--bail` flag can enforce this.

### 3.2 Stub Validation

Before the real implementation exists, we create a **minimal stub** — a shell script that:
- Exits 0 for all invocations
- Produces no stdout
- Ignores all arguments

When the Phase 1 (spec) tests are run against this stub, **nearly all should fail.** Any spec test that passes against the stub is suspect — it may be testing nothing. This is a one-time validation step, not a permanent part of CI.

**Procedure:**
1. Create the stub binary:
   ```bash
   #!/bin/bash
   exit 0
   ```
2. Point `runCLI` at the stub.
3. Run the spec test suite.
4. Maintain a small **allowlist** of test IDs that are expected to pass against the stub for legitimate reasons (e.g., `-n 0` exits 0 coincidentally). Review only passes outside this allowlist.
5. Inspect unexpected passes: they either have a weak assertion that should be strengthened, or represent a genuine test error.
6. Revise flagged tests to include assertions that would fail against the stub (e.g., check stderr for expected messages, verify specific stdout content, check file system side effects).

### 3.3 Test Categorization

Each test file uses Vitest's `describe` blocks with category labels:

- **`describe("HARNESS: ...")`** — Phase 0 tests. Must pass without implementation.
- **`describe("SPEC: ...")`** — Spec requirement tests. Expected to fail until implemented.
- **`describe("FUZZ: ...")`** — Property-based tests. Expected to fail until implemented.

During implementation, as features are built, the corresponding SPEC tests should transition from failing to passing. A test that continues to fail after its feature is implemented indicates either a bug in the implementation or a bug in the test.

---

## 4. E2E Test Cases

Each test is identified by a unique ID (`T-<SECTION>-<NUMBER>`), references a SPEC.md section, and specifies its runtime scope. Unless marked `[Node]` or `[Bun]`, tests run on both runtimes.

### 4.1 CLI Basics

**Spec refs:** 4.1, 4.2, 4.3, 11.1, 11.2

#### Help & Version

- **T-CLI-01**: `loopx version` prints the bare package version string followed by a newline, exits 0. Assert exact stdout is `${version}\n` — the spec requires a trailing newline, so assert against the untrimmed stdout, not a trimmed comparison. No additional text or labels. Does not require `.loopx/` to exist. *(Spec 4.3, 5.4)*

#### Top-Level Help

- **T-CLI-02**: `loopx -h` prints usage text containing "loopx" and "usage" (case-insensitive), exits 0. Assert that the output lists the available subcommands: `run`, `version`, `output`, `env`, and `install` must all appear in the help text. Does not list workflows — top-level help performs no discovery. Additionally assert: (a) the top-level usage line presents a subcommand-based grammar (not a legacy flat-script form like `loopx [options] [script-name]`), and (b) `-n` and `-e` are not presented as top-level flags in the options listing (these are `run`-scoped — mentioning them in a subcommand description is acceptable, but they must not appear as top-level option entries). These assertions guard against stale help text that advertises removed behavior. *(Spec 4.2, 11.1)*
- **T-CLI-03**: `loopx --help` produces identical stdout, stderr, and exit code as `loopx -h`. Run both in the same fixture containing `.loopx/` with workflows, a name collision (e.g., `check.sh` and `check.ts` in the same workflow), and an invalid workflow name. Assert: (a) stdout is byte-identical between the two invocations, (b) stderr is byte-identical (both empty — no discovery or validation warnings), and (c) both exit 0. This proves the `--help` long form is a true alias for `-h` including the non-discovery guarantee, not just a help-text match in a clean fixture. *(Spec 4.2, 11.1)*
- **T-CLI-04**: `loopx -h` with `.loopx/` containing workflows does NOT list discovered workflow or script names in output. Top-level help performs no discovery. Assert that stdout does not contain any of the workflow or script names. *(Spec 4.2, 11.1)*
- **T-CLI-05**: `loopx -h` without `.loopx/` directory still prints help (no error). No workflow list, no warnings. *(Spec 4.2, 11.1)*
- **T-CLI-06**: `loopx -h` with `.loopx/` containing name collisions does NOT print warnings on stderr. Top-level help performs no validation. *(Spec 4.2, 11.1)*
- **T-CLI-07e**: `loopx -h version` prints top-level help and exits 0 (top-level `-h` takes precedence over everything that follows). The `version` subcommand does not execute. *(Spec 4.2)*
- **T-CLI-07f**: `loopx -h env set FOO bar` prints top-level help and exits 0 (top-level `-h` takes precedence over `env` subcommand). *(Spec 4.2)*
- **T-CLI-07g**: `loopx -h --invalid-flag` prints top-level help and exits 0 (top-level `-h` takes precedence over invalid flags). *(Spec 4.2)*
- **T-CLI-07j**: `loopx -h -e nonexistent.env` prints top-level help and exits 0 (top-level `-h` takes precedence over `-e`). The nonexistent env file is not read or validated. *(Spec 4.2)*
- **T-CLI-39**: `loopx -h run foo` shows top-level help (not run help) and exits 0. Top-level `-h` takes precedence over everything that follows, including `run` subcommand dispatch. *(Spec 4.2)*
- **T-CLI-61**: `loopx --help run foo` shows top-level help (not run help) and exits 0. Same behavior as `loopx -h run foo` — verifies that the `--help` long form has identical precedence semantics to `-h` when followed by additional arguments. *(Spec 4.2)*
- **T-CLI-90**: `loopx --help --invalid-flag` prints top-level help and exits 0 (top-level `--help` takes precedence over invalid flags). This is the `--help` long-form counterpart to T-CLI-07g (`loopx -h --invalid-flag`), verifying both help spellings suppress subsequent invalid flags identically. *(Spec 4.2)*
- **T-CLI-91**: `loopx --help -e nonexistent.env` prints top-level help and exits 0 (top-level `--help` takes precedence over `-e`). The nonexistent env file is not read or validated. This is the `--help` long-form counterpart to T-CLI-07j (`loopx -h -e nonexistent.env`). *(Spec 4.2)*

#### Run Help

- **T-CLI-40**: `loopx run -h` with `.loopx/` containing workflows prints run-specific help that includes: (a) run syntax showing the target form (e.g., `loopx run [options] <workflow>[:<script>]` or equivalent), (b) the `-n` and `-e` options with descriptions, and (c) a list of discovered workflows and their scripts. If a workflow has an `index` script, it is indicated as the default entry point. Exits 0. *(Spec 4.2, 11.2)*
- **T-CLI-40a**: `loopx run -h` advertises the workflow-based invocation grammar, not the legacy flat-script form. Assert that the run help usage line presents the workflow-based target form (e.g., `<workflow>[:<script>]` or equivalent) as the positional argument. The positive check for the correct grammar is more robust than blacklisting individual words. Additionally verify that the usage line does not show `<script>` as a bare top-level positional argument (the old flat-script form was `loopx run [options] <script>`). This is the run-help counterpart to T-CLI-02's grammar assertions, applied to the `run` subcommand where ADR-0003 changed the grammar most directly. *(Spec 4.2, 11.2)*
- **T-CLI-41**: `loopx run --help` produces identical stdout, stderr, and exit code as `loopx run -h`. Run both in the same fixture containing `.loopx/` with valid workflows and a name collision (e.g., `check.sh` and `check.ts` in the same workflow). Assert: (a) stdout is byte-identical between the two invocations, (b) stderr is byte-identical (both should contain the same non-fatal discovery/validation warnings — collision warnings), and (c) both exit 0. This proves the `--help` long form is a true alias for `-h` including non-fatal warning behavior, not just a help-text match in a clean fixture. *(Spec 4.2, 11.2)*
- **T-CLI-42**: `loopx run -h` without `.loopx/` directory still prints run help with a warning that the directory was not found. The discovered-workflows section is omitted. Exits 0. *(Spec 11.2)*
- **T-CLI-43**: `loopx run -h` with `.loopx/` containing name collisions (e.g., `check.sh` and `check.ts` in the same workflow) prints run help with warnings on stderr about the conflicting entries. Exits 0. *(Spec 5.2, 11.2)*
- **T-CLI-43a**: `loopx run -h` with `.loopx/` containing an `index` name collision (`index.sh` and `index.ts` in the same workflow) prints run help with warnings on stderr about the conflicting `index` entries. Exits 0. This is the `index`-specific variant of T-CLI-43 — a bad implementation could special-case `index` and bypass collision warnings for the default entry point. *(Spec 2.1, 5.2, 11.2)*
- **T-CLI-44**: `loopx run -h` with `.loopx/` containing a script with an invalid name (e.g., `-startswithdash.sh`) prints run help with a non-fatal warning on stderr about the invalid name. Assert: (a) stderr contains a warning mentioning the offending script name (e.g., `-startswithdash`), and (b) stdout (the help output) lists the offending script name within the context of its parent workflow's script listing — per Spec 5.3, "the invalid entry is listed with a warning." Help still exits 0. *(Spec 5.3, 11.2)*
- **T-CLI-101**: `loopx run -h` with `.loopx/` containing a workflow that has an `index` script indicates the default entry point in the output. Assert that the help text marks `index` as the default entry point for that workflow. *(Spec 11.2)*
- **T-CLI-101a**: `loopx run -h` with `.loopx/` containing a workflow that has **no** `index` script (e.g., `.loopx/tools/` with only `check.sh` and `deploy.sh`). Assert: (a) the workflow is still listed in the discovered-workflows output, (b) no script is marked as the default entry point for that workflow, and (c) the workflow's actual scripts (`check` and `deploy`) are listed in the help output. This is the converse of T-CLI-101 and pins down the ADR-0003 behavior that workflows without `index` are discoverable and fully listed in help — including their scripts — but have no default entry point indication. *(Spec 11.2)*
- **T-CLI-102**: `loopx run -h` with `.loopx/` containing a workflow with invalid script names shows non-fatal warnings. The workflow is still listed. Exits 0. *(Spec 5.3, 11.2)*
- **T-CLI-104**: `loopx run -h` with `.loopx/` containing non-workflow files directly in `.loopx/` root (e.g., `.loopx/loose-script.sh`) — the files are neither listed nor warned about. Only workflow subdirectories appear. *(Spec 5.1, 11.2)*
- **T-CLI-104a**: `loopx run -h` with `.loopx/` containing an empty subdirectory (`.loopx/empty/`) alongside a valid workflow (`.loopx/ralph/index.sh`). The empty directory is not a workflow (no top-level script files) and is neither listed in the workflow discovery output nor warned about on stderr. Only `ralph` appears. *(Spec 5.1, 11.2)*
- **T-CLI-104b**: `loopx run -h` with `.loopx/` containing a subdirectory with only non-script files (`.loopx/meta/` containing `config.json` and `notes.md`) alongside a valid workflow (`.loopx/ralph/index.sh`). The `meta` directory is not a workflow (no supported-extension files) and is neither listed in the workflow discovery output nor warned about on stderr. Only `ralph` appears. *(Spec 5.1, 11.2)*
- **T-CLI-104c**: `loopx run -h` with `.loopx/mypipeline/` containing `package.json` and a nested `src/run.js`, but no top-level file with a supported script extension. `mypipeline` is not a workflow — directory scripts are removed (ADR-0003); only top-level script files count for workflow detection. Assert `mypipeline` is neither listed in the discovered-workflows output nor warned about on stderr. *(Spec 5.1, 11.2)*
- **T-CLI-104d**: Same fixture as T-DISC-14a: `.loopx/ralph/index.sh` plus `.loopx/ralph/lib/-bad.ts` (invalid script name) and `.loopx/ralph/lib/check.sh` + `.loopx/ralph/lib/check.ts` (same-base-name collision). `loopx run -h` lists `ralph` with no warnings about the nested invalid entries on stderr. Assert that neither `-bad` nor `check` (from the `lib/` subdirectory) appears in any warning. This is the `-h` counterpart to T-DISC-14a, proving subdirectory contents are invisible to both runtime validation and help-mode warning generation. *(Spec 5.1, 11.2)*
- **T-CLI-104e**: `loopx run -h` with `.loopx/ralph/index.sh` and `.loopx/ralph/lib/helpers.ts`. Assert that stdout lists `ralph` as a discovered workflow and `index` as its script, but `helpers` does not appear anywhere in stdout. This is the help-listing counterpart to T-DISC-14 — nested files must not appear in the discovered scripts list, not just be absent from warnings (which T-CLI-104d covers). A buggy discovery that suppresses warnings but still enumerates nested files in the help listing would pass T-CLI-104d but fail here. *(Spec 5.1, 11.2)*
- **T-CLI-105**: `loopx run ralph -h` is equivalent to `loopx run -h` — the `-h` short-circuit applies, and the workflow argument is ignored. Assert identical stdout/stderr to `loopx run -h`. *(Spec 4.2, 11.2)*
- **T-CLI-106**: `loopx run ralph:index -h` is equivalent to `loopx run -h` — the target argument including script is ignored. *(Spec 4.2, 11.2)*
- **T-CLI-62**: `loopx run myscript --help` shows run help and exits 0. Same behavior as `loopx run myscript -h` — verifies that the `--help` long form triggers the run-help short-circuit identically to `-h` when appearing after a target name. *(Spec 4.2, 11.2)*
- **T-CLI-120**: `loopx run -h` with `.loopx/` containing a workflow with an invalid name (e.g., `.loopx/-bad-workflow/index.sh`) prints run help with a non-fatal warning on stderr about the invalid workflow name. Assert: (a) stderr contains a warning mentioning the offending workflow name (e.g., `-bad-workflow`), and (b) stdout (the help output) lists the offending workflow name in the discovered-workflows section — per Spec 5.3, "the invalid entry is listed with a warning." Help still exits 0. *(Spec 5.3, 11.2)*
- **T-CLI-120a**: `loopx run -h` with `.loopx/` containing a workflow whose name contains `:` (e.g., `.loopx/foo:bar/index.sh`) prints run help with a non-fatal warning on stderr about the invalid workflow name. Assert: (a) stderr contains a warning mentioning the offending workflow name (e.g., `foo:bar`), (b) stdout (the help output) lists the offending workflow name in the discovered-workflows section — per Spec 5.3, "the invalid entry is listed with a warning," and (c) exit code 0. T-CLI-120 covers the generic invalid-name path (leading dash); T-DISC-32 covers the runtime fatal case for `:` in a workflow name. This test exercises the ADR-0003 reserved-delimiter `:` specifically on the non-fatal help path, ensuring the new reserved-delimiter rule is enforced consistently across both validation modes (fatal at run, non-fatal warning at `run -h`) — a buggy implementation could special-case `:` to be silently ignored or fatal under help. *(Spec 5.3, 11.2)*
- **T-CLI-120b**: `loopx run -h` with `.loopx/` containing a workflow whose script base name contains `:` (e.g., `.loopx/ralph/index.sh` alongside `.loopx/ralph/check:ready.sh`) prints run help with a non-fatal warning on stderr about the invalid script name. Assert: (a) stderr contains a warning mentioning the offending script name (e.g., `check:ready`), (b) stdout (the help output) lists the offending script name under the `ralph` workflow's script listing — per Spec 5.3, "the invalid entry is listed with a warning," and (c) exit code 0. T-DISC-31 covers the runtime fatal case for `:` in a script name, and T-CLI-120a covers the help-path reserved-delimiter rule at the workflow-name level. This test is the script-name reserved-delimiter counterpart to T-CLI-120a: it ensures the ADR-0003 `:`-exclusion rule is enforced consistently on the non-fatal help path for script names as well as workflow names — a buggy implementation could apply the reserved-delimiter check only at the workflow-name level and miss it at the script-name level, or special-case `:` to be silently ignored or fatal under help. *(Spec 5.3, 11.2)*
- **T-CLI-121**: `loopx run -h` lists a symlinked workflow under the **symlink's own name**, not the target directory's name. Same setup as T-DISC-39: create a workflow directory outside `.loopx/` (e.g., `/tmp/real-workflow/` with `index.sh`), then symlink `.loopx/my-alias/ → /tmp/real-workflow/`. Assert: (a) stdout contains `my-alias` in the discovered-workflows listing, and (b) stdout does **not** contain the target directory's basename (e.g., `real-workflow`). This is the run-help counterpart to T-DISC-39 (runtime symlink naming) — discovery-time naming is covered, but users see names via `run -h`, so symlink naming must be correct in help output too. *(Spec 5.1, 11.2)*
- **T-CLI-122**: `loopx run -h` lists a symlinked script under the **symlink's basename**, not the target file's name. Same setup as T-DISC-40: create `.loopx/ralph/` with `index.sh` and a symlink `my-check.sh → /tmp/original-check.sh`. Assert: (a) stdout contains `my-check` in the `ralph` workflow's script listing, and (b) stdout does **not** contain `original-check`. This is the run-help counterpart to T-DISC-40 (runtime symlink naming for scripts). *(Spec 5.1, 11.2)*

#### Run Help Short-Circuit

Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows run help, exits 0, and ignores all other run-level arguments unconditionally.

- **T-CLI-48**: `loopx run -h foo` shows run help and exits 0 (target name ignored). *(Spec 4.2)*
- **T-CLI-49**: `loopx run ralph -h` shows run help and exits 0 (`-h` after target name still triggers help short-circuit). In the same fixture, assert that stdout and stderr are identical to `loopx run -h` output and that exit code is 0 — proving the short-circuit produces the canonical run-help behavior, not a degraded or partial variant. *(Spec 4.2, 11.2)*
- **T-CLI-50**: `loopx run -h -e missing.env` shows run help and exits 0 (env file not validated). *(Spec 4.2)*
- **T-CLI-51**: `loopx run -h -n bad` shows run help and exits 0 (`-n` not validated). *(Spec 4.2)*
- **T-CLI-52**: `loopx run -h -n 5 -n 10` shows run help and exits 0 (duplicate `-n` not rejected under help). *(Spec 4.2)*
- **T-CLI-53**: `loopx run -h foo bar` shows run help and exits 0 (extra positional not rejected under help). *(Spec 4.2)*
- **T-CLI-54**: `loopx run -h --unknown` shows run help and exits 0 (unknown flag not rejected under help). *(Spec 4.2)*
- **T-CLI-63**: `loopx run -h -e a.env -e b.env` shows run help and exits 0 (duplicate `-e` not rejected under help). *(Spec 4.2)*
- **T-CLI-67**: `loopx run ralph -h --unknown` shows run help and exits 0. The `-h` after the target name triggers the help short-circuit, suppressing the unknown flag error. *(Spec 4.2)*
- **T-CLI-68**: `loopx run ralph -h -e missing.env` shows run help and exits 0. The `-h` after the target name triggers the help short-circuit, suppressing env file validation. *(Spec 4.2)*
- **T-CLI-69**: `loopx run --help --unknown` shows run help and exits 0. Verifies that the `--help` long form inherits the full ignore-everything-else short-circuit semantics, not just help display. *(Spec 4.2)*
- **T-CLI-70**: `loopx run ralph --help -e missing.env` shows run help and exits 0. Verifies that the `--help` long form after a target name suppresses env file validation identically to `-h`. *(Spec 4.2)*
- **T-CLI-92**: `loopx run -h -n` shows run help and exits 0 (missing `-n` operand not rejected under help). *(Spec 4.2)*
- **T-CLI-93**: `loopx run -h -e` shows run help and exits 0 (missing `-e` operand not rejected under help). *(Spec 4.2)*
- **T-CLI-94**: `loopx run --help -n` shows run help and exits 0 (long-form help, missing `-n` operand not rejected). *(Spec 4.2)*
- **T-CLI-95**: `loopx run --help -e` shows run help and exits 0 (long-form help, missing `-e` operand not rejected). *(Spec 4.2)*

#### Late-Help Short-Circuit (Invalid Args Before `-h`)

- **T-CLI-73**: `loopx run --unknown -h` shows run help and exits 0. *(Spec 4.2)*
- **T-CLI-74**: `loopx run -e missing.env -h` shows run help and exits 0. *(Spec 4.2)*
- **T-CLI-75**: `loopx run -n 5 -n 10 -h` shows run help and exits 0. *(Spec 4.2)*
- **T-CLI-76**: `loopx run foo bar -h` shows run help and exits 0. *(Spec 4.2)*
- **T-CLI-77**: `loopx run -n bad -h` shows run help and exits 0. *(Spec 4.2)*
- **T-CLI-78**: `loopx run --unknown --help` shows run help and exits 0. *(Spec 4.2)*
- **T-CLI-78a**: `loopx run ":script" -h` shows run help and exits 0. The malformed target (leading colon) before `-h` does not prevent the help short-circuit. This proves help suppresses the target validation rules introduced for the `workflow:script` syntax. *(Spec 4.1, 4.2)*
- **T-CLI-78b**: `loopx run "a:b:c" --help` shows run help and exits 0. The malformed target (multiple colons) before `--help` does not prevent the help short-circuit. *(Spec 4.1, 4.2)*
- **T-CLI-78c**: `loopx run "bad.name" -h` shows run help and exits 0. The target `bad.name` violates the name restriction pattern `[a-zA-Z0-9_][a-zA-Z0-9_-]*` (the dot is not allowed), but the help short-circuit ignores it. T-CLI-78a/78b cover malformed colon forms; this covers a name-pattern violation in a non-colon target. *(Spec 4.1, 4.2)*
- **T-CLI-78d**: `loopx run "ralph:-bad" --help` shows run help and exits 0. The target `ralph:-bad` has a valid workflow portion but the script portion (`-bad`) violates the name restriction pattern (leading hyphen). The help short-circuit ignores the entire target, including script-portion validation. *(Spec 4.1, 4.2)*
- **T-CLI-84**: `loopx run -e a.env -e b.env -h` shows run help and exits 0. *(Spec 4.2)*

#### Bare Invocation & Top-Level Parsing Errors

- **T-CLI-28**: `loopx` with no arguments shows top-level help (equivalent to `loopx -h`). Exits 0. Set up `.loopx/` containing a name collision in a workflow. Assert that stdout is identical to `loopx -h` output, that stdout does not contain any workflow names, and that stderr does not contain any discovery or validation warnings. This proves bare `loopx` truly behaves as top-level help and does not inspect `.loopx/`. *(Spec 4.1, 4.2, 5.4)*
- **T-CLI-33**: `loopx ralph` is a usage error (unrecognized subcommand, no implicit fallback to `run`). Create `.loopx/ralph/index.sh` that writes a known value to a marker file. Assert exit code 1 AND assert the marker file does not exist (proving the script was not executed despite being present). *(Spec 4.1)*
- **T-CLI-34**: `loopx --unknown` is a usage error (unrecognized top-level flag). Exit code 1. *(Spec 4.2)*
- **T-CLI-71**: `loopx -x` is a usage error (unrecognized top-level short flag). Exit code 1. *(Spec 4.2)*
- **T-CLI-36**: `loopx -n 5 ralph` is a usage error (top-level `-n` rejected — only `-h` is recognized at top level). Exit code 1. *(Spec 4.2)*
- **T-CLI-37**: `loopx -e .env ralph` is a usage error (top-level `-e` rejected). Exit code 1. *(Spec 4.2)*
- **T-CLI-07b**: `loopx -n 5 -h` is a usage error (exit code 1). The first argument is `-n`, which is not `-h` and not a recognized subcommand, so top-level parsing fails before `-h` is reached. *(Spec 4.2)*
- **T-CLI-07c**: `loopx ralph -h` is a usage error (exit code 1). `ralph` is an unrecognized token in the subcommand position. *(Spec 4.2)*
- **T-CLI-38**: `loopx foo -h` is a usage error (unrecognized subcommand, exit code 1 — not top-level help). *(Spec 4.2)*
- **T-CLI-79**: `loopx foo --help` is a usage error (unrecognized subcommand, exit code 1 — not top-level help). *(Spec 4.2)*

#### Target Invocation via `run`

- **T-CLI-30**: `loopx run -n 1 ralph` with `.loopx/ralph/index.sh` runs the script. Assert via marker file: the script writes a known value to a marker file, confirming execution. *(Spec 4.1)*
- **T-CLI-11**: `loopx run ralph` (no `-n`, no `-e`) with `.loopx/ralph/index.sh` that outputs `{"stop":true}` on the first iteration. Assert via marker file that the script executed AND assert exit code 0. *(Spec 4.1)*
- **T-CLI-107**: `loopx run ralph:check-ready` with `.loopx/ralph/check-ready.sh` runs the specified script. Assert via marker file. *(Spec 4.1)*
- **T-CLI-108**: `loopx run ralph:index` is equivalent to `loopx run ralph`. Both run `.loopx/ralph/index.sh`. Assert via marker file that the same script executes in both cases. *(Spec 4.1)*
- **T-CLI-109**: `loopx run ralph` where `.loopx/ralph/` exists but has no `index` script → exits with code 1 (error about missing default entry point). The workflow has other scripts (e.g., `check.sh`) but no `index`. *(Spec 4.1, 7.2)*
- **T-CLI-109a**: `loopx run ralph:index` where `.loopx/ralph/` exists but has no `index` script → exits with code 1 (error about missing script `index` in workflow `ralph`). The workflow has other scripts (e.g., `check.sh`) but no `index.*`. The explicit `:index` target follows the ordinary missing-script rule rather than the bare default-entry-point rule — ADR-0003 makes `index` special only when the script portion of the target is omitted. T-CLI-109 covers the bare `loopx run ralph` case (missing-default-entry error path); this test pins down the explicit `loopx run ralph:index` case so a buggy implementation cannot special-case `:index` to fall back to "any other script" or to silently succeed. *(Spec 4.1, 7.2)*
- **T-CLI-110**: `loopx run ralph:check` where `.loopx/ralph/` exists and has `check.sh` but no `index` → runs successfully. A workflow without `index` is valid when targeting explicit scripts. *(Spec 4.1)*
- **T-CLI-12**: `loopx run nonexistent` with `.loopx/` existing but no matching workflow exits with code 1. *(Spec 4.1)*
- **T-CLI-111**: `loopx run ralph:nonexistent` with `.loopx/ralph/` existing but no matching script → exits with code 1 (error about missing script in workflow). *(Spec 4.1, 7.2)*
- **T-CLI-111a**: `loopx run check-ready` where `.loopx/ralph/check-ready.sh` exists but no `.loopx/check-ready/` workflow → exits with code 1 (no matching workflow). Assert that `ralph:check-ready` is NOT executed (no marker file written). A bare `run` target is always a workflow name — it must not resolve to a script inside another workflow. This is the core ADR-0003 disambiguation: `run` addresses workflows, `goto` addresses scripts. *(Spec 2.2, 4.1)*
- **T-CLI-13**: `loopx run -n 1 default` runs the `index` script in a workflow named `default` — `default` has no special behavior. Assert via marker file. *(Spec 4.1)*
- **T-CLI-29**: `loopx run` with no target is a usage error (exit code 1). This does not inspect `.loopx/` or perform discovery. *(Spec 4.1)*
- **T-CLI-64**: `loopx run` with no target, with `.loopx/default/index.sh` present — still exits 1. There is no implicit default workflow concept. *(Spec 4.1)*
- **T-CLI-65**: `loopx` (bare invocation) with `.loopx/default/index.sh` present — shows top-level help and exits 0. There is no implicit default workflow concept. *(Spec 4.1, 4.2, 11.1)*
- **T-CLI-59**: `loopx run -n 5` (options present but no target) is a usage error (exit code 1). Assert exit code 1 AND assert stderr does not contain any discovery or validation warnings. *(Spec 4.1, 5.1)*
- **T-CLI-60**: `loopx run` with `.loopx/` containing a name collision — still exits with code 1 as a usage error (missing target), AND stderr does not contain any discovery warnings. *(Spec 4.1, 5.1)*
- **T-CLI-85**: `loopx run -e missing.env` (no target, with `-e`) exits with code 1 as a usage error (missing target). Assert stderr does not mention the missing env file. *(Spec 4.1, 4.2, 5.1)*
- **T-CLI-31**: `loopx run -n 1 version` with `.loopx/version/index.sh` runs the script named `version`, not the built-in subcommand. Assert via marker file that the script executed. Also assert that CLI stdout is empty — proving `run version` dispatched to the workflow, not the built-in `version` subcommand. *(Spec 4.1)*
- **T-CLI-32**: `loopx run -n 1 run` with `.loopx/run/index.sh` runs the workflow named `run`. Assert via marker file. *(Spec 4.1)*
- **T-CLI-66**: `loopx version` with `.loopx/version/index.sh` present still prints the CLI version string and exits 0. The workflow is not executed. *(Spec 4.1, 4.3)*
- **T-CLI-80**: `loopx output --result "x"` with `.loopx/output/index.sh` present still runs the built-in `output` subcommand, not the workflow. *(Spec 4.1, 4.3)*
- **T-CLI-81**: `loopx env list` with `.loopx/env/index.ts` present still runs the built-in `env` subcommand, not the workflow. *(Spec 4.1, 4.3)*

#### Target Validation

- **T-CLI-112**: `loopx run ""` (empty string target) → error, exit code 1. Fixture contains a valid `.loopx/ralph/index.sh`. Assert stderr mentions the empty/invalid target format, not a missing-workflow error — the rejection must be about the target shape, not about `.loopx/` state. *(Spec 4.1)*
- **T-CLI-113**: `loopx run ":"` (bare colon) → error, exit code 1. Fixture contains a valid `.loopx/ralph/index.sh`. Assert stderr mentions the invalid target format. *(Spec 4.1)*
- **T-CLI-114**: `loopx run ":script"` (leading colon) → error, exit code 1. Fixture contains a valid `.loopx/ralph/index.sh`. Assert stderr mentions the invalid target format. *(Spec 4.1)*
- **T-CLI-115**: `loopx run "workflow:"` (trailing colon) → error, exit code 1. Fixture contains a valid `.loopx/ralph/index.sh`. Assert stderr mentions the invalid target format. *(Spec 4.1)*
- **T-CLI-116**: `loopx run "a:b:c"` (multiple colons) → error, exit code 1. Fixture contains a valid `.loopx/ralph/index.sh`. Assert stderr mentions the invalid target format. *(Spec 4.1)*
- **T-CLI-117**: `loopx run "bad.name:index"` (workflow name violates name restrictions) → error, exit code 1. Fixture contains a valid `.loopx/ralph/index.sh`. Assert stderr mentions the name restriction violation, not a missing-workflow error. *(Spec 4.1)*
- **T-CLI-118**: `loopx run "ralph:bad.name"` (script name violates name restrictions) → error, exit code 1. Fixture contains a valid `.loopx/ralph/index.sh`. Assert stderr mentions the name restriction violation, not a missing-script error. *(Spec 4.1)*
- **T-CLI-118a**: `loopx run "bad.name"` (bare target where the workflow name violates name restrictions) → error, exit code 1. Fixture contains a valid `.loopx/ralph/index.sh`. Assert stderr mentions the name restriction violation. This is the bare-name counterpart to T-CLI-117 (qualified target with invalid workflow name) — ADR-0003 made bare names central to the invocation model, so bare invalid-workflow rejection must be tested independently of the qualified form. *(Spec 4.1)*
- **T-CLI-114a**: Invalid target format is rejected after discovery and global validation, not as an early usage error. Create `.loopx/broken/check.sh` and `.loopx/broken/check.ts` (name collision) alongside `.loopx/valid/index.sh`. Run `loopx run ":script"` (an invalid target string). Assert exit code 1 AND that stderr mentions the name collision in `broken` — proving discovery and global validation ran before the invalid target was rejected. Per Spec 4.1, invalid targets are rejected "at the same point as a missing workflow (after discovery)." *(Spec 4.1, 5.4)*
- **T-CLI-118b**: Invalid target with a name-restriction violation is rejected after discovery and global validation, not as an early usage error. Create `.loopx/broken/check.sh` and `.loopx/broken/check.ts` (name collision) alongside `.loopx/valid/index.sh`. Run `loopx run "bad.name"` (bare target whose workflow-name portion contains `.`, violating the name restriction pattern `[a-zA-Z0-9_][a-zA-Z0-9_-]*`). Assert exit code 1 AND that stderr mentions the name collision in `broken` — proving discovery and global validation ran before the invalid target was rejected. T-CLI-114a covers the ordering proof for malformed colon-shape targets (`":script"`); this test covers the same ordering proof for the name-restriction invalid-target category, a distinct validation path under ADR-0003's expanded target validation rules. Per Spec 4.1, invalid targets are rejected "at the same point as a missing workflow (after discovery)." *(Spec 4.1, 5.4)*

#### Option Order

- **T-CLI-57**: `loopx run ralph -n 1` (target name before `-n`) runs the script for exactly 1 iteration. Assert via counter file that the script ran exactly once. *(Spec 4.2)*
- **T-CLI-58**: `loopx run ralph -e local.env -n 1` (target name before both `-e` and `-n`) runs the script with the env file loaded. Assert via marker file that the env variable from `local.env` is visible to the script. *(Spec 4.2)*
- **T-CLI-83**: `loopx run -e local.env ralph -n 1` (options on both sides of the target name) runs the script for exactly 1 iteration with the env file loaded. *(Spec 4.2)*

#### CLI `-n` Option

- **T-CLI-14**: `loopx run -n 3 ralph` with a counter fixture runs exactly 3 iterations. Assert counter file contains 3 marks. *(Spec 4.2, 7.1)*
- **T-CLI-15**: `loopx run -n 0 ralph` exits 0 without running the script. Assert counter file does not exist or is empty. *(Spec 4.2, 7.1)*
- **T-CLI-16**: `loopx run -n -1 ralph` exits with code 1 (usage error). *(Spec 4.2)*
- **T-CLI-17**: `loopx run -n 1.5 ralph` exits with code 1 (usage error). *(Spec 4.2)*
- **T-CLI-18**: `loopx run -n abc ralph` exits with code 1 (usage error). *(Spec 4.2)*
- **T-CLI-19**: `loopx run -n 0 nonexistent` with `.loopx/` existing but no workflow named `nonexistent` — exits with code 1 (validation occurs before `-n 0` short-circuit). *(Spec 4.2, 7.1)*
- **T-CLI-19a**: `loopx run -n 0 ralph` with `.loopx/` directory missing entirely → exits with code 1. *(Spec 4.2, 7.1, 7.2)*
- **T-CLI-20**: `loopx run -n 1 ralph` runs exactly 1 iteration even if the script produces no `stop`. *(Spec 4.2)*
- **T-CLI-56**: `loopx run -n 0 ralph` with a valid workflow performs discovery and validation (target must exist), then executes zero iterations, and exits 0. *(Spec 4.2, 7.1)*
- **T-CLI-119**: `loopx run -n 0 ralph` skips workflow-level version checking. Set up `.loopx/ralph/package.json` declaring a loopx version range not satisfied by the running version. Assert exit code 0 and no version mismatch warning on stderr. *(Spec 3.2, 4.2)*
- **T-CLI-119c**: `loopx run -n 0 ralph` skips the entire version-check path, including `package.json` reading. Set up `.loopx/ralph/package.json` with invalid JSON content (e.g., `{broken`). Assert exit code 0 and no `package.json` warning on stderr. This extends T-CLI-119 (which tests unsatisfied range) to prove the whole runtime version-check path is skipped under `-n 0` — not just the range comparison. SPEC 3.2 says "no workflow is entered for execution," so `package.json` is never read. *(Spec 3.2, 4.2)*
- **T-CLI-119e**: `loopx run -n 0 ralph` with `.loopx/ralph/package.json` unreadable (e.g., mode 000). Assert exit code 0 and no `package.json` warning on stderr. This extends T-CLI-119 (unsatisfied range) and T-CLI-119c (invalid JSON) to the unreadable-file failure path — the third distinct failure branch in SPEC 3.2. Together, T-CLI-119/119c/119e prove that `-n 0` skips the version-check path across three `package.json` failure modes. **Conditional on `process.getuid() !== 0`.** *(Spec 3.2, 4.2)*
- **T-CLI-119f**: `loopx run -n 0 ralph` with `.loopx/ralph/package.json` containing a valid JSON object with an invalid semver range for `loopx` (e.g., `"loopx": "not-a-range"` in `dependencies`). Assert exit code 0 and no `package.json` or version-related warning on stderr. This extends T-CLI-119 (unsatisfied range), T-CLI-119c (invalid JSON), and T-CLI-119e (unreadable file) to the invalid-semver-range failure path — the fourth distinct failure branch in SPEC 3.2. Together, T-CLI-119/119c/119e/119f prove that `-n 0` skips the entire version-check path, including all `package.json` failure modes. Mirrors API behavior (T-API-08g). *(Spec 3.2, 4.2)*
- **T-CLI-119a**: `loopx run -n 0 ralph` where `.loopx/ralph/` exists but has no `index` script (e.g., only `check.sh`) → exits with code 1. Target resolution requires the default entry point to exist even under `-n 0`. *(Spec 4.1, 4.2, 7.1)*
- **T-CLI-119b**: `loopx run -n 0 ralph:missing` where `.loopx/ralph/` exists (with `index.sh`) but has no script named `missing` → exits with code 1. Target resolution validates the specified script exists even under `-n 0`. *(Spec 4.1, 4.2, 7.1)*
- **T-CLI-119d**: `loopx run -n 0 ":script"` → exits with code 1. Malformed target strings are validated before the `-n 0` short-circuit. This extends the `-n 0` validation coverage (T-CLI-19/119a/119b test missing workflow/script/index) to cover target-syntax validation — the spec (4.1) says invalid targets are rejected at the same point as a missing workflow. *(Spec 4.1, 4.2, 7.1)*
- **T-CLI-119g**: `loopx run -n 0 ralph:check` where `.loopx/ralph/check.sh` exists and `.loopx/ralph/index.*` does not → exits with code 0, runs zero iterations. A workflow without an `index` script is still valid when targeting an explicit script — `-n 0` validates that the explicit target exists and passes validation, then exits cleanly. This is the positive counterpart to T-CLI-119a (bare target without index → error). *(Spec 4.1, 4.2, 7.1)*
- **T-CLI-119h**: `loopx run -n 0 ralph:check` where `.loopx/ralph/check.sh` exists, `.loopx/ralph/index.*` does not, and `.loopx/ralph/package.json` declares an unsatisfied loopx range (e.g., `{ "dependencies": { "loopx": ">=999.0.0" } }`) → exit code 0 and no version mismatch or `package.json` warnings on stderr. Combines T-CLI-119g (explicit `workflow:script` target under `-n 0` in a no-index workflow) with T-CLI-119 (`-n 0` skips workflow version checking) — proves that the version-check skip applies to explicit `workflow:script` targets, not just bare workflow targets. Without this combined case, a buggy implementation that scoped the `-n 0` version-check skip only to bare workflow targets could still pass T-CLI-119/119c/119e/119f and T-CLI-119g. *(Spec 3.2, 4.1, 4.2, 7.1)*
- **T-CLI-119i**: `loopx run -n 0 ralph:check` where `.loopx/ralph/check.sh` exists, `.loopx/ralph/index.*` does not, and `.loopx/ralph/package.json` contains invalid JSON (e.g., `{broken`) → exit code 0 and no `package.json` warning on stderr. Extends T-CLI-119h (explicit `workflow:script` target under `-n 0` in a no-index workflow with an unsatisfied range) to the invalid-JSON `package.json` failure path — proving the `-n 0` version-check skip on the explicit-target path covers all `package.json` failure branches, not just unsatisfied ranges. Without this combined case, a buggy implementation that read `package.json` on the explicit-target path (but skipped the range comparison) could still pass T-CLI-119h while emitting a JSON parse warning here. *(Spec 3.2, 4.1, 4.2, 7.1)*
- **T-CLI-119j**: `loopx run -n 0 ralph:check` where `.loopx/ralph/check.sh` exists, `.loopx/ralph/index.*` does not, and `.loopx/ralph/package.json` contains a valid JSON object with an invalid semver range for `loopx` (e.g., `"loopx": "not-a-range"` in `dependencies`) → exit code 0 and no `package.json` or version-related warning on stderr. Invalid-semver counterpart to T-CLI-119i (invalid JSON), extending the explicit-target `-n 0` coverage to a third `package.json` failure branch. *(Spec 3.2, 4.1, 4.2, 7.1)*
- **T-CLI-119k**: `loopx run -n 0 ralph:check` where `.loopx/ralph/check.sh` exists, `.loopx/ralph/index.*` does not, and `.loopx/ralph/package.json` is unreadable (e.g., mode 000) → exit code 0 and no `package.json` warning on stderr. Unreadable-file counterpart to T-CLI-119i (invalid JSON) and T-CLI-119j (invalid semver), completing explicit-target `-n 0` coverage of all `package.json` failure branches in SPEC 3.2. **Conditional on `process.getuid() !== 0`.** *(Spec 3.2, 4.1, 4.2, 7.1)*

#### Duplicate Flags

- **T-CLI-20a**: `loopx run -n 3 -n 5 ralph` exits with code 1 (duplicate `-n` is a usage error). *(Spec 4.2)*
- **T-CLI-20b**: `loopx run -e .env1 -e .env2 ralph` exits with code 1 (duplicate `-e` is a usage error). *(Spec 4.2)*

#### Unrecognized Run Flags

- **T-CLI-35**: `loopx run --unknown ralph` exits with code 1 (unrecognized flag within `run` is a usage error). *(Spec 4.2)*
- **T-CLI-72**: `loopx run -x ralph` exits with code 1 (unrecognized short flag within `run`). *(Spec 4.2)*
- **T-CLI-86**: `loopx run ralph --unknown` exits with code 1. Create `.loopx/ralph/index.sh` that writes a known value to a marker file. Assert exit code 1 AND assert the marker file does not exist. *(Spec 4.2)*
- **T-CLI-87**: `loopx run ralph -x` exits with code 1. *(Spec 4.2)*
- **T-CLI-88**: `loopx run ralph -n 1 -n 2` exits with code 1 (duplicate `-n` after target name). *(Spec 4.2)*
- **T-CLI-89**: `loopx run ralph -e a.env -e b.env` exits with code 1 (duplicate `-e` after target name). *(Spec 4.2)*

#### Missing Flag Operands

- **T-CLI-97**: `loopx run -n` (no operand for `-n`, no target) exits with code 1 (usage error). *(Spec 4.2)*
- **T-CLI-98**: `loopx run -e` (no operand for `-e`, no target) exits with code 1 (usage error). *(Spec 4.2)*
- **T-CLI-99**: `loopx run ralph -n` (missing `-n` operand after target name) exits with code 1 (usage error). *(Spec 4.2)*
- **T-CLI-100**: `loopx run ralph -e` (missing `-e` operand after target name) exits with code 1 (usage error). *(Spec 4.2)*

#### CLI `-e` Option

- **T-CLI-21**: `loopx run -e .env -n 1 ralph` with a valid `.env` file makes its variables available in the script. Use `write-env-to-file` fixture in the workflow's `index.sh`. Assert the marker file contains the expected value. *(Spec 4.2)*
- **T-CLI-22**: `loopx run -e nonexistent.env ralph` exits with code 1. Stderr mentions the missing file. *(Spec 4.2)*
- **T-CLI-22a**: `loopx run -n 0 -e nonexistent.env ralph` exits with code 1 (env file validation happens before `-n 0` short-circuit). *(Spec 4.2, 7.1)*
- **T-CLI-22c**: `loopx run -n 0 -e malformed.env ralph` where `malformed.env` exists and is readable but contains an invalid line (e.g., `1BAD=val`) → exits with code 0, stderr contains a parser warning for the invalid key, and the script never runs (assert counter file does not exist). Proves env files are actually parsed under `-n 0`, not just existence/readability checked. *(Spec 4.2, 7.1, 8.1)*
- **T-CLI-22b**: `loopx run -n 0 ralph` with `.loopx/` containing a name collision in a workflow → exits with code 1 (validation occurs before `-n 0` short-circuit). *(Spec 4.2, 5.2, 7.1)*
- **T-CLI-22d**: `loopx run -n 0 ralph` with `.loopx/` containing an invalid script name (e.g., `-bad.sh` in any workflow) → exits with code 1. *(Spec 4.2, 5.3, 7.1)*
- **T-CLI-22e**: `loopx run -n 0 ralph` with `.loopx/` containing a sibling with an invalid workflow name (e.g., `.loopx/-bad-workflow/index.sh`) → exits with code 1 (global validation catches the invalid workflow name before the `-n 0` short-circuit). This is the `-n 0` counterpart to T-DISC-47b (invalid workflow name in sibling, normal run mode). *(Spec 4.2, 5.3, 7.1)*
- **T-CLI-22f**: `loopx run -n 0 -e unreadable.env ralph` where `unreadable.env` exists but is unreadable (e.g., mode 000) → exits with code 1. Env file readability validation fires before the `-n 0` short-circuit. This completes the local `-e` file failure coverage under `-n 0`: T-CLI-22a covers missing, T-CLI-22c covers malformed, and this test covers unreadable. **Conditional on `process.getuid() !== 0`.** *(Spec 4.2, 7.1, 8.2)*

#### CLI Stdout Silence

- **T-CLI-23**: `loopx run -n 1 ralph` where `ralph:index` outputs `{"result":"hello"}` and writes a marker file — the CLI's own stdout is empty (result is not printed), AND the marker file exists (proving the script actually ran). *(Spec 7.1)*
- **T-CLI-27**: `loopx run ralph beta` (two positional arguments within `run`) exits with code 1. `run` accepts exactly one positional argument. *(Spec 4.1)*
- **T-CLI-96**: `loopx run ralph -n 1 beta` exits with code 1 (extra positional argument interleaved with options). *(Spec 4.1)*

### 4.2 Subcommands

**Spec refs:** 4.3, 5.4

#### `loopx output`

- **T-SUB-01**: `loopx output --result "hello"` prints valid JSON to stdout, exits 0. Parse stdout as JSON and assert `result === "hello"`. Do not assert exact byte-for-byte text or field order. *(Spec 4.3)*
- **T-SUB-02**: `loopx output --goto "next"` prints valid JSON to stdout, exits 0. Parse stdout as JSON and assert `goto === "next"`. *(Spec 4.3)*
- **T-SUB-02a**: `loopx output --goto "review-adr:request-feedback"` prints valid JSON with a qualified goto target. Parse stdout as JSON and assert `goto === "review-adr:request-feedback"`. The output helper does not validate the goto target format — it only serializes. *(Spec 4.3)*
- **T-SUB-02b**: `loopx output --goto "check-ready"` prints valid JSON with a bare goto target (intra-workflow). *(Spec 4.3)*
- **T-SUB-02c**: `loopx output --goto ""` prints valid JSON with `goto === ""`. The output helper does not validate — empty string is serialized as-is. *(Spec 4.3)*
- **T-SUB-02d**: `loopx output --goto "a:b:c"` prints valid JSON with `goto === "a:b:c"`. The output helper does not validate malformed targets; it only serializes them. *(Spec 4.3)*
- **T-SUB-02e**: `loopx output --goto ":script"` prints valid JSON with `goto === ":script"`. The output helper does not validate leading-colon targets; it only serializes. *(Spec 4.3)*
- **T-SUB-02f**: `loopx output --goto "workflow:"` prints valid JSON with `goto === "workflow:"`. The output helper does not validate trailing-colon targets; it only serializes. *(Spec 4.3)*
- **T-SUB-02g**: `loopx output --goto ":"` prints valid JSON with `goto === ":"`. The output helper does not validate bare-colon targets; it only serializes. This completes the invalid-shape matrix from Spec 4.1 (empty string, bare colon, leading colon, trailing colon, multiple colons) for the CLI helper. *(Spec 4.3)*
- **T-SUB-02h**: `loopx output --goto "missing-workflow:missing-script"` prints valid JSON with `goto === "missing-workflow:missing-script"` and exits 0, even without a `.loopx/` directory existing. The output helper does not validate target existence — a well-formed but nonexistent target is serialized identically to a real one. The existing non-validation tests (T-SUB-02c–02g) cover syntactically invalid targets; this test covers a syntactically valid but nonexistent target, proving the helper performs no existence check at all. *(Spec 4.3, 5.4)*
- **T-SUB-02i**: `loopx output --goto "bad.name"` prints valid JSON with `goto === "bad.name"` and exits 0. The output helper does not validate name-pattern violations in bare targets. The dot is not allowed by the name restriction pattern `[a-zA-Z0-9_][a-zA-Z0-9_-]*`, but the helper only serializes — target validation is deferred to loop execution time. T-SUB-02c–02g cover invalid delimiter shapes (empty, bare colon, leading colon, trailing colon, multiple colons) and T-SUB-02h covers a syntactically valid but nonexistent target; this test covers a third category — a bare target that is not colon-malformed and not merely nonexistent, but violates the name-restriction regex itself. A helper that incorrectly regex-validates names would pass T-SUB-02c–02h and fail here. *(Spec 4.3)*
- **T-SUB-02j**: `loopx output --goto "bad.name:index"` prints valid JSON with `goto === "bad.name:index"` and exits 0. The workflow portion of the qualified target violates the name restriction pattern (the dot is not allowed), but the output helper does not validate either portion of the target — it only serializes. This is the qualified-target counterpart to T-SUB-02i (bare invalid name), proving that name-pattern validation is deferred for the workflow portion specifically. *(Spec 4.3)*
- **T-SUB-02k**: `loopx output --goto "ralph:bad.name"` prints valid JSON with `goto === "ralph:bad.name"` and exits 0. The script portion of the qualified target violates the name restriction pattern (the dot is not allowed), but the output helper does not validate either portion of the target. Combined with T-SUB-02j, this proves that name-pattern validation is deferred for both the workflow and script portions of qualified targets. *(Spec 4.3)*
- **T-SUB-03**: `loopx output --stop` prints valid JSON to stdout, exits 0. Parse stdout as JSON and assert `stop === true`. *(Spec 4.3)*
- **T-SUB-04**: `loopx output --result "x" --goto "y" --stop` prints valid JSON to stdout. Parse as JSON and assert all three fields present with correct values. *(Spec 4.3)*
- **T-SUB-05**: `loopx output` with no flags exits with code 1 (error). *(Spec 4.3)*
- **T-SUB-06**: `loopx output --result "x"` works without `.loopx/` directory existing. *(Spec 5.4)*
- **T-SUB-06a**: `loopx output --result 'value with "quotes" and \\backslashes'` → stdout is valid JSON with the value correctly escaped. *(Spec 4.3)*
- **T-SUB-06b**: `loopx output --result $'line1\nline2'` → stdout is valid JSON with the newline correctly escaped. *(Spec 4.3)*

#### `loopx env set`

- **T-SUB-07**: `loopx env set FOO bar` then `loopx env list` shows `FOO=bar`. *(Spec 4.3)*
- **T-SUB-08**: `loopx env set _UNDER score` succeeds (underscore-prefixed name valid). Follow with `loopx env list` and assert `_UNDER=score` is present. *(Spec 4.3)*
- **T-SUB-09**: `loopx env set A1 val` succeeds (alphanumeric name). *(Spec 4.3)*
- **T-SUB-10**: `loopx env set 1INVALID val` exits with code 1 (starts with digit). *(Spec 4.3)*
- **T-SUB-11**: `loopx env set -DASH val` exits with code 1 (invalid name). *(Spec 4.3)*
- **T-SUB-12**: `loopx env set FOO bar` then `loopx env set FOO baz` then `loopx env list` shows `FOO=baz` (overwrite). *(Spec 4.3)*
- **T-SUB-13**: `loopx env set FOO bar` in a directory with no `.loopx/` → exits 0 AND `loopx env list` subsequently shows `FOO=bar`. *(Spec 5.4)*
- **T-SUB-14**: `loopx env set` creates the config directory (`$XDG_CONFIG_HOME/loopx/`) if it doesn't exist. *(Spec 8.1)*
- **T-SUB-14a**: `loopx env set KEY "value with spaces"` → `loopx env list` shows `KEY=value with spaces`. *(Spec 4.3)*
- **T-SUB-14b**: `loopx env set KEY "value#hash"` → value preserved including `#`. *(Spec 4.3)*
- **T-SUB-14c**: `loopx env set KEY "val=ue"` → value with `=` round-trips correctly. *(Spec 4.3)*
- **T-SUB-14d**: `loopx env set KEY <value containing an actual newline byte>` → rejected. Exit code 1. *(Spec 4.3)*
- **T-SUB-14e**: `loopx env set KEY 'val"ue'` → `loopx env list` shows `KEY=val"ue`. *(Spec 4.3)*
- **T-SUB-14f**: `loopx env set KEY "value  "` → `loopx env list` shows `KEY=value  `. Trailing spaces preserved. *(Spec 4.3)*
- **T-SUB-14g**: `loopx env set KEY <value containing an actual CR byte>` → rejected. Exit code 1. *(Spec 4.3)*

#### `loopx env set` On-Disk Serialization

- **T-SUB-14h**: `loopx env set FOO bar` → read the global env file. Assert it contains the line `FOO="bar"\n`. *(Spec 4.3)*
- **T-SUB-14i**: `loopx env set FOO "value with spaces"` → file contains `FOO="value with spaces"\n`. *(Spec 4.3)*
- **T-SUB-14j**: `loopx env set FOO 'val"ue'` → file contains `FOO="val"ue"\n` (no escaping). *(Spec 4.3)*
- **T-SUB-14k**: `loopx env set FOO ""` (empty value) → file contains `FOO=""\n`. *(Spec 4.3)*

#### `loopx env remove`

- **T-SUB-15**: `loopx env set FOO bar` then `loopx env remove FOO` then `loopx env list` — `FOO` is absent. *(Spec 4.3)*
- **T-SUB-16**: `loopx env remove NONEXISTENT` exits with code 0 (silent no-op). *(Spec 4.3)*

#### `loopx env list`

- **T-SUB-17**: With no variables set, `loopx env list` produces no stdout output, exits 0. *(Spec 4.3)*
- **T-SUB-18**: With variables `ZEBRA=z`, `ALPHA=a`, `MIDDLE=m` set, `loopx env list` outputs them sorted: `ALPHA=a`, `MIDDLE=m`, `ZEBRA=z`. *(Spec 4.3)*
- **T-SUB-19**: `loopx env list` in a directory with no `.loopx/` → exits 0 and produces no stdout. *(Spec 5.4)*

### 4.3 Workflow & Script Discovery

**Spec refs:** 2.1, 5.1–5.4

#### Workflow Discovery

- **T-DISC-01**: `.loopx/ralph/` containing `index.sh` is a valid workflow. `loopx run -n 1 ralph` runs the `index.sh` script. Assert via marker file. *(Spec 2.1, 5.1)*
- **T-DISC-02**: `.loopx/ralph/` containing `index.ts` is a valid workflow. `loopx run -n 1 ralph` runs it. Assert via marker file. *(Spec 2.1, 5.1)*
- **T-DISC-03**: `.loopx/ralph/` containing `index.js` is a valid workflow. Assert via marker file. *(Spec 2.1, 5.1)*
- **T-DISC-04**: `.loopx/ralph/` containing `index.jsx` is a valid workflow. Assert via marker file. *(Spec 2.1, 5.1)*
- **T-DISC-05**: `.loopx/ralph/` containing `index.tsx` is a valid workflow. Assert via marker file. *(Spec 2.1, 5.1)*
- **T-DISC-06**: `.loopx/ralph/` containing only `index.mjs` → not recognized as a workflow (`.mjs` is unsupported). `loopx run -n 1 ralph` fails with "not found." *(Spec 2.1, 5.1)*
- **T-DISC-07**: `.loopx/ralph/` containing only `index.cjs` → not recognized as a workflow. *(Spec 2.1, 5.1)*
- **T-DISC-08**: `.loopx/ralph/` containing only `readme.txt` and `config.json` → not a workflow (no supported script extensions). `loopx run -n 1 ralph` fails. No warning. *(Spec 2.1, 5.1)*
- **T-DISC-09**: Empty subdirectory `.loopx/ralph/` → not a workflow (no script files). `loopx run -n 1 ralph` fails. No warning. *(Spec 5.1)*
- **T-DISC-10**: Files placed directly in `.loopx/` are never discovered. `.loopx/loose-script.sh` exists alongside `.loopx/ralph/index.sh`. `loopx run -n 1 loose-script` fails (not found). `loopx run -n 1 ralph` succeeds. *(Spec 5.1)*
- **T-DISC-11**: `.loopx/loose-script.ts` directly in `.loopx/` is not discovered even if it has a supported extension. Assert `loopx run -n 1 loose-script` fails. *(Spec 5.1)*
- **T-DISC-10a**: Flat-script explicit no-migration-warning test. `.loopx/loose-script.sh` exists alongside a valid workflow (`.loopx/ralph/index.sh`). `loopx run loose-script` fails with exit code 1 (not found). Additionally assert — **structurally** rather than by prose blacklisting — that stderr does not contain a migration-guidance or deprecation warning as a separate output category alongside the not-found error. Concretely: the stderr output is limited to the standard target-resolution error (and any unrelated warnings that would be emitted regardless of the flat-script sibling). There is no additional warning/notice/advisory line whose subject is the loose flat-script layout (the `.loopx/loose-script.sh` file itself is not mentioned in any extra category of output beyond, at most, the routine "target not found" message). Prose-level phrase matching is intentionally avoided — the check targets the presence of a distinct migration-warning output category, not specific wording. This is the flat-script counterpart to T-DISC-20c (legacy directory-script no-migration-warning), explicitly locking down the ADR-0003 consequence that no migration warnings are provided for any legacy layout. *(Spec 5.1)*
- **T-DISC-10b**: An invalid loose file directly under `.loopx/` is ignored, not just valid ones. `.loopx/-bad-name.sh` exists (a name that would fail name restriction validation if it were inside a workflow) alongside a valid workflow (`.loopx/ralph/index.sh`). `loopx run -n 1 ralph` succeeds with no errors or warnings about the invalid file. This proves flat-root files are completely outside discovery and validation — they are not scanned, named, or validated at all. *(Spec 5.1)*
- **T-DISC-10c**: A non-workflow subdirectory with an invalid name is ignored entirely — it is never validated. `.loopx/-bad-dir/` exists containing only `README.md` (no script files) alongside a valid workflow (`.loopx/ralph/index.sh`). `loopx run -n 1 ralph` succeeds with no errors or warnings about `-bad-dir`. Because `-bad-dir` has no top-level script files, it is not a workflow and its name is never checked against the naming restriction pattern. This is distinct from T-DISC-47b, where the invalid-named directory IS a workflow (contains scripts) and IS fatal. *(Spec 5.1)*
- **T-DISC-10d**: Same fixture as T-DISC-10c under `loopx run -h`. The non-workflow directory `-bad-dir` is neither listed in the discovered-workflows output nor warned about on stderr. Only `ralph` appears. This is the `-h` counterpart to T-DISC-10c, and the invalid-name counterpart to T-CLI-104a/104b (which use valid names for non-workflow subdirectories). *(Spec 5.1, 11.2)*
- **T-DISC-10e**: An invalid-named loose file at `.loopx/` root is ignored under `loopx run -h`. `.loopx/-bad-root-file.sh` exists alongside a valid workflow (`.loopx/ralph/index.sh`). `loopx run -h` lists `ralph` with no warnings about `-bad-root-file.sh` on stderr. This is the `-h` counterpart to T-DISC-10b (which covers run mode). *(Spec 5.1, 11.2)*
- **T-DISC-10f**: Same-name loose root file and workflow coexist. `.loopx/foo.sh` and `.loopx/foo/index.sh` both exist. `loopx run -n 1 foo` runs `foo:index` successfully (asserted via marker file). No collision or error is raised — `foo.sh` is a loose root file, ignored by discovery. This is the same-name variant of T-DISC-10 (which uses different names for the loose file and workflow). A leftover flat-script namespace implementation could pass T-DISC-10/T-DISC-11 and fail only here, where the loose file shares the workflow's basename. *(Spec 5.1)*
- **T-DISC-10g**: Same fixture as T-DISC-10f under `loopx run -h`. Assert: (a) `foo` appears as a discovered workflow, (b) `foo.sh` is neither listed nor warned about on stderr, and (c) no collision warning is raised. This is the help-mode counterpart to T-DISC-10f and the same-name variant of T-CLI-104 (which uses a different name for the loose file). *(Spec 5.1, 11.2)*

#### Script Discovery Within Workflows

- **T-DISC-12**: All top-level files with supported extensions inside a workflow are discovered as scripts. `.loopx/ralph/` contains `index.sh`, `check-ready.sh`, `setup.ts`. `loopx run -n 1 ralph:check-ready` runs `check-ready.sh`. `loopx run -n 1 ralph:setup` runs `setup.ts`. Assert via marker files. *(Spec 2.1, 5.1)*
- **T-DISC-13**: Script name is the base name without extension. `.loopx/ralph/my-check.ts` → script name is `my-check`. `loopx run -n 1 ralph:my-check` runs it. *(Spec 2.1)*
- **T-DISC-14**: Files in subdirectories within a workflow are NOT discovered. `.loopx/ralph/lib/helpers.ts` exists. `loopx run -n 1 ralph:helpers` fails. The `lib/` subdirectory is ignored during script discovery. *(Spec 2.1, 5.1)*
- **T-DISC-14b**: Files in workflow subdirectories are usable internally by workflow scripts, even though they are invisible to loopx discovery. Create `.loopx/ralph/index.ts` that imports `./lib/helpers.ts` (e.g., `import { greet } from "./lib/helpers.ts"`) and uses the imported value in its output. Create `.loopx/ralph/lib/helpers.ts` exporting a function (e.g., `export function greet() { return "hello from helpers"; }`). `loopx run -n 1 ralph` succeeds and the output contains the value from `helpers.ts`. Additionally assert that `loopx run -n 1 ralph:helpers` fails (the subdirectory file is not a discovered script). This tests both halves of the Spec 2.1 statement that subdirectory files are "invisible to loopx and available for internal use by the workflow's scripts" — T-DISC-14 and T-DISC-14a cover "invisible," but not the positive "available for internal use" half. *(Spec 2.1, 5.1)*
- **T-DISC-14a**: Nested invalid files inside a workflow do not trigger fatal validation. `.loopx/ralph/index.sh` plus `.loopx/ralph/lib/-bad.ts` (invalid script name) and `.loopx/ralph/lib/check.sh` + `.loopx/ralph/lib/check.ts` (same-base-name collision). `loopx run -n 1 ralph` succeeds (exit code 0). The nested files in `lib/` are not discovered and therefore not validated — invalid names and collisions in subdirectories do not trigger fatal validation errors. This is the runtime counterpart to T-INST-64a (which covers the same scenario at install time). *(Spec 2.1, 5.1)*
- **T-DISC-15**: Non-script files inside a workflow are allowed and ignored. `.loopx/ralph/` contains `index.ts`, `schema.json`, `README.md`. The non-script files do not cause warnings. `loopx run -n 1 ralph` works. *(Spec 2.1)*
- **T-DISC-15a**: Config-style file with a supported extension is discovered as a script (no exclusion mechanism). `.loopx/ralph/` contains `index.ts` and `eslint.config.js`. Discovery treats `eslint.config.js` as a script with base name `eslint.config`. The dot in `eslint.config` violates the name restriction pattern `[a-zA-Z0-9_][a-zA-Z0-9_-]*`. `loopx run ralph` fails (exit code 1) due to global validation catching the invalid script name. *(Spec 2.1, 5.3)*
- **T-DISC-15b**: Same setup as T-DISC-15a but via `loopx run -h`. The invalid script name `eslint.config` is reported as a non-fatal warning on stderr. Assert that the warning text contains the offending script name. Help still exits 0. This locks down the ADR-0003 rule that there is no exclusion mechanism — every top-level file with a supported extension is a discovered script, even config-style files. *(Spec 2.1, 5.3, 11.2)*
- **T-DISC-16**: Workflow directory with no top-level supported script files — only supported-extension files in subdirectories (e.g., `.loopx/ralph/lib/helpers.ts` exists but no `.loopx/ralph/*.{sh,js,jsx,ts,tsx}`) — is not recognized as a valid workflow. *(Spec 2.1, 5.1)*

#### Default Entry Point

- **T-DISC-17**: `loopx run ralph` runs `ralph:index`. Create `.loopx/ralph/index.sh` and `.loopx/ralph/check.sh`. Assert `loopx run -n 1 ralph` runs `index.sh` (via marker file), not `check.sh`. *(Spec 2.1)*
- **T-DISC-18**: `loopx run ralph:index` is equivalent to `loopx run ralph`. Assert both produce the same marker file content. *(Spec 2.1, 4.1)*
- **T-DISC-19**: Workflow with no `index` script: `loopx run ralph` → error (exit code 1). `loopx run ralph:check` with `check.sh` present → succeeds. *(Spec 2.1, 4.1)*
- **T-DISC-20**: `index` is not otherwise special. It can be the target of `goto`, follows collision rules, can `goto` other scripts. Create a chain: `ralph:index` → goto `check` → `ralph:check` produces stop. Assert both scripts execute. *(Spec 2.1)*
- **T-DISC-20a**: `package.json` `main` field is ignored for entry point resolution. Create `.loopx/ralph/` with `package.json` containing `{ "main": "check.ts" }`, `index.ts`, and `check.ts`. `loopx run -n 1 ralph` runs `index.ts`, not `check.ts`. Assert via marker files that `index.ts` executed and `check.ts` did not. *(Spec 2.1)*
- **T-DISC-20b**: `package.json` `main` field does not provide a fallback entry point. Create `.loopx/ralph/` with `package.json` containing `{ "main": "check.ts" }` and `check.ts` but NO `index` script. `loopx run ralph` → error (exit code 1, missing default entry point). The `main` field is ignored. *(Spec 2.1)*
- **T-DISC-20c**: A legacy-style directory-script layout is not discovered as a workflow, and loopx does not emit migration warnings. Create `.loopx/mypipeline/` with `package.json` containing `{ "main": "src/run.js" }` and no top-level files with supported script extensions (place `run.js` inside a `src/` subdirectory so no top-level supported-extension files exist). The subdirectory is not a workflow (no top-level supported-extension files). `loopx run mypipeline` fails with exit code 1. Additionally assert — **structurally** rather than by prose blacklisting — that stderr does not contain a migration-guidance or deprecation warning as a separate output category alongside the not-found error. Concretely: the stderr output is limited to the standard target-resolution error (and any unrelated warnings that would be emitted regardless of the directory-script sibling). There is no additional warning/notice/advisory line whose subject is the legacy directory-script layout at `.loopx/mypipeline/` (the `main` field, the nested `src/run.js` file, and the presence of `package.json` without top-level script files are not flagged in any extra output category beyond, at most, the routine "target not found" message). Prose-level phrase matching is intentionally avoided — the check targets the presence of a distinct migration-warning output category, not specific wording. The spec states legacy layouts are simply not recognized — no migration tooling or warnings are provided. *(Spec 2.1, 5.1)*

#### Name Collisions Within Workflows

- **T-DISC-21**: `.loopx/ralph/check.sh` and `.loopx/ralph/check.ts` both exist → `loopx run -n 1 ralph:check` refuses to start with error listing the conflicting entries. Exit code 1. *(Spec 5.2)*
- **T-DISC-21a**: `index` follows the same collision rules as any other script. `.loopx/ralph/index.sh` and `.loopx/ralph/index.ts` both exist → `loopx run -n 1 ralph` refuses to start with error listing the conflicting `index` entries. Exit code 1. A bad implementation could special-case `index` and still pass collision tests that only use non-index names (T-DISC-21). *(Spec 2.1, 5.2)*
- **T-DISC-22**: Same-base-name collision in one workflow is fatal for any target in any workflow. `.loopx/ralph/check.sh` and `.loopx/ralph/check.ts` exist, `.loopx/other/index.sh` is valid. `loopx run -n 1 other` still fails because global validation catches ralph's collision. *(Spec 5.2, 5.4)*
- **T-DISC-23**: Same base names in **different** workflows are allowed. `.loopx/ralph/check.sh` and `.loopx/other/check.ts` coexist without collision. Both `loopx run -n 1 ralph:check` and `loopx run -n 1 other:check` succeed. *(Spec 5.2)*
- **T-DISC-24**: Non-conflicting scripts within the same workflow → no error. `.loopx/ralph/alpha.sh` and `.loopx/ralph/beta.ts` coexist. *(Spec 5.2)*

#### Workflow and Script Naming

- **T-DISC-25**: Workflow name restrictions follow `[a-zA-Z0-9_][a-zA-Z0-9_-]*`. `.loopx/my-workflow/index.sh` → valid. *(Spec 5.3)*
- **T-DISC-26**: `.loopx/_underscore/index.sh` → valid workflow name. *(Spec 5.3)*
- **T-DISC-26a**: `.loopx/1flow/index.sh` → valid workflow name (digit first). `loopx run -n 1 1flow` succeeds and runs the script. Assert via marker file. This mirrors T-DISC-30a (digit-start script name) but covers the workflow-name validation path — an implementation could wrongly require workflows to start with a letter or underscore. *(Spec 5.3)*
- **T-DISC-26b**: `.loopx/42/index.sh` → valid workflow name (all digits). `loopx run -n 1 42` succeeds and runs the script. Assert via marker file. This mirrors T-DISC-30b (all-digit script name) but covers the workflow-name validation path. *(Spec 5.3)*
- **T-DISC-27**: `.loopx/-startswithdash/index.sh` → invalid workflow name, error. *(Spec 5.3)*
- **T-DISC-28**: `.loopx/has space/index.sh` → invalid workflow name (space not allowed). *(Spec 5.3)*
- **T-DISC-29**: `.loopx/has.dot/index.sh` → invalid workflow name (dot not allowed). *(Spec 5.3)*
- **T-DISC-30**: Script name `check-ready` (hyphen in middle) → valid. *(Spec 5.3)*
- **T-DISC-30a**: Script name `1start` (digit first) → valid per `[a-zA-Z0-9_]`. *(Spec 5.3)*
- **T-DISC-30b**: Script name `42` (all digits) → valid. *(Spec 5.3)*
- **T-DISC-31**: Script name with `:` → error. The `:` is explicitly disallowed in both workflow and script names. *(Spec 5.3)*
- **T-DISC-32**: Workflow name with `:` → error. *(Spec 5.3)*

#### Previously Reserved Names (Now Allowed)

- **T-DISC-33**: `.loopx/output/index.sh` is discoverable. `loopx run -n 1 output` runs the script (not the built-in `output` subcommand). Assert via marker file. *(Spec 4.1, 5.1)*
- **T-DISC-34**: `.loopx/env/index.ts` is discoverable. `loopx run -n 1 env` runs the script. *(Spec 5.1)*
- **T-DISC-35**: `.loopx/install/index.js` is discoverable. `loopx run -n 1 install` runs the script. *(Spec 5.1)*
- **T-DISC-36**: `.loopx/version/index.sh` is discoverable. `loopx run -n 1 version` runs the script (not the built-in). *(Spec 4.1, 5.1)*
- **T-DISC-37**: `.loopx/run/index.sh` is discoverable. `loopx run -n 1 run` runs the workflow named `run`. *(Spec 4.1, 5.1)*
- **T-DISC-38**: `loopx run -h` with `.loopx/` containing **only** workflows named `version`, `output`, `env`, `install`, and `run` lists all five workflows and stderr is empty. No warnings about these names. *(Spec 5.1, 11.2)*

#### Symlinks

- **T-DISC-39**: Symlink to a workflow directory inside `.loopx/` → discovered under the **symlink's own name**, not the target directory's name. Create a workflow directory outside `.loopx/` (e.g., `/tmp/real-workflow/` with `index.sh`), then symlink `.loopx/my-alias/ → /tmp/real-workflow/`. `loopx run -n 1 my-alias` succeeds. `loopx run -n 1 real-workflow` fails (not discovered under the target's name). *(Spec 5.1)*
- **T-DISC-39a**: `LOOPX_WORKFLOW` reflects the symlink name for a symlinked workflow. Same setup as T-DISC-39. Script writes `$LOOPX_WORKFLOW` to a marker file. Assert marker contains `my-alias`, not the real directory's name. *(Spec 5.1, 8.3)*
- **T-DISC-40**: Symlinked script file inside a workflow → discovered and targetable by the **symlink's base name**, not the original file's name. Create `.loopx/ralph/` with `index.sh` and a symlink `my-check.sh → /tmp/original-check.sh`. `loopx run -n 1 ralph:my-check` succeeds. `loopx run -n 1 ralph:original-check` fails (not discovered under the target's name). *(Spec 5.1)*
- **T-DISC-40a**: Symlink to non-workflow directory is ignored at runtime. Create a directory with no top-level script files (e.g., `/tmp/non-workflow-dir/` containing only `README.md`), then symlink `.loopx/meta → /tmp/non-workflow-dir`. Also set up a valid workflow `.loopx/ralph/index.sh`. Assert: (a) `loopx run -n 1 ralph` succeeds, (b) `loopx run meta` fails (not found as a workflow), and (c) no warning is emitted about `meta` on stderr. Workflow detection rules still apply after following symlinks — a symlink that resolves to a directory without top-level script files is silently ignored, same as a normal non-workflow subdirectory (T-DISC-08). *(Spec 5.1)*
- **T-DISC-40b**: Symlink to non-workflow directory is ignored in help output. Same fixture as T-DISC-40a. `loopx run -h` lists `ralph` but does not list or warn about `meta`. This is the help-mode counterpart to T-DISC-40a, and the symlink counterpart to T-CLI-104a (normal non-workflow subdirectory ignored in help). *(Spec 5.1, 11.2)*
- **T-DISC-40c**: Symlinked workflow directory with invalid alias name is fatal in run, non-fatal warning in help. Create a valid workflow directory outside `.loopx/` (e.g., `/tmp/real-workflow/` with `index.sh`), then symlink `.loopx/-bad-alias → /tmp/real-workflow/`. Also set up a valid workflow `.loopx/ralph/index.sh`. Assert: (a) `loopx run -n 1 ralph` fails with exit code 1 (global validation catches the invalid workflow name from the symlink alias), and (b) `loopx run -h` exits 0 with a non-fatal warning about `-bad-alias` on stderr. Validation uses the symlink's own name (`-bad-alias`), not the target directory's name. This extends T-DISC-39 (symlink naming for discovery) to prove alias names also participate in name-restriction validation. *(Spec 5.1, 5.3, 11.2)*
- **T-DISC-40d**: Symlinked script file with invalid alias basename is fatal in run, non-fatal warning in help. Create `.loopx/ralph/index.sh` and symlink `.loopx/ralph/-bad.sh → /tmp/valid-check.sh` (where the target file exists and is valid). Assert: (a) `loopx run -n 1 ralph` fails with exit code 1 (global validation catches the invalid script name from the symlink's base name), and (b) `loopx run -h` exits 0 with a non-fatal warning about `-bad` on stderr. Validation uses the symlink's own base name (`-bad`), not the target file's name. This extends T-DISC-40 (symlink naming for script discovery) to prove alias names also participate in name-restriction validation. *(Spec 5.1, 5.3, 11.2)*
- **T-DISC-40e**: Symlinked script file participates in same-base-name collision rules. Create `.loopx/ralph/index.sh`, `.loopx/ralph/check.sh`, and a symlink `.loopx/ralph/check.ts → /tmp/helper.ts` (where the target file exists). The regular `check.sh` and symlinked `check.ts` share the base name `check`. Assert: (a) `loopx run -n 1 ralph` fails with exit code 1 (collision detected), and (b) `loopx run -h` exits 0 with a non-fatal collision warning on stderr listing both `check.sh` and `check.ts`. Symlinked scripts are treated identically to regular files for collision detection. *(Spec 5.1, 5.2, 11.2)*
- **T-DISC-40f**: Symlinked non-workflow directory with invalid alias name is silently ignored. Create a directory with no top-level script files (e.g., `/tmp/non-workflow-dir/` containing only `README.md`), then symlink `.loopx/-bad-link → /tmp/non-workflow-dir`. Also set up a valid workflow `.loopx/ralph/index.sh`. `loopx run -n 1 ralph` succeeds with no warning or error about `-bad-link` on stderr. This matters because Spec 5.1/5.3 implies name validation applies only after workflow detection — the symlink target has no top-level script files, so it is not a workflow, and the invalid alias name is never validated. A buggy implementation could validate the symlink alias name before checking whether the target qualifies as a workflow. This is the invalid-name variant of T-DISC-40a (valid-name symlink to non-workflow, also ignored). *(Spec 5.1, 5.3)*
- **T-DISC-40g**: Same fixture as T-DISC-40f under `loopx run -h`. Assert `-bad-link` is neither listed in the discovered-workflows output nor warned about on stderr. Only `ralph` appears. This is the help-mode counterpart to T-DISC-40f, and the invalid-name symlink variant of T-DISC-40b (valid-name symlink to non-workflow ignored in help). *(Spec 5.1, 5.3, 11.2)*
- **T-DISC-40h**: Symlinked workflow directory with a valid alias name whose target's basename is invalid. Create a valid workflow directory at `/tmp/-bad-real-workflow/` (with `index.sh`), then symlink `.loopx/goodalias → /tmp/-bad-real-workflow/`. Also set up a valid workflow `.loopx/ralph/index.sh`. Assert: (a) `loopx run -n 1 goodalias` succeeds and runs the script (marker file written), and (b) `loopx run -h` lists `goodalias` without any warning about `-bad-real-workflow` on stderr. Validation uses only the symlink's own name (`goodalias`), and the target directory's basename (`-bad-real-workflow`) is completely ignored. Existing tests prove alias names are used (T-DISC-39) and invalid alias names fail (T-DISC-40c), but they do not prove that an invalid target basename is ignored — this test closes that gap. *(Spec 5.1, 5.3, 11.2)*
- **T-DISC-40i**: Symlinked script file with a valid alias basename whose target file's basename is invalid. Create `.loopx/ralph/index.sh` and a symlink `.loopx/ralph/goodcheck.sh → /tmp/-bad-real-script.sh` (where the target file exists and is executable). Assert: (a) `loopx run -n 1 ralph:goodcheck` succeeds and runs the symlinked script (marker file written), and (b) `loopx run -h` lists `goodcheck` under `ralph` without any warning about `-bad-real-script` on stderr. This is the script-level counterpart to T-DISC-40h. Existing tests prove alias basenames are used (T-DISC-40) and invalid alias basenames fail (T-DISC-40d), but they do not prove that an invalid target basename is ignored — this test closes that gap. *(Spec 5.1, 5.3, 11.2)*

#### Discovery Caching

- **T-DISC-41**: During a loop (`-n 3`), create a new workflow in `.loopx/` between iteration 1 and 2 (using a script that creates a directory with a script file). Then have iteration 2 `goto` a script in the new workflow → error (not in cached discovery). *(Spec 5.1)*
- **T-DISC-42**: During a loop, modify the content of an already-discovered script between iterations. Assert the new content takes effect on the next iteration (since the file is re-read from disk). *(Spec 5.1)*
- **T-DISC-42a**: During a multi-iteration loop, an already-discovered script is removed (deleted from disk) between iterations. On the next iteration that would execute this script, loopx fails at spawn time. Assert loopx exits with code 1. *(Spec 5.1, 7.2)*
- **T-DISC-42b**: During a multi-iteration loop, an already-discovered script is renamed between iterations (rename variant of T-DISC-42a). Create a workflow with `index.sh` (emits goto to `check`) and `check.sh`. After the first iteration discovers and caches `check.sh`, rename it to `check-new.sh` before the next iteration. The cached path for `check` still points to the original `check.sh`, which no longer exists. Assert loopx fails at spawn time with exit code 1. This covers the "removed or renamed" language in Spec 5.1. *(Spec 5.1, 7.2)*
- **T-DISC-42c**: During a multi-iteration loop, a new script file is added to an already-discovered workflow between iterations. Start with `.loopx/ralph/index.sh` only — the `index.sh` script creates `.loopx/ralph/new-step.sh` on its first execution (detected via a marker file), then on the second iteration emits `goto: "new-step"`. The `goto` targets a script that was not present at loop start → error (not in cached discovery), exit code 1. This is the "new script in existing workflow" counterpart to T-DISC-41 (new workflow added mid-loop). *(Spec 5.1)*

#### Validation Scope

- **T-DISC-43**: `loopx version` works when `.loopx/` doesn't exist. *(Spec 5.4)*
- **T-DISC-44**: `loopx env set X Y` when `.loopx/` doesn't exist → exits 0. *(Spec 5.4)*
- **T-DISC-45**: `loopx output --result "x"` when `.loopx/` doesn't exist → exits 0. *(Spec 5.4)*
- **T-DISC-46**: `loopx version` when `.loopx/` exists and contains name collisions → exits 0 with version string. No validation warnings. *(Spec 5.4)*
- **T-DISC-47**: `loopx install <source>` when `.loopx/` exists and contains collisions → install succeeds for a non-colliding workflow. Install validates the source workflows, not all of `.loopx/`. *(Spec 5.4, 10.5)*
- **T-DISC-47a**: Invalid script name in a sibling workflow is fatal in normal run mode. Create `.loopx/ralph/index.sh` (valid) and `.loopx/broken/-bad.sh` (invalid script name). `loopx run ralph` → exits with code 1. Global validation catches the invalid name in the sibling workflow before execution begins. This is the normal-run-mode counterpart to T-CLI-22d (`-n 0`) and the name-restriction analogue to T-DISC-22 (sibling collision). *(Spec 5.3, 5.4)*
- **T-DISC-47b**: Invalid workflow name in a sibling workflow is fatal in normal run mode. Create `.loopx/good/index.sh` (valid) and `.loopx/-bad-workflow/index.sh` (invalid workflow name). `loopx run good` → exits with code 1. Global validation catches the invalid workflow name in the sibling before execution begins. This is the workflow-name counterpart to T-DISC-47a (sibling invalid script name) and the normal-run-mode counterpart to T-CLI-120 (invalid workflow name non-fatal in `run -h`). *(Spec 5.3, 5.4)*

#### Discovery Scope

- **T-DISC-48**: A parent directory has `.loopx/` with workflows, but the current working directory does not have `.loopx/`. `loopx run ralph` in the child directory fails — parent `.loopx/` is not discovered. *(Spec 5.1)*
- **T-DISC-48a**: API: no ancestor `.loopx/` search. Create a parent directory with `.loopx/ralph/index.sh` and a child subdirectory with no `.loopx/`. Call `run("ralph", { cwd: childDir })` (or `runPromise`). Assert: generator throws (or promise rejects) with a missing-workflow or missing-`.loopx/` error. The parent's `.loopx/ralph` must not be discovered — the project root is `cwd` only, with no ancestor search. This is the programmatic API counterpart to T-DISC-48, making the project-root-only model explicit for `run()` / `runPromise()`. *(Spec 5.1, 9.5)*

### 4.4 Script Execution

**Spec refs:** 6.1–6.5

#### Working Directory

- **T-EXEC-01**: Script in workflow `.loopx/ralph/index.sh` writes `$PWD` to a marker file. Assert the marker file content equals the absolute path of `.loopx/ralph/` (the workflow directory), **not** the project root. *(Spec 6.1)*
- **T-EXEC-02**: A different workflow `.loopx/other/index.sh` writes `$PWD` to a marker file. Assert it equals `.loopx/other/`. *(Spec 6.1)*
- **T-EXEC-03**: Script writes `$LOOPX_PROJECT_ROOT` to a marker file. Assert marker content equals the invocation directory (project root), not the workflow directory. *(Spec 6.1)*
- **T-EXEC-03a**: `LOOPX_PROJECT_ROOT` is preserved across cross-workflow goto. Script `ralph:index` outputs `goto:"other:check"`. Script `other:check` writes `$LOOPX_PROJECT_ROOT` to a marker file. Assert marker content equals the project root directory, not `.loopx/other/`. This pins down the one remaining env/cwd interaction not covered by T-EXEC-03 (normal execution), T-EXEC-16b (cross-workflow cwd switch), and T-EXEC-04b (cross-workflow `LOOPX_WORKFLOW` update): that `LOOPX_PROJECT_ROOT` stays the original project root after a cross-workflow transition, even though cwd changes to the target workflow directory. *(Spec 6.1, 8.3)*
- **T-EXEC-04**: `LOOPX_WORKFLOW` is injected correctly. Script writes `$LOOPX_WORKFLOW` to a marker file. Assert marker content equals the workflow name (e.g., `ralph`). *(Spec 8.3)*
- **T-EXEC-04a**: `LOOPX_WORKFLOW` overrides inherited/env-file values. Set `LOOPX_WORKFLOW=fake` in global env and spawn with `LOOPX_WORKFLOW=fake` in the process environment. Script writes `$LOOPX_WORKFLOW` to a marker file. Assert marker contains the real workflow name, not `"fake"`. *(Spec 8.3)*
- **T-EXEC-04b**: Cross-workflow goto updates `LOOPX_WORKFLOW`. Script `ralph:index` outputs `goto:"other:check"`. Script `other:check` writes `$LOOPX_WORKFLOW` to a marker file. Assert marker contains `other`, not `ralph`. *(Spec 8.3)*
- **T-EXEC-04c**: `LOOPX_WORKFLOW` is re-injected correctly after cross-workflow loop reset. `alpha:index` writes `$LOOPX_WORKFLOW` to a marker file keyed by iteration (e.g., appending to `alpha-marker`), then on its first execution outputs `goto:"beta:step"`. `beta:step` writes `$LOOPX_WORKFLOW` to `beta-marker`, then outputs no goto (chain ends, loop resets). On the next iteration, `alpha:index` runs again and appends to `alpha-marker`. Run with `-n 3`. Assert: (a) `beta-marker` contains `beta`, and (b) `alpha-marker` contains `alpha` on both its first and third iterations — proving the reset iteration sees `LOOPX_WORKFLOW` set back to the starting workflow name. This is the combination of T-EXEC-04b (cross-workflow updates `LOOPX_WORKFLOW`) and T-LOOP-33 (loop reset returns to starting target) that neither alone proves. *(Spec 8.3)*

#### Bash Scripts

- **T-EXEC-05**: A `.sh` script runs successfully and its stdout is captured as structured output. Observe via `runPromise("ralph", { maxIterations: 1 })`: the yielded Output contains the expected `result`. *(Spec 6.2)*
- **T-EXEC-06**: A `.sh` script's stderr appears on the CLI's stderr (pass-through). *(Spec 6.2)*
- **T-EXEC-07**: A `.sh` script that lacks `#!/bin/bash` still runs (loopx invokes via `/bin/bash` explicitly). Assert actual execution via marker file. *(Spec 6.2)*

#### JS/TS Scripts

- **T-EXEC-08**: `.ts` script runs and produces structured output. Observe via `runPromise("ralph", { maxIterations: 1 })`. *(Spec 6.3)*
- **T-EXEC-09**: `.js` script runs and produces structured output. *(Spec 6.3)*
- **T-EXEC-10**: `.tsx` script runs and produces structured output. The fixture **must use actual TSX syntax** to verify JSX transformation. *(Spec 6.3)*
- **T-EXEC-11**: `.jsx` script runs and produces structured output. The fixture **must use actual JSX syntax**. *(Spec 6.3)*
- **T-EXEC-12**: JS/TS script stderr passes through to CLI stderr. *(Spec 6.3)*
- **T-EXEC-13**: JS/TS script can use TypeScript type annotations (verifies tsx handles TS syntax under Node.js). `[Node]` *(Spec 6.3)*
- **T-EXEC-13b**: JS/TS script can use TypeScript type annotations under Bun. `[Bun]` *(Spec 6.3)*
- **T-EXEC-13a**: A `.js` script that uses `require()` (CJS) fails with an error. CJS is not supported. *(Spec 6.3)*
- **T-EXEC-14**: `[Bun]` When running under Bun, JS/TS scripts are executed via Bun's native runtime, not `tsx`. *(Spec 6.3)*

#### Workflow-Local Dependencies

- **T-EXEC-15**: Workflow with its own `node_modules/` can import from local dependencies. Setup: create a workflow with a local dependency in `node_modules/`. Script writes a marker file confirming the import succeeded. *(Spec 2.1)*
- **T-EXEC-16**: Workflow CWD is the workflow directory. TS script writes `process.cwd()` to a marker file. Assert marker content matches the workflow's directory path (e.g., `.loopx/ralph/`). *(Spec 6.1)*
- **T-EXEC-16a**: Workflow that imports a package not present in its `node_modules/` — the script fails with a module resolution error from the active runtime, and loopx exits with code 1. *(Spec 2.1)*
- **T-EXEC-16b**: Cross-workflow goto preserves per-workflow cwd. Set up `ralph:index` to output `goto:"other:check"`. Script `other:check` writes `$PWD` (bash) or `process.cwd()` (TS) to a marker file. Assert the marker content equals the absolute path of `.loopx/other/`, not `.loopx/ralph/`. This proves cwd switches to the target workflow's directory on cross-workflow goto — locking down ADR-0003 behavior that each workflow's scripts always execute in their own workflow directory, even when reached via cross-workflow transition. *(Spec 6.1, 2.2)*

### 4.5 Structured Output Parsing

**Spec refs:** 2.3

These tests use bash fixture scripts that echo specific strings to stdout. **Parsing correctness is asserted by examining the actual yielded `Output` object** via the programmatic API (`run()`, `runPromise()`, or `runAPIDriver()`), not by inferring from loop behavior alone.

All fixture scripts live inside a workflow (e.g., `.loopx/test/index.sh`). The `runPromise` calls use the workflow name.

#### Valid Structured Output

- **T-PARSE-01**: Script outputs `{"result":"hello"}`. Assert via `runPromise("test", { maxIterations: 1 })`: yielded Output is `{ result: "hello" }`. *(Spec 2.3)*
- **T-PARSE-02**: Script outputs `{"goto":"next"}` → loopx transitions to script `next` (within the same workflow). *(Spec 2.3)*
- **T-PARSE-03**: Script outputs `{"stop":true}` → loop halts, exit code 0. *(Spec 2.3)*
- **T-PARSE-04**: Script outputs `{"result":"x","goto":"next","stop":true}` → stop takes priority, loop halts. *(Spec 2.3)*
- **T-PARSE-05**: Script outputs `{"result":"x","extra":"ignored"}`. Assert via `runPromise("test", { maxIterations: 1 })`: yielded Output has `result: "x"` and no `extra` property. *(Spec 2.3)*

#### Fallback to Raw Result

- **T-PARSE-06**: Script outputs `{"unknown":"field"}` (valid JSON object, no known fields). Assert via `runPromise("test", { maxIterations: 1 })`: yielded Output is `{ result: '{"unknown":"field"}' }`. *(Spec 2.3)*
- **T-PARSE-07**: Script outputs `[1,2,3]` (JSON array). Assert yielded Output has `result: "[1,2,3]"`. *(Spec 2.3)*
- **T-PARSE-08**: Script outputs `"hello"` (JSON string). Assert yielded Output has `result: '"hello"'`. *(Spec 2.3)*
- **T-PARSE-09**: Script outputs `42` (JSON number). Assert yielded Output has `result: "42"`. *(Spec 2.3)*
- **T-PARSE-10**: Script outputs `true` (JSON boolean). Assert yielded Output has `result: "true"`. *(Spec 2.3)*
- **T-PARSE-11**: Script outputs `null` (JSON null). Assert yielded Output has `result: "null"`. *(Spec 2.3)*
- **T-PARSE-12**: Script outputs `not json at all`. Assert yielded Output has `result: "not json at all"`. *(Spec 2.3)*
- **T-PARSE-12a**: Raw fallback preserves exact stdout including trailing newline. Script outputs `hello\n`. Assert yielded Output has `result: "hello\n"`. *(Spec 2.3)*
- **T-PARSE-13**: Script produces empty stdout. Assert yielded Output is `{ result: "" }`. *(Spec 2.3)*

#### Type Coercion

- **T-PARSE-14**: `{"result": 42}`. Assert yielded Output has `result: "42"` (coerced via `String()`). *(Spec 2.3)*
- **T-PARSE-15**: `{"result": true}`. Assert yielded Output has `result: "true"`. *(Spec 2.3)*
- **T-PARSE-16**: `{"result": {"nested": "obj"}}`. Assert yielded Output has `result: "[object Object]"`. *(Spec 2.3)*
- **T-PARSE-17**: `{"result": null}`. Assert yielded Output has `result: "null"`. *(Spec 2.3)*
- **T-PARSE-18**: `{"goto": 42}` (goto is not a string). Assert yielded Output is exactly `{}`. *(Spec 2.3)*
- **T-PARSE-19**: `{"goto": true}`. Assert yielded Output is exactly `{}`. *(Spec 2.3)*
- **T-PARSE-20**: `{"goto": null}`. Assert yielded Output is exactly `{}`. *(Spec 2.3)*
- **T-PARSE-21**: `{"stop": "true"}` (string, not boolean). Assert yielded Output is exactly `{}`. Loop continues. *(Spec 2.3)*
- **T-PARSE-22**: `{"stop": 1}`. Assert yielded Output is exactly `{}`. *(Spec 2.3)*
- **T-PARSE-23**: `{"stop": false}`. Assert yielded Output is exactly `{}`. *(Spec 2.3)*
- **T-PARSE-24**: `{"stop": "false"}`. Assert yielded Output is exactly `{}`. *(Spec 2.3)*
- **T-PARSE-20a**: `{"goto":""}` (empty string goto). An empty string IS a string, so parser preserves it. Observe via `run("test")`: the first yielded Output has `goto: ""` (parsing preserves the string value without validating it). The generator throws an error when advancing past that iteration — target validation rejects `""` at transition time, not at parse time. This matches the T-MOD-13h model: parsing preserves, `run()` yields, transition validates. For direct rejection semantics, also verify `runPromise("test")` rejects with the same invalid-target error (the first iteration's output contains `goto: ""`, but the transition failure surfaces as a promise rejection). *(Spec 2.3, 4.1, 9.1, 9.2)*

#### Mixed Valid/Invalid Fields

- **T-PARSE-28**: `{"result":"x","goto":42}` (valid result + invalid goto). Assert yielded Output is exactly `{ result: "x" }`. *(Spec 2.3)*
- **T-PARSE-29**: `{"result":"x","stop":"true"}` (valid result + invalid stop). Assert yielded Output is exactly `{ result: "x" }`. *(Spec 2.3)*

#### Whitespace & Formatting

- **T-PARSE-25**: Script outputs JSON with trailing newline `{"result":"x"}\n`. Parsed correctly. *(Spec 2.3)*
- **T-PARSE-26**: Script outputs pretty-printed JSON (with newlines and indentation). Parsed correctly. *(Spec 2.3)*
- **T-PARSE-27**: Script outputs JSON with leading whitespace. Parsed correctly. *(Spec 2.3)*

### 4.6 Loop State Machine

**Spec refs:** 2.2, 7.1, 7.2, 6.6, 6.7

#### Basic Loop Behavior

- **T-LOOP-01**: Script produces no output → loop resets, starting target runs again. Use counter fixture with `-n 3` and verify 3 runs. *(Spec 2.2, 7.1)*
- **T-LOOP-02**: Script A (`ralph:index`) → `goto:"check"` → `ralph:check` produces no output → starting target `ralph:index` runs again. With `-n 4`, assert A ran twice, check ran twice. *(Spec 2.2)*
- **T-LOOP-03**: `ralph:index` → `goto:"setup"` → `ralph:setup` → `goto:"check"` → `ralph:check` → no goto → back to `ralph:index`. With `-n 4`, assert execution order index, setup, check, index. *(Spec 2.2)*
- **T-LOOP-04**: Script outputs `{"stop":true}` on first iteration → loop runs once, exits 0. *(Spec 2.2)*
- **T-LOOP-05**: Script runs 3 times then outputs `{"stop":true}` on 4th. Assert exactly 4 iterations. *(Spec 2.2)*

#### `-n` Counting

- **T-LOOP-06**: `-n 1` → exactly 1 iteration. *(Spec 7.1)*
- **T-LOOP-07**: `-n 3` with script that never stops → exactly 3 iterations. *(Spec 7.1)*
- **T-LOOP-08**: `-n 3` with `ralph:index` → `goto:"check"` → `ralph:check` → no goto. Execution: index, check, index. That's 3 iterations. *(Spec 7.1)*
- **T-LOOP-09**: `-n 2` with `ralph:index` → `goto:"check"`. Execution: index (1), check (2). *(Spec 7.1)*
- **T-LOOP-10**: `-n 0` → no iterations, script never runs. *(Spec 7.1)*

#### Input Piping

- **T-LOOP-11**: `ralph:index` outputs `{"result":"payload","goto":"reader"}`. `ralph:reader` reads stdin and outputs the received value as its result. Observe via `runPromise("ralph", { maxIterations: 2 })`: the second yielded Output has `result: "payload"`. *(Spec 6.6)*
- **T-LOOP-12**: `ralph:index` outputs `{"goto":"reader"}` (no result). `ralph:reader` reads stdin → empty string. *(Spec 2.3, 6.6)*
- **T-LOOP-13**: `ralph:index` outputs `{"result":"payload"}` (no goto). Loop resets to index. Index reads stdin → empty string (result not piped on reset). *(Spec 6.6)*
- **T-LOOP-14**: First iteration receives empty stdin. *(Spec 6.7)*
- **T-LOOP-15**: Chain A → goto B with result → B → goto C with result → C reads stdin and gets B's result, not A's. *(Spec 6.6)*
- **T-LOOP-15a**: Cross-workflow stdin piping. `ralph:index` outputs `{"result":"cross-payload","goto":"other:reader"}`. `other:reader` reads stdin and outputs the received value as its result. Observe via `runPromise("ralph", { maxIterations: 2 })`: the second yielded Output has `result: "cross-payload"`. Proves `result` crosses the workflow boundary via stdin. *(Spec 6.6, 2.2)*

#### Goto Semantics — Intra-Workflow

- **T-LOOP-16**: Goto is a transition, not permanent. `ralph:index` → `goto:"check"` → `ralph:check` → no goto → `ralph:index` runs again (not check). *(Spec 2.2)*
- **T-LOOP-17**: Self-referencing goto. `ralph:index` → `goto:"index"`. With `-n 2`, index runs twice. *(Spec 2.2)*
- **T-LOOP-18**: Goto target that doesn't exist within the workflow → error, exit code 1. *(Spec 7.2)*
- **T-LOOP-18a**: `{"goto":""}` (empty string goto) → error, exit code 1. *(Spec 2.3, 4.1, 7.2)*
- **T-LOOP-19**: Goto to a script name that exists in a different workflow but not the current one → error (bare goto resolves in current workflow). *(Spec 2.2, 7.2)*
- **T-LOOP-19a**: Bare goto matching an existing workflow name does not jump to that workflow's default entry point. Starting target: `ralph:index`. `ralph:index` emits `{"goto":"other"}`. `.loopx/other/index.sh` exists (a valid workflow with a default entry point). `.loopx/ralph/` has no `other.*` script. Expected: error (exit code 1), not a transition to `other:index`. In `goto`, a bare name is always a script in the current workflow, never another workflow's default entry point — the qualified form `"other:index"` is required for cross-workflow default-entry targeting. *(Spec 2.2, 7.2)*
- **T-LOOP-19b**: Positive bare-goto disambiguation: current-workflow script takes precedence over a same-named workflow. Set up: `.loopx/ralph/index.sh` (starting target), `.loopx/ralph/apply.sh` (a script in the current workflow), `.loopx/apply/index.sh` (another workflow also named `apply`). `ralph:index` emits `{"goto":"apply"}`. Expected: `ralph:apply` runs (bare goto resolves to the current workflow's `apply` script), not `apply:index`. Assert via marker file that `ralph/apply.sh` executed. *(Spec 2.2)*

#### Goto Semantics — Cross-Workflow

- **T-LOOP-30**: Qualified goto crosses workflows. `ralph:index` → `goto:"other:check"` → `other:check` runs. Assert via marker file that `other:check` executed. *(Spec 2.2)*
- **T-LOOP-30a**: Qualified cross-workflow goto into a workflow with no `index` script. Starting target: `alpha:index`. `alpha:index` → `goto:"beta:check"`. `.loopx/beta/check.sh` exists. `.loopx/beta/index.*` does not exist. Assert `beta:check` runs successfully (via marker file). A workflow without a default entry point is still reachable via qualified goto targeting an explicit script. *(Spec 2.2, 4.1)*
- **T-LOOP-31**: Qualified same-workflow goto works. `ralph:index` → `goto:"ralph:check"` is equivalent to bare `goto:"check"`. *(Spec 2.2)*
- **T-LOOP-31a**: Cross-workflow default-entry targeting via qualified goto. Starting target: `ralph:index`. `ralph:index` → `goto:"other:index"`. Assert `other:index` runs (via marker file). This tests the positive case of targeting another workflow's default entry point via goto — goto requires the qualified form `"workflow:index"` since a bare name resolves as a script within the current workflow. *(Spec 2.2, 4.1)*
- **T-LOOP-31b**: Qualified same-workflow goto to `index`. Starting target: `ralph:check`. `ralph:check` → `goto:"ralph:index"`. Assert `ralph:index` runs (via marker file). This covers the exact corner case of using the qualified form to target the default entry point within the same workflow — T-LOOP-31 covers qualified same-workflow goto to a non-index script (`ralph:check`), T-LOOP-17 covers bare self-goto to `index`, and T-LOOP-31a covers cross-workflow goto to `other:index`, but none cover the `"ralph:index"` qualified form from within `ralph` itself. A bad implementation could special-case `index` in the qualified-goto resolution path. *(Spec 2.2)*
- **T-LOOP-31c**: Cross-workflow qualified goto to `other:index` where `other` exists but has no `index` script → error, exit code 1. Starting target: `ralph:index`. `ralph:index` → `goto:"other:index"`. `.loopx/other/` exists with at least one script (e.g., `check.sh`) but no `index.*`. The qualified `:index` goto target follows the ordinary missing-script rule — a workflow without a default entry point cannot be targeted via `workflow:index` from goto. T-LOOP-31a covers the positive case (target workflow has `index`); T-LOOP-35 covers a generic missing script in the target workflow; this test pins down the specific `:index` missing case so a buggy implementation cannot special-case `:index` in qualified-goto resolution to fall back to "any script" or to silently succeed. ADR-0003 makes `index` special only when omitted, even on the cross-workflow goto path. *(Spec 2.2, 7.2, 4.1)*
- **T-LOOP-32**: Bare goto from a cross-workflow context resolves in the executing workflow, not the starting workflow. Starting target: `ralph:index`. `ralph:index` → `goto:"other:step1"`. `other:step1` → `goto:"step2"` (bare). Assert `other:step2` runs, not `ralph:step2`. *(Spec 2.2)*
- **T-LOOP-32a**: Bare `goto:"index"` from a cross-workflow context resolves to the executing workflow's `index`, not the starting workflow's `index`. Starting target: `alpha:index`. `alpha:index` → `goto:"beta:step"`. `beta:step` → `goto:"index"` (bare). Assert `beta:index` runs (via marker file), not `alpha:index`. This is the `index`-specific variant of T-LOOP-32 — because `index` has special default-entry semantics in `run` targeting (bare `run ralph` means `ralph:index`), the bare cross-workflow `goto` resolution must be pinned down directly for `index`. Existing coverage proves bare cross-workflow resolution for non-`index` names (T-LOOP-32) and qualified `other:index` (T-LOOP-31a), but not the bare `index` case. A buggy implementation could special-case the bare name `"index"` to re-enter the starting workflow's default entry point or treat it as a workflow reference. *(Spec 2.2)*
- **T-LOOP-33**: Loop reset always returns to the starting target. Starting target: `ralph:index`. `ralph:index` → `goto:"other:check"` → `other:check` → no goto → loop resets to `ralph:index` (not `other:index`). *(Spec 2.2)*
- **T-LOOP-34**: Missing workflow in qualified goto → error, exit code 1. `ralph:index` → `goto:"nonexistent:check"`. *(Spec 7.2)*
- **T-LOOP-35**: Missing script in target workflow → error, exit code 1. `ralph:index` → `goto:"other:nonexistent"`. *(Spec 7.2)*
- **T-LOOP-36**: Malformed goto target → error at transition time. `ralph:index` → `goto:":script"` (leading colon). *(Spec 4.1, 7.2)*
- **T-LOOP-37**: Malformed goto target → error. `ralph:index` → `goto:"a:b:c"` (multiple colons). *(Spec 4.1, 7.2)*
- **T-LOOP-38**: Malformed goto target → error. `ralph:index` → `goto:":"` (bare colon). *(Spec 4.1, 7.2)*
- **T-LOOP-39**: Malformed goto target → error. `ralph:index` → `goto:"other:"` (trailing colon). *(Spec 4.1, 7.2)*
- **T-LOOP-40**: Goto with name restriction failure in bare name. `ralph:index` → `goto:"-bad"`. Error, exit code 1. *(Spec 4.1, 5.3, 7.2)*
- **T-LOOP-41**: Goto with name restriction failure in qualified target's script portion. `ralph:index` → `goto:"other:-bad"`. Error, exit code 1. *(Spec 4.1, 5.3, 7.2)*
- **T-LOOP-42**: Goto with name restriction failure in qualified target's workflow portion. `ralph:index` → `goto:"-bad:index"`. Error, exit code 1. *(Spec 4.1, 5.3, 7.2)*
- **T-LOOP-43**: Reset to explicit script starting target (not the workflow default). Starting target: `ralph:check` (not `index`). `ralph:check` → `goto:"other:step"` → `other:step` → no goto → loop resets to `ralph:check`, not `ralph:index`. Assert via counter/marker files that `ralph:check` runs again. *(Spec 2.2)*

#### Error Handling

- **T-LOOP-20**: Script exits with code 1 → loop stops immediately. loopx exits with code 1. *(Spec 7.2)*
- **T-LOOP-21**: Script exits with code 2 → same behavior (any non-zero is an error). *(Spec 7.2)*
- **T-LOOP-22**: Script fails on iteration 3 of 5 (`-n 5`). Assert exactly 3 iterations ran. *(Spec 7.2)*
- **T-LOOP-23**: Script's stderr output on failure is visible on CLI stderr. *(Spec 7.2)*
- **T-LOOP-24**: Script's stdout on failure is NOT parsed as structured output. Observe via `run("ralph")`: the generator throws without yielding an Output for that iteration. *(Spec 7.2)*

#### Final Iteration Output

- **T-LOOP-25**: `-n 2` with script producing `{"result":"iter-N"}`. Both iterations' outputs are observable via programmatic API. *(Spec 7.1)*

### 4.7 Environment Variables

**Spec refs:** 8.1–8.3

All env tests use `withGlobalEnv` to isolate from the real user config.

#### Global Env File

- **T-ENV-01**: Variable set via `loopx env set` is available in a script. Use `write-env-to-file` fixture inside a workflow's `index.sh`. Assert the marker file contains the expected value. *(Spec 8.1, 8.3)*
- **T-ENV-02**: Variable removed via `loopx env remove` is no longer available. Use `observe-env` fixture. Assert `{ "present": false }`. *(Spec 8.1)*
- **T-ENV-03**: `XDG_CONFIG_HOME` is respected. *(Spec 8.1)*
- **T-ENV-04**: When `XDG_CONFIG_HOME` is unset, default is `~/.config`. Use `withIsolatedHome`. *(Spec 8.1)*
- **T-ENV-05**: Config directory created on first `env set`. *(Spec 8.1)*
- **T-ENV-05a**: Unreadable global env file → exits with code 1. **Conditional on `process.getuid() !== 0`.** *(Spec 8.1)*
- **T-ENV-05b**: Unreadable global env file via programmatic API → generator throws. **Conditional on `process.getuid() !== 0`.** *(Spec 8.1, 9.3)*
- **T-ENV-05c**: Unreadable global env file with `loopx env list` → exits with code 1. **Conditional on `process.getuid() !== 0`.** *(Spec 8.1)*
- **T-ENV-05d**: Unreadable global env file with `loopx env set` → exits with code 1. **Conditional on `process.getuid() !== 0`.** *(Spec 8.1)*
- **T-ENV-05e**: Unreadable global env file with `loopx env remove` → exits with code 1. **Conditional on `process.getuid() !== 0`.** *(Spec 8.1)*

#### Env File Parsing

All env file parsing tests below use `writeEnvFileRaw` to write exact file content, then a `write-env-to-file` fixture script inside a workflow to observe the parsed value via a marker file.

- **T-ENV-06**: `writeEnvFileRaw(path, "KEY=VALUE\n")`. Assert marker contains `VALUE`. *(Spec 8.1)*
- **T-ENV-07**: `writeEnvFileRaw(path, "# comment\nKEY=val\n")`. Assert `KEY=val`. *(Spec 8.1)*
- **T-ENV-08**: Blank lines ignored, `KEY=val` loaded. *(Spec 8.1)*
- **T-ENV-09**: Duplicate keys: last occurrence wins. *(Spec 8.1)*
- **T-ENV-10**: Double-quoted value → quotes stripped. *(Spec 8.1)*
- **T-ENV-11**: Single-quoted value → quotes stripped. *(Spec 8.1)*
- **T-ENV-12**: No escape sequences → literal `hello\nworld`. *(Spec 8.1)*
- **T-ENV-13**: Inline `#` is part of value. *(Spec 8.1)*
- **T-ENV-14**: Trailing whitespace on value trimmed. *(Spec 8.1)*
- **T-ENV-15**: `KEY = value` → invalid key (space before `=`). Warning on stderr. *(Spec 8.1)*
- **T-ENV-15f**: `KEY= value` → leading space in value preserved. *(Spec 8.1)*
- **T-ENV-15a**: `KEY=` → empty value. Variable is present with empty string. *(Spec 8.1)*
- **T-ENV-15b**: `KEY=a=b=c` → split on first `=`. *(Spec 8.1)*
- **T-ENV-15c**: `1BAD=val` → invalid key, line ignored with warning. *(Spec 8.1)*
- **T-ENV-15d**: `justtext` → malformed line, ignored with warning. *(Spec 8.1)*
- **T-ENV-15e**: Unmatched quotes → literal preserved. *(Spec 8.1)*

#### Local Env Override (`-e`)

- **T-ENV-16**: `-e local.env` loads variables into script. *(Spec 8.2)*
- **T-ENV-17**: `-e nonexistent.env` → error, exit 1. *(Spec 8.2)*
- **T-ENV-17a**: `-e unreadable.env` → error, exit 1. **Conditional on `process.getuid() !== 0`.** *(Spec 8.2)*
- **T-ENV-18**: Global has `X=global`, local has `X=local`. Script sees `local`. *(Spec 8.2)*
- **T-ENV-19**: Global has `A=1`, local has `B=2`. Both present. *(Spec 8.2)*

#### Injection Precedence

- **T-ENV-20**: `LOOPX_BIN` is always set, overrides user values. *(Spec 8.3)*
- **T-ENV-20a**: `LOOPX_BIN` overrides inherited system environment. *(Spec 8.3)*
- **T-ENV-20b**: `LOOPX_BIN` overrides local env file (`-e`) value. Create a local env file containing `LOOPX_BIN=/tmp/fake-binary`. Run with `-e <envfile>`. Script writes `$LOOPX_BIN` to a marker file. Assert marker contains the real injected binary path (a valid executable path that is not `/tmp/fake-binary`). This explicitly tests the highest-precedence layer (loopx-injected) against the second-highest layer (local `-e`) for `LOOPX_BIN`, completing the SPEC 8.3 precedence coverage pattern established by T-ENV-21c for `LOOPX_WORKFLOW`. *(Spec 8.3)*
- **T-ENV-21**: `LOOPX_PROJECT_ROOT` always set, overrides user-supplied value. *(Spec 8.3)*
- **T-ENV-21a**: `LOOPX_PROJECT_ROOT` overrides inherited system environment. *(Spec 8.3)*
- **T-ENV-21b**: `LOOPX_WORKFLOW` always set, overrides user-supplied value. Script writes `$LOOPX_WORKFLOW` to a marker file. Set `LOOPX_WORKFLOW=fake` in global env. Assert marker contains the real workflow name. *(Spec 8.3)*
- **T-ENV-21c**: `LOOPX_WORKFLOW` overrides local env file (`-e`) value. Create a local env file containing `LOOPX_WORKFLOW=fake`. Run with `-e <envfile>`. Script writes `$LOOPX_WORKFLOW` to a marker file. Assert marker contains the real workflow name, not `"fake"`. This explicitly tests the highest-precedence layer (loopx-injected) against the second-highest layer (local `-e`). *(Spec 8.3)*
- **T-ENV-21d**: `LOOPX_PROJECT_ROOT` overrides local env file (`-e`) value. Create a local env file containing `LOOPX_PROJECT_ROOT=/tmp/fake-project-root`. Run with `-e <envfile>`. Script writes `$LOOPX_PROJECT_ROOT` to a marker file. Assert marker contains the real project root (the invocation cwd), not `/tmp/fake-project-root`. This explicitly tests the highest-precedence layer (loopx-injected) against the second-highest layer (local `-e`) for `LOOPX_PROJECT_ROOT`, completing the SPEC 8.3 precedence coverage pattern alongside T-ENV-20b (`LOOPX_BIN`) and T-ENV-21c (`LOOPX_WORKFLOW`). *(Spec 8.3)*
- **T-ENV-22**: System env has `SYS_VAR=sys`, global env has `SYS_VAR=global`. Script sees `global`. *(Spec 8.3)*
- **T-ENV-23**: System env has `SYS_VAR=sys`, no loopx override. Script sees `sys`. *(Spec 8.3)*
- **T-ENV-24**: Full precedence chain. Assert local wins over global over system. *(Spec 8.3)*
- **T-ENV-24a**: `LOOPX_DELEGATED` is visible in script execution environments when inherited. Spawn loopx with `LOOPX_DELEGATED=1` in the inherited process environment. Script uses `observe-env` fixture for `LOOPX_DELEGATED`. Assert marker contains `{ "present": true, "value": "1" }`. The spec does not require loopx to scrub this variable before spawning scripts — it is part of the inherited system environment. *(Spec 8.3, 3.2)*
- **T-ENV-24b**: Empty-string value in local env file overrides non-empty global/system value. *(Spec 8.3)*

#### Env Caching

- **T-ENV-25**: During a multi-iteration loop, modify the global env file between iterations. Assert the marker contains the original value. *(Spec 8.1)*
- **T-ENV-25a**: During a multi-iteration loop with `-e`, modify the local env file between iterations. Assert original value persists. *(Spec 8.2)*
- **T-ENV-25b**: `loopx run -n 0 ralph` with an unreadable global env file → exits with code 1. Global env loading and validation happens before the `-n 0` short-circuit. **Conditional on `process.getuid() !== 0`.** *(Spec 4.2, 8.1)*
- **T-ENV-25c**: `loopx run -n 0 ralph` with a malformed-but-readable global env file (e.g., containing `1BAD=val`) → exits with code 0, stderr contains a parser warning for the invalid key. Proves global env files are actually parsed under `-n 0`, not just existence/readability checked. This is the global-env counterpart to T-CLI-22c (which covers the local `-e` file under `-n 0`). *(Spec 4.2, 8.1)*

### 4.8 Module Resolution & Script Helpers

**Spec refs:** 3.3, 3.4, 6.4, 6.5

#### `import from "loopx"` Resolution

- **T-MOD-01**: A TS script in a workflow with `import { output } from "loopx"` runs successfully under Node.js. `[Node]` *(Spec 3.3)*
- **T-MOD-02**: Same import works under Bun. `[Bun]` *(Spec 3.3)*
- **T-MOD-03**: A JS script with `import { output } from "loopx"` also works. *(Spec 3.3)*
- **T-MOD-03a**: A workflow that has its own `node_modules/loopx` (a different version) resolves `import from "loopx"` to the **local** package, not the running CLI's package. Standard module resolution applies — the closest `node_modules` wins. The workflow-local `node_modules/loopx` package must export a sentinel value (e.g., a unique marker string from a custom `output()` or an additional export) that differs from the CLI-provided package. The test script imports from `"loopx"` and writes the sentinel to a marker file. Assert: (a) the marker file contains the workflow-local sentinel, proving the local package was actually loaded (not just that the CLI didn't warn), and (b) **no warning is emitted on stderr** — per Spec 3.3, no warning is emitted for workflow-local `node_modules/loopx` resolution in v1. *(Spec 3.3, 2.1)*
- **T-MOD-03b**: Combined precedence: project-root delegation is active (project-root `package.json` declares `loopx`, `node_modules/.bin/loopx` exists) **and** the target workflow has its own `node_modules/loopx` with a different sentinel export. The test script imports from `"loopx"` and writes the resolved sentinel to a marker file. Assert: the marker file contains the **workflow-local** sentinel, not the project-root delegated package's sentinel. This tests the full Spec 3.3 precedence chain — delegation determines which CLI binary runs, but `import "loopx"` within a script resolves to the closest `node_modules/loopx` (the workflow-local one), not the delegated project-root one. T-MOD-03a tests workflow-local vs. CLI without delegation; T-DEL-06 tests delegation without workflow-local; this test combines both and asserts the workflow-local package wins. *(Spec 3.3, 3.2)*
- **T-MOD-03c**: Workflow-level `package.json` `type` field is respected for intra-workflow `.js` module resolution. Create `.loopx/ralph/package.json` with `{ "type": "module" }`, `.loopx/ralph/lib/helper.js` containing `export const value = "esm-resolved";` (ESM named export), and `.loopx/ralph/index.ts` that does `import { value } from "./lib/helper.js"; import { output } from "loopx"; output({ result: value });`. Run `loopx run -n 1 ralph` under Node.js. Assert: (a) exit code 0, and (b) output result is `"esm-resolved"`. The `.ts` entry point is executed via tsx, but the imported `.js` helper in `lib/` is resolved through Node.js's standard module system, where the nearest `package.json` `type` field determines whether `.js` files are treated as ESM. This verifies that loopx's execution model (workflow directory as cwd, per Spec 6.1) correctly exposes the workflow's `package.json` `type` field to Node.js module resolution for intra-workflow imports. `[Node]` *(Spec 2.1, 3.3)*

#### `output()` Function

- **T-MOD-04**: `output({ result: "hello" })`. Observe via `runPromise("ralph", { maxIterations: 1 })`: yielded Output has `result: "hello"`. *(Spec 6.4)*
- **T-MOD-05**: `output({ result: "x", goto: "check" })`. Observe via `run("ralph")`: yielded Output has both fields, and loopx transitions. *(Spec 6.4)*
- **T-MOD-05a**: TS/JS script `alpha:index` calls `output({ goto: "beta:index" })`; `beta:index` writes a marker file and then calls `output({ stop: true })`. Assert `beta:index` executed (marker file exists). This is a positive end-to-end test for a JS/TS `output()` cross-workflow goto: T-MOD-05 covers intra-workflow goto and T-LOOP-05 covers cross-workflow goto generally, but no existing test exercises a JS/TS `output()` emitting a qualified `workflow:script` target that the loop follows. *(Spec 6.4, 2.2)*
- **T-MOD-06**: `output({ stop: true })`. Loop completes after one iteration. *(Spec 6.4)*
- **T-MOD-07**: `output({})` (no known fields). Script crashes with non-zero exit code. *(Spec 6.4)*
- **T-MOD-08**: `output(null)`. Script crashes. *(Spec 6.4)*
- **T-MOD-09**: `output(undefined)`. Script crashes. *(Spec 6.4)*
- **T-MOD-10**: `output("string")`. Yielded Output has `result: "string"`. *(Spec 6.4)*
- **T-MOD-11**: `output(42)`. Yielded Output has `result: "42"`. *(Spec 6.4)*
- **T-MOD-12**: `output(true)`. Yielded Output has `result: "true"`. *(Spec 6.4)*
- **T-MOD-13**: `output({ result: "x", goto: undefined })`. Yielded Output has `result: "x"` and no `goto` property. *(Spec 6.4)*
- **T-MOD-13a**: `output([1, 2, 3])` (array, no known fields). Script crashes. *(Spec 6.4)*
- **T-MOD-13b**: `output({ result: undefined, goto: undefined, stop: undefined })`. Equivalent to `output({})`. Script crashes. *(Spec 6.4)*
- **T-MOD-13c**: `output({ foo: "bar" })`. Script crashes (no known fields). *(Spec 6.4)*
- **T-MOD-13d**: `output({ stop: false })`. Output accepted, but parsed as `{}` (stop must be exactly true). Loop continues. *(Spec 6.4, 2.3)*
- **T-MOD-13e**: `output({ goto: 42 })`. Output accepted, but parsed as `{}` (goto must be string). Loop resets. *(Spec 6.4, 2.3)*
- **T-MOD-13f**: `output({ result: null })`. Coerced to `"null"`. *(Spec 6.4, 2.3)*
- **T-MOD-13g**: `output({ goto: null })`. Parsed as `{}`. Loop resets. *(Spec 6.4, 2.3)*
- **T-MOD-13h**: JS/TS `output()` does not validate goto targets. Script calls `output({ goto: "a:b:c" })`. The script exits 0 (`output()` serializes the value without validation). Observe via `run("test")`: the first yielded Output has `goto: "a:b:c"`, then the generator throws an error at transition time (malformed goto target — multiple colons). This mirrors the CLI-helper non-validation behavior tested in T-SUB-02d. *(Spec 6.4)*
- **T-MOD-13i**: JS/TS `output()` does not validate leading-colon goto targets. Script calls `output({ goto: ":script" })`. The script exits 0. Observe via `run("test")`: the first yielded Output has `goto: ":script"`, then the generator throws at transition time (leading colon). This mirrors the CLI-helper non-validation behavior tested in T-SUB-02e. *(Spec 6.4)*
- **T-MOD-13j**: JS/TS `output()` does not validate trailing-colon goto targets. Script calls `output({ goto: "workflow:" })`. The script exits 0. Observe via `run("test")`: the first yielded Output has `goto: "workflow:"`, then the generator throws at transition time (trailing colon). This mirrors the CLI-helper non-validation behavior tested in T-SUB-02f. *(Spec 6.4)*
- **T-MOD-13k**: JS/TS `output()` does not validate empty-string goto targets. Script calls `output({ goto: "" })`. The script exits 0. Observe via `run("test")`: the first yielded Output has `goto: ""`, then the generator throws at transition time (empty string). This mirrors the CLI-helper non-validation behavior tested in T-SUB-02c. An implementation that incorrectly rejects falsy `""` at serialization time would fail here. *(Spec 6.4)*
- **T-MOD-13l**: JS/TS `output()` does not validate bare-colon goto targets. Script calls `output({ goto: ":" })`. The script exits 0. Observe via `run("test")`: the first yielded Output has `goto: ":"`, then the generator throws at transition time (bare colon). This mirrors the CLI-helper non-validation behavior tested in T-SUB-02g. *(Spec 6.4)*
- **T-MOD-13m**: JS/TS `output()` does not validate goto target existence. Script calls `output({ goto: "missing-workflow:missing-script" })`. The script exits 0. Observe via `run("test")`: the first yielded Output has `goto: "missing-workflow:missing-script"`, then the generator throws at transition time (nonexistent workflow). The existing non-validation tests (T-MOD-13h–13l) cover syntactically invalid targets; this test covers a syntactically valid but nonexistent target, confirming the helper only serializes and existence validation is deferred to loop execution time. This mirrors CLI-helper T-SUB-02h. *(Spec 6.4)*
- **T-MOD-13n**: JS/TS `output()` does not validate name-pattern violations in bare goto targets. Script calls `output({ goto: "bad.name" })`. The script exits 0 (`output()` serializes without validation). Observe via `run("test")`: the first yielded Output has `goto: "bad.name"`, then the generator throws at transition time (invalid bare target — the dot violates the name restriction `[a-zA-Z0-9_][a-zA-Z0-9_-]*`). T-MOD-13h–13l cover invalid colon shapes and T-MOD-13m covers a syntactically valid but nonexistent target; this test covers name-pattern violations, which are a distinct validation category. A `output()` that incorrectly regex-validates names at serialization time would fail here. This mirrors CLI-helper T-SUB-02i. *(Spec 6.4)*
- **T-MOD-13o**: JS/TS `output()` does not validate name-pattern violations in the workflow portion of a qualified goto target. Script calls `output({ goto: "bad.name:index" })`. The script exits 0. Observe via `run("test")`: the first yielded Output has `goto: "bad.name:index"`, then the generator throws at transition time (workflow-portion name violates the name restriction pattern). This is the qualified-target counterpart to T-MOD-13n and mirrors CLI-helper T-SUB-02j. *(Spec 6.4)*
- **T-MOD-13p**: JS/TS `output()` does not validate name-pattern violations in the script portion of a qualified goto target. Script calls `output({ goto: "ralph:bad.name" })`. The script exits 0. Observe via `run("test")`: the first yielded Output has `goto: "ralph:bad.name"`, then the generator throws at transition time (script-portion name violates the name restriction pattern). Combined with T-MOD-13o, this proves that name-pattern validation is deferred for both portions of qualified targets. This mirrors CLI-helper T-SUB-02k. *(Spec 6.4)*
- **T-MOD-14**: Code after `output()` does not execute. *(Spec 6.4)*
- **T-MOD-14a**: Large-payload flush: `output({ result: "x".repeat(1_000_000) })`. Full 1 MB string preserved. *(Spec 6.4)*

#### `input()` Function

- **T-MOD-15**: `input()` returns empty string on first iteration. *(Spec 6.5)*
- **T-MOD-16**: `ralph:index` → `output({ result: "payload", goto: "reader" })` → `ralph:reader` calls `input()` → receives `"payload"`. *(Spec 6.5)*
- **T-MOD-17**: `input()` called twice returns the same value (cached). *(Spec 6.5)*
- **T-MOD-18**: `input()` returns a Promise. *(Spec 6.5)*

#### ESM-Only Package Contract

- **T-MOD-22**: `[Node]` `require("loopx")` from a CJS consumer fails with ERR_REQUIRE_ESM. *(Spec 1)*

#### `LOOPX_BIN` in Bash Scripts

**These tests use `withDelegationSetup` (or the real executable path), not `runCLI`.**

- **T-MOD-19**: Bash script uses `$LOOPX_BIN output --result "payload" --goto "reader"`. Assert the reader script receives `"payload"` via stdin. *(Spec 3.4)*
- **T-MOD-20**: Bash script writes `$LOOPX_BIN` to a marker file. Assert it contains a valid executable path. *(Spec 3.4)*
- **T-MOD-21**: Bash script runs `$LOOPX_BIN version` and captures stdout. Assert it matches the package version. *(Spec 3.4)*
- **T-MOD-21a**: End-to-end bash cross-workflow goto via `$LOOPX_BIN output`. Create two workflows: `.loopx/alpha/index.sh` (runs `$LOOPX_BIN output --goto "beta:index"`) and `.loopx/beta/index.sh` (writes `"arrived"` to a marker file via `printf '%s' "arrived" > <markerPath>`, then runs `$LOOPX_BIN output --result "arrived" --stop`). Run `loopx run alpha` via CLI. Assert: (a) exit code 0 (stop: true halted the loop cleanly), and (b) the marker file exists and contains `"arrived"` (proving `beta:index` executed after the cross-workflow goto). The CLI never prints structured Output to its own stdout (Spec 7.1), so assertions use marker files and exit code, not stdout parsing. This is a composition test spanning sections 3.4 (LOOPX_BIN), 4.3 (loopx output subcommand), and 2.2 (cross-workflow goto). *(Spec 3.4, 4.3, 2.2)*

### 4.9 Programmatic API

**Spec refs:** 9.1–9.5

**Runtime-matrix methodology:** All programmatic API tests that run under both Node.js and Bun use `runAPIDriver()` to spawn a driver process under the target runtime.

#### `run()` (AsyncGenerator)

- **T-API-01**: `run("ralph")` returns an async generator. Calling `next()` yields an `Output` object. *(Spec 9.1)*
- **T-API-02**: Generator yields one `Output` per iteration. With `maxIterations: 3`, collect all yields → array of 3 outputs. *(Spec 9.1)*
- **T-API-03**: Generator completes when `stop: true` is output. *(Spec 9.1)*
- **T-API-04**: Generator completes when `maxIterations` is reached. *(Spec 9.1)*
- **T-API-05**: The output from the final iteration is yielded before the generator completes. *(Spec 9.1)*
- **T-API-06**: Breaking out of `for await` loop after the first yield prevents further iterations. *(Spec 9.1)*
- **T-API-07**: `run("ralph", { cwd: "/path/to/project" })` resolves workflows relative to the given cwd. `cwd` is the **project root** — it controls where `.loopx/` is found and sets `LOOPX_PROJECT_ROOT`, but does not control the script's execution working directory (scripts always run with their workflow directory as cwd). The test must explicitly assert that `LOOPX_PROJECT_ROOT` equals the provided `cwd` value (via a marker file written by the script using `observe-env`), not just that discovery succeeded. *(Spec 9.5, 6.1)*
- **T-API-07a**: `RunOptions.cwd` does not control script execution cwd. Create a workflow in project A. Call `run("ralph", { cwd: projectA })`. Script writes `process.cwd()` to a marker file. Assert marker equals the workflow directory path (`.loopx/ralph/`), not `projectA`. *(Spec 9.5, 6.1)*
- **T-API-08**: `run("ralph", { maxIterations: 0 })` → generator completes immediately with no yields. *(Spec 9.5)*
- **T-API-08a**: `run("nonexistent", { maxIterations: 0 })` → generator throws on first `next()` (validation runs before zero-iteration short-circuit). *(Spec 9.1, 9.5, 7.1)*
- **T-API-08b**: `runPromise("ralph", { maxIterations: 0 })` skips workflow-level version checking, mirroring CLI `-n 0`. Set up `.loopx/ralph/` with `package.json` declaring a loopx version range not satisfied by the running version. Assert: (a) resolves with `[]`, and (b) no version mismatch warning on stderr. *(Spec 9.5, 3.2)*
- **T-API-08c**: `run("ralph", { maxIterations: 0 })` where `ralph` exists but has no `index` script → generator throws on first `next()`. Target resolution validates the default entry point even with `maxIterations: 0`. *(Spec 9.1, 9.5, 4.1)*
- **T-API-08d**: `run("ralph:missing", { maxIterations: 0 })` where `ralph` exists but script `missing` does not → generator throws on first `next()`. *(Spec 9.1, 9.5, 4.1)*
- **T-API-08e**: `run("ralph", { maxIterations: 0, envFile: "missing.env" })` → generator throws on first `next()`. Env file validation fires even with `maxIterations: 0`, mirroring CLI `-n 0` behavior (T-CLI-22a). *(Spec 9.1, 9.5, 4.2)*
- **T-API-08f**: `runPromise("ralph", { maxIterations: 0, envFile: "missing.env" })` → rejects. Env file validation fires even with `maxIterations: 0`, mirroring CLI `-n 0` behavior. *(Spec 9.2, 9.5, 4.2)*
- **T-API-08g**: `run("ralph", { maxIterations: 0 })` skips the entire version-check path, including `package.json` reading. Set up `.loopx/ralph/package.json` with an invalid semver range for `loopx` (e.g., `"loopx": "not-a-range"` in `dependencies`). Assert: generator completes with no yields, and no `package.json` or version-related warnings on stderr. This extends T-API-08b (which tests unsatisfied range via `runPromise`) to prove the entire runtime version-check path is skipped under `maxIterations: 0` — not just the range comparison. *(Spec 9.1, 9.5, 3.2)*
- **T-API-08h**: `run("ralph", { maxIterations: 0 })` with `.loopx/` containing a sibling workflow with a same-base-name collision (e.g., `.loopx/broken/check.sh` and `.loopx/broken/check.ts`) → generator throws on first `next()`. Global discovery validation catches the collision before the zero-iteration short-circuit, mirroring CLI `-n 0` behavior (T-CLI-22b). *(Spec 9.1, 9.5, 5.2)*
- **T-API-08i**: `run("ralph", { maxIterations: 0 })` with `.loopx/` containing a sibling workflow with an invalid script name (e.g., `.loopx/broken/-bad.sh`) → generator throws on first `next()`. Global discovery validation catches the invalid name before the zero-iteration short-circuit, mirroring CLI `-n 0` behavior (T-CLI-22d). *(Spec 9.1, 9.5, 5.3)*
- **T-API-08j**: `run("ralph", { maxIterations: 0 })` with `.loopx/` containing a sibling workflow with an invalid workflow name (e.g., `.loopx/-bad-workflow/index.sh`) → generator throws on first `next()`. Global discovery validation catches the invalid workflow name before the zero-iteration short-circuit, mirroring CLI `-n 0` behavior (T-CLI-22e). *(Spec 9.1, 9.5, 5.3)*
- **T-API-08k**: `run("ralph", { maxIterations: 0, envFile: "malformed.env" })` where `malformed.env` exists and is readable but contains an invalid line (e.g., `1BAD=val`) → generator completes with no yields, stderr contains a parser warning for the invalid key. Env files are parsed under `maxIterations: 0`, not just existence-checked, mirroring CLI `-n 0` behavior (T-CLI-22c). *(Spec 9.1, 9.5, 8.1)*
- **T-API-08l**: `run("ralph", { maxIterations: 0 })` with an unreadable global env file → generator throws on first `next()`. Global env loading and validation fires before the zero-iteration short-circuit, mirroring CLI `-n 0` behavior (T-ENV-25b). **Conditional on `process.getuid() !== 0`.** *(Spec 9.1, 9.5, 8.1)*
- **T-API-08m**: `run("ralph", { maxIterations: 0 })` with a malformed-but-readable global env file (e.g., containing `1BAD=val`) → generator completes with no yields, stderr contains a parser warning for the invalid key. Global env files are parsed under `maxIterations: 0` in the programmatic API, mirroring CLI `-n 0` behavior (T-ENV-25c). *(Spec 9.1, 9.5, 8.1)*
- **T-API-08n**: `runPromise("a:b:c", { maxIterations: 0 })` → rejects. Malformed target strings (multiple colons) are validated before the `maxIterations: 0` short-circuit, mirroring CLI `-n 0` behavior (T-CLI-119d). This extends the `maxIterations: 0` validation coverage (T-API-08a/08c/08d test missing workflow/index/script) to cover target-syntax validation. *(Spec 9.2, 9.5, 4.1)*
- **T-API-08n1**: `run("a:b:c", { maxIterations: 0 })` returns a generator (lazy); on the first `next()`, the generator throws an invalid-target error. Malformed target strings (multiple colons) are validated before the `maxIterations: 0` short-circuit on the generator surface, mirroring CLI `-n 0` behavior (T-CLI-119d) and the `runPromise` surface (T-API-08n). This is the `run()` generator counterpart to T-API-08n, completing target-syntax validation parity under `maxIterations: 0` across all three surfaces (CLI, `run()`, `runPromise()`). ADR-0003 changed target syntax and zero-iteration semantics enough that the ordering rule — validate target syntax before zero-iteration skip — must be pinned down on the generator API independently of the promise API. *(Spec 9.1, 9.5, 4.1)*
- **T-API-08o**: `run("ralph", { maxIterations: 0 })` with `.loopx/ralph/package.json` unreadable (e.g., mode 000) → generator completes with no yields and no `package.json` warning on stderr. This extends T-API-08b (unsatisfied range via `runPromise`) and T-API-08g (invalid semver via `run()`) to the unreadable-file failure path — completing coverage of all three distinct `package.json` failure branches in SPEC 3.2 under `maxIterations: 0`. Mirrors CLI behavior (T-CLI-119e). **Conditional on `process.getuid() !== 0`.** *(Spec 9.1, 9.5, 3.2)*
- **T-API-08p**: `run("ralph", { maxIterations: 0, envFile: "unreadable.env" })` where `unreadable.env` exists but is unreadable (e.g., mode 000) → generator throws on first `next()`. Env file readability validation fires even with `maxIterations: 0`, mirroring CLI `-n 0` behavior (T-CLI-22f). This completes the local `envFile` failure coverage under `maxIterations: 0`: T-API-08e covers missing, T-API-08k covers malformed, and this test covers unreadable. **Conditional on `process.getuid() !== 0`.** *(Spec 9.1, 9.5, 4.2, 8.2)*
- **T-API-08p2**: `runPromise("ralph", { maxIterations: 0, envFile: "unreadable.env" })` where `unreadable.env` exists but is unreadable (e.g., mode 000) → rejects. This is the `runPromise` twin of T-API-08p, providing generator/promise symmetry for the unreadable local env file case under `maxIterations: 0`. **Conditional on `process.getuid() !== 0`.** *(Spec 9.2, 9.5, 4.2, 8.2)*
- **T-API-08q**: `run("ralph", { maxIterations: 0 })` with `.loopx/ralph/package.json` containing invalid JSON (e.g., `{broken`) → generator completes with no yields and no `package.json` warning on stderr. This extends the `maxIterations: 0` version-check skip coverage to the invalid-JSON `package.json` failure branch, mirroring CLI `-n 0` behavior (T-CLI-119c). Together with T-API-08b (unsatisfied range), T-API-08g (invalid semver), and T-API-08o (unreadable), this completes coverage of all four distinct workflow `package.json` failure modes under `maxIterations: 0`. *(Spec 9.1, 9.5, 3.2)*
- **T-API-08r**: `run("ralph:check", { maxIterations: 0 })` where `.loopx/ralph/check.sh` exists and `.loopx/ralph/index.*` does not → generator completes with no yields. A workflow without an `index` script is still valid when targeting an explicit script — `maxIterations: 0` validates that the explicit target exists and passes validation. This is the positive counterpart to T-API-08c (bare target without index → throws). Mirrors CLI behavior (T-CLI-119g). *(Spec 9.1, 9.5, 4.1)*
- **T-API-08s**: Normal-execution version mismatch warning via `run()`. Set up `.loopx/ralph/index.sh` (outputs `{"result":"ok"}`) with `.loopx/ralph/package.json` declaring a loopx version range NOT satisfied by the running version (e.g., `"loopx": ">=999.0.0"` in `dependencies`). Call `run("ralph", { maxIterations: 1 })` and iterate to completion. Assert: (a) generator yields one output with `result: "ok"` (execution succeeds despite mismatch), and (b) stderr contains a version mismatch warning for `ralph`. This is the normal-execution counterpart to T-API-08b (which verifies the warning is *skipped* under `maxIterations: 0`); CLI coverage exists (T-VER-02), but the programmatic API is a separate surface where ADR-0003's runtime version-warning behavior must also hold. *(Spec 9.1, 3.2)*
- **T-API-08t**: Cross-workflow first-entry version warning via `run()`. Set up two workflows: `.loopx/alpha/index.sh` (no `package.json`, outputs `{"goto":"beta:index"}`) and `.loopx/beta/index.sh` (with `package.json` declaring an unsatisfied loopx range, outputs `{"stop":true}`). Call `run("alpha")` and iterate to completion. Assert: (a) two outputs are yielded (alpha's goto, then beta's stop), (b) stderr contains exactly one version mismatch warning for `beta` (emitted on first entry via goto), and (c) no version warning for `alpha`. This is the API counterpart to T-VER-04 (CLI). *(Spec 9.1, 3.2)*
- **T-API-08t2**: Cross-workflow first-entry `package.json` failure warning via `run()` — invalid JSON variant. Set up `.loopx/clean/index.sh` (no `package.json` or a valid one with no loopx declaration, outputs `{"goto":"broken:index"}`) and `.loopx/broken/index.sh` (outputs `{"stop":true}`) with `.loopx/broken/package.json` containing invalid JSON (e.g., `{broken`). Call `run("clean")` and iterate to completion. Assert: (a) two outputs are yielded (clean's goto, then broken's stop), (b) stderr contains exactly one invalid-JSON warning for `broken` (emitted on first entry via goto), (c) no warning is emitted for `clean`, and (d) execution continues normally. This is the API counterpart to CLI T-VER-07d. T-API-08u covers invalid JSON on normal (single-workflow, bare-target) execution; this test pins down the cross-workflow first-entry path on the programmatic API surface. *(Spec 9.1, 3.2, 2.2)*
- **T-API-08t3**: Cross-workflow first-entry `package.json` failure warning via `run()` — unreadable variant. Same structure as T-API-08t2, but `.loopx/broken/package.json` is set to mode 000 (unreadable) instead of containing invalid JSON. Assert: (a) two outputs are yielded, (b) stderr contains exactly one unreadable-file warning for `broken` (emitted on first entry via goto), (c) no warning for `clean`, and (d) execution continues normally. Unreadable-file counterpart to T-API-08t2; API counterpart to CLI T-VER-07e. **Conditional on `process.getuid() !== 0`.** *(Spec 9.1, 3.2, 2.2)*
- **T-API-08t4**: Cross-workflow first-entry `package.json` failure warning via `run()` — invalid semver range variant. Same structure as T-API-08t2, but `.loopx/broken/package.json` contains `{ "dependencies": { "loopx": "not-a-range!!!" } }` (valid JSON but invalid semver range) instead of invalid JSON. Assert: (a) two outputs are yielded, (b) stderr contains exactly one invalid-semver warning for `broken` (emitted on first entry via goto), (c) no warning for `clean`, and (d) execution continues normally. Invalid-semver counterpart to T-API-08t2 (invalid JSON) and T-API-08t3 (unreadable); API counterpart to CLI T-VER-07f. Together with T-API-08t2 and T-API-08t3, this completes API parity for all three cross-workflow first-entry `package.json` failure branches on the `run()` surface. *(Spec 9.1, 3.2, 2.2)*
- **T-API-08t5**: Cross-workflow first-entry version warning via `run()` for a no-index workflow entered via qualified goto. Set up `.loopx/alpha/index.sh` (no `package.json`, outputs `{"goto":"beta:check"}`) and `.loopx/beta/check.sh` (no `index` script, outputs `{"stop":true}`) with `.loopx/beta/package.json` declaring an unsatisfied loopx range. Call `run("alpha")` and iterate to completion. Assert: (a) two outputs are yielded (alpha's goto, then beta's stop), (b) stderr contains exactly one version mismatch warning for `beta` (emitted on first entry via qualified goto), and (c) no version warning for `alpha`. This is the API counterpart to CLI T-VER-27. T-API-08t covers cross-workflow version mismatch into `beta:index` (index present); T-API-08z covers normal-execution version mismatch on explicit `workflow:script` entry into a no-index workflow; this test is the combination — cross-workflow goto into a no-index workflow via qualified `workflow:script` target with version mismatch. *(Spec 9.1, 3.2, 2.2, 4.1, 2.1)*
- **T-API-08t6**: Cross-workflow first-entry invalid-JSON `package.json` warning via `run()` for a no-index workflow entered via qualified goto. Set up `.loopx/alpha/index.sh` (no `package.json`, outputs `{"goto":"beta:check"}`) and `.loopx/beta/check.sh` (no `index` script, outputs `{"stop":true}`) with `.loopx/beta/package.json` containing invalid JSON (e.g., `{broken`). Call `run("alpha")` and iterate to completion. Assert: (a) two outputs are yielded (alpha's goto, then beta's stop), (b) stderr contains exactly one invalid-JSON warning for `beta` (emitted on first entry via qualified goto), (c) no warning is emitted for `alpha`, and (d) execution continues normally. T-API-08t2 covers cross-workflow goto into `broken:index` (index present) with invalid JSON; T-API-08t5 covers cross-workflow goto into a no-index workflow with version mismatch; this test is the combination — cross-workflow goto into a no-index workflow (entered via explicit `workflow:script` qualified goto) with invalid-JSON `package.json`. API counterpart to CLI T-VER-27a. *(Spec 9.1, 3.2, 2.2, 4.1, 2.1)*
- **T-API-08t7**: Cross-workflow first-entry unreadable `package.json` warning via `run()` for a no-index workflow entered via qualified goto. Same structure as T-API-08t6, but `.loopx/beta/package.json` is set to mode 000 (unreadable) instead of containing invalid JSON. Assert: (a) two outputs are yielded, (b) stderr contains exactly one unreadable-file warning for `beta` (emitted on first entry via qualified goto), (c) no warning for `alpha`, and (d) execution continues normally. Unreadable-file counterpart to T-API-08t6 (invalid JSON); T-API-08t3 covers the same `package.json` failure mode on cross-workflow goto into a workflow *with* an `index` script. API counterpart to CLI T-VER-27b. **Conditional on `process.getuid() !== 0`.** *(Spec 9.1, 3.2, 2.2, 4.1, 2.1)*
- **T-API-08t8**: Cross-workflow first-entry invalid-semver-range `package.json` warning via `run()` for a no-index workflow entered via qualified goto. Same structure as T-API-08t6, but `.loopx/beta/package.json` contains `{ "dependencies": { "loopx": "not-a-range!!!" } }` (valid JSON but invalid semver range) instead of invalid JSON. Assert: (a) two outputs are yielded, (b) stderr contains exactly one invalid-semver warning for `beta` (emitted on first entry via qualified goto), (c) no warning for `alpha`, and (d) execution continues normally. Invalid-semver counterpart to T-API-08t6 (invalid JSON) and T-API-08t7 (unreadable); T-API-08t4 covers the same failure mode on cross-workflow goto into a workflow *with* an `index` script. API counterpart to CLI T-VER-27c. Together with T-API-08t5 (unsatisfied range) and T-API-08t6/08t7 (invalid JSON/unreadable), this completes `run()` cross-workflow first-entry parity across all four `package.json` warning branches for qualified goto entry into no-index workflows. *(Spec 9.1, 3.2, 2.2, 4.1, 2.1)*
- **T-API-08u**: Broken workflow `package.json` warning on normal `run()` execution. Set up `.loopx/ralph/index.sh` (outputs `{"result":"ok"}`) with `.loopx/ralph/package.json` containing invalid JSON (e.g., `{broken`). Call `run("ralph", { maxIterations: 1 })` and iterate to completion. Assert: (a) generator yields one output with `result: "ok"` (execution succeeds despite broken `package.json`), and (b) stderr contains a `package.json` parse-failure warning. This is the normal-execution counterpart to T-API-08q (which verifies the warning is *suppressed* under `maxIterations: 0`). CLI coverage exists (T-VER-08), but the API surface requires independent verification. *(Spec 9.1, 3.2)*
- **T-API-08u2**: Starting-workflow unreadable `package.json` warning on normal `run()` execution. Set up `.loopx/ralph/index.sh` (outputs `{"result":"ok"}`) with `.loopx/ralph/package.json` set to mode 000 (unreadable). Call `run("ralph", { maxIterations: 1 })` and iterate to completion. Assert: (a) generator yields one output with `result: "ok"` (execution succeeds despite the unreadable `package.json`), and (b) stderr contains an unreadable-file warning for `ralph`. This is the unreadable-file counterpart to T-API-08u (invalid JSON) on the normal-execution path. CLI coverage exists (T-VER-07), but ADR-0003's starting-workflow `package.json` failure-warning branches must be pinned down independently on the programmatic API surface — T-API-08s covers unsatisfied range and T-API-08u covers invalid JSON, but the unreadable branch is not currently covered for `run()`. **Conditional on `process.getuid() !== 0`.** *(Spec 9.1, 3.2)*
- **T-API-08u3**: Starting-workflow invalid-semver-range `package.json` warning on normal `run()` execution. Set up `.loopx/ralph/index.sh` (outputs `{"result":"ok"}`) with `.loopx/ralph/package.json` containing `{ "dependencies": { "loopx": "not-a-range!!!" } }` (valid JSON, invalid semver range). Call `run("ralph", { maxIterations: 1 })` and iterate to completion. Assert: (a) generator yields one output with `result: "ok"` (execution succeeds despite the invalid range), and (b) stderr contains an invalid-semver warning for `ralph`. This is the invalid-semver counterpart to T-API-08u (invalid JSON) and T-API-08u2 (unreadable) on the normal-execution path. CLI coverage exists (T-VER-09), but the API surface requires independent verification. Together with T-API-08s (unsatisfied range), T-API-08u (invalid JSON), and T-API-08u2 (unreadable), this completes `run()` normal-execution parity across all four starting-workflow `package.json` warning branches from SPEC 3.2. *(Spec 9.1, 3.2)*
- **T-API-08v**: `run("ralph:check", { maxIterations: 0 })` where `.loopx/ralph/check.sh` exists, `.loopx/ralph/index.*` does not, and `.loopx/ralph/package.json` declares an unsatisfied loopx range (e.g., `{ "dependencies": { "loopx": ">=999.0.0" } }`) → generator completes with no yields and no version mismatch or `package.json` warnings on stderr. Combines T-API-08r (explicit `workflow:script` target under `maxIterations: 0` in a no-index workflow) with T-API-08b (`maxIterations: 0` skips workflow version checking) — proves that the version-check skip applies to explicit `workflow:script` targets in the programmatic API, not just bare workflow targets. Mirrors CLI behavior (T-CLI-119h). *(Spec 9.1, 9.5, 3.2, 4.1)*
- **T-API-08w**: `run("ralph:check", { maxIterations: 0 })` where `.loopx/ralph/check.sh` exists, `.loopx/ralph/index.*` does not, and `.loopx/ralph/package.json` contains invalid JSON (e.g., `{broken`) → generator completes with no yields and no `package.json` warning on stderr. Extends T-API-08v (explicit target under `maxIterations: 0` with unsatisfied range) to the invalid-JSON `package.json` failure path — proving the `maxIterations: 0` version-check skip on the explicit-target path in the programmatic API covers all `package.json` failure branches, not just unsatisfied ranges. Mirrors CLI behavior (T-CLI-119i). *(Spec 9.1, 9.5, 3.2, 4.1)*
- **T-API-08x**: `run("ralph:check", { maxIterations: 0 })` where `.loopx/ralph/check.sh` exists, `.loopx/ralph/index.*` does not, and `.loopx/ralph/package.json` contains a valid JSON object with an invalid semver range for `loopx` (e.g., `"loopx": "not-a-range"` in `dependencies`) → generator completes with no yields and no `package.json` or version-related warning on stderr. Invalid-semver counterpart to T-API-08w (invalid JSON). Mirrors CLI behavior (T-CLI-119j). *(Spec 9.1, 9.5, 3.2, 4.1)*
- **T-API-08y**: `run("ralph:check", { maxIterations: 0 })` where `.loopx/ralph/check.sh` exists, `.loopx/ralph/index.*` does not, and `.loopx/ralph/package.json` is unreadable (e.g., mode 000) → generator completes with no yields and no `package.json` warning on stderr. Unreadable-file counterpart to T-API-08w and T-API-08x. Mirrors CLI behavior (T-CLI-119k). **Conditional on `process.getuid() !== 0`.** *(Spec 9.1, 9.5, 3.2, 4.1)*
- **T-API-08z**: Normal-execution version mismatch warning on explicit `workflow:script` entry into a no-index workflow via `run()`. Set up `.loopx/ralph/check.sh` (no `index` script, outputs `{"result":"ok"}`) with `.loopx/ralph/package.json` declaring a loopx version range NOT satisfied by the running version (e.g., `"loopx": ">=999.0.0"` in `dependencies`). Call `run("ralph:check", { maxIterations: 1 })` and iterate to completion. Assert: (a) generator yields one output with `result: "ok"` (execution succeeds despite the mismatch), and (b) stderr contains a version mismatch warning for `ralph`. This is the API counterpart to CLI T-VER-26. T-API-08s covers the bare-target normal-execution warning path; T-API-36a covers explicit `workflow:script` targeting of a no-index workflow (no version declaration); this test is the symmetric combination that pins down the ADR-0003 behavior that runtime version checking still fires when a workflow is entered via an explicit script target in a workflow without a default entry point. *(Spec 9.1, 3.2, 4.1, 2.1)*
- **T-API-08z2**: Normal-execution invalid-JSON `package.json` warning on explicit `workflow:script` entry into a no-index workflow via `run()`. Set up `.loopx/ralph/check.sh` (no `index` script, outputs `{"result":"ok"}`) with `.loopx/ralph/package.json` containing invalid JSON (e.g., `{broken`). Call `run("ralph:check", { maxIterations: 1 })` and iterate to completion. Assert: (a) generator yields one output with `result: "ok"` (execution succeeds despite the broken `package.json`), and (b) stderr contains an invalid-JSON warning for `ralph`. Invalid-JSON counterpart to T-API-08z (unsatisfied range) on the explicit-target-into-no-index-workflow path and the API counterpart to CLI T-VER-26a. T-API-08w covers the same `package.json` failure mode under `maxIterations: 0` (version-check skipped); this test pins down that the normal-execution warning still fires when entering via an explicit `workflow:script` target in a workflow without a default entry point. *(Spec 9.1, 3.2, 4.1, 2.1)*
- **T-API-08z3**: Normal-execution invalid-semver-range `package.json` warning on explicit `workflow:script` entry into a no-index workflow via `run()`. Same setup as T-API-08z2, but `.loopx/ralph/package.json` contains `{ "dependencies": { "loopx": "not-a-range!!!" } }` (valid JSON, invalid semver range). Assert: (a) generator yields one output with `result: "ok"`, and (b) stderr contains an invalid-semver warning for `ralph`. Invalid-semver counterpart to T-API-08z2 (invalid JSON); API counterpart to CLI T-VER-26b. T-API-08x covers the same failure mode under `maxIterations: 0`. *(Spec 9.1, 3.2, 4.1, 2.1)*
- **T-API-08z4**: Normal-execution unreadable `package.json` warning on explicit `workflow:script` entry into a no-index workflow via `run()`. Same setup as T-API-08z2, but `.loopx/ralph/package.json` is set to mode 000 (unreadable). Assert: (a) generator yields one output with `result: "ok"`, and (b) stderr contains an unreadable-file warning for `ralph`. Unreadable-file counterpart to T-API-08z2 (invalid JSON) and T-API-08z3 (invalid semver); API counterpart to CLI T-VER-26c. T-API-08y covers the same failure mode under `maxIterations: 0`. Together with T-API-08z (unsatisfied range), T-API-08z2 (invalid JSON), and T-API-08z3 (invalid semver), this completes `run()` normal-execution parity across all four `package.json` warning branches for explicit `workflow:script` entry into no-index workflows. **Conditional on `process.getuid() !== 0`.** *(Spec 9.1, 3.2, 4.1, 2.1)*
- **T-API-08aa**: First-entry-only version-warning deduplication on re-entry via `run()`. Set up `.loopx/ralph/index.sh` that outputs `{"result":"ok"}` (no `goto`, no `stop` — the loop resets to the starting target after each iteration) with `.loopx/ralph/package.json` declaring an unsatisfied loopx range (e.g., `"loopx": ">=999.0.0"` in `dependencies`). Call `run("ralph", { maxIterations: 3 })` and iterate to completion. Assert: (a) the generator yields exactly three outputs, and (b) stderr contains exactly one version mismatch warning for `ralph` — not one per iteration. CLI coverage exists (T-VER-03), but the programmatic API is a separate surface where ADR-0003's "first entry only" deduplication rule must also hold; this test pins down on the API surface that re-entering the same workflow via loop reset does not repeat the warning. *(Spec 9.1, 3.2)*
- **T-API-08ab**: Cross-workflow alternating re-entry version-warning deduplication via `run()`. Create two workflows: `.loopx/alpha/index.sh` and `.loopx/beta/index.sh`, both with `package.json` declaring an unsatisfied loopx range. Set up a multi-iteration loop where execution alternates: `alpha:index` → goto `"beta:index"` → (no goto, reset) → `alpha:index` → goto `"beta:index"` → stop. Call `run("alpha")` and iterate to completion. Assert: (a) stderr contains exactly one version mismatch warning for `alpha` and exactly one for `beta`, and (b) no duplicate warnings appear despite both workflows being entered twice. This is the API counterpart to T-VER-04a (CLI alternating dedupe). T-API-08aa covers same-workflow re-entry on the API surface; this extends the "first entry only" deduplication rule to the full A→B→A→B alternation pattern on `run()`. *(Spec 9.1, 3.2, 2.2)*

#### `run()` with Invalid `target`

`target` is a required parameter. In TypeScript, omitting it is a static type error. In JavaScript, or when the type check is bypassed, runtime-invalid `target` values are rejected lazily.

- **T-API-09**: `run(undefined as any)` returns a generator without throwing. On the first `next()`, the generator throws (invalid target). *(Spec 9.1)*
- **T-API-20h**: `run(null as any)` returns a generator without throwing. On first `next()`, throws. *(Spec 9.1)*
- **T-API-20i**: `run(42 as any)` returns a generator without throwing. On first `next()`, throws. *(Spec 9.1)*
- **T-API-30**: `run("")` (empty string target) returns a generator. Fixture contains a valid `.loopx/ralph/index.sh`. On first `next()`, throws (invalid target). Assert the error message references the invalid target format, not a missing-workflow error. *(Spec 9.1, 4.1)*
- **T-API-31**: `run(":")` (bare colon target) returns a generator. Fixture contains a valid `.loopx/ralph/index.sh`. On first `next()`, throws. Assert the error references the invalid target format. *(Spec 9.1, 4.1)*
- **T-API-32**: `run(":script")` (leading colon). Fixture contains a valid `.loopx/ralph/index.sh`. On first `next()`, throws. Assert the error references the invalid target format. *(Spec 9.1, 4.1)*
- **T-API-33**: `run("workflow:")` (trailing colon). Fixture contains a valid `.loopx/ralph/index.sh`. On first `next()`, throws. Assert the error references the invalid target format. *(Spec 9.1, 4.1)*
- **T-API-34**: `run("a:b:c")` (multiple colons). Fixture contains a valid `.loopx/ralph/index.sh`. On first `next()`, throws. Assert the error references the invalid target format. *(Spec 9.1, 4.1)*
- **T-API-35a**: `run("-bad:index")` (workflow name violates name restrictions). Fixture contains a valid `.loopx/ralph/index.sh`. On first `next()`, throws. Assert the error references the name restriction violation. *(Spec 9.1, 4.1)*
- **T-API-35b**: `run("ralph:-bad")` (script name violates name restrictions). Fixture contains a valid `.loopx/ralph/index.sh`. On first `next()`, throws. Assert the error references the name restriction violation. *(Spec 9.1, 4.1)*
- **T-API-35d**: `run("bad.name")` (bare target where the workflow name violates name restrictions). Fixture contains a valid `.loopx/ralph/index.sh`. On first `next()`, throws. Assert the error references the name restriction violation. This is the bare-name counterpart to T-API-35a (qualified target with invalid workflow name). *(Spec 9.1, 4.1)*
- **T-API-35c**: Invalid target format is rejected after discovery and global validation in the programmatic API, mirroring CLI T-CLI-114a. Create `.loopx/broken/check.sh` and `.loopx/broken/check.ts` (name collision) alongside `.loopx/valid/index.sh`. Call `run(":script")` — generator is returned (lazy). On first `next()`, the generator throws. Assert that the error mentions the name collision in `broken` — proving discovery and global validation ran before the invalid target format was rejected. *(Spec 9.1, 4.1, 5.4)*
- **T-API-35f**: Invalid target with a name-restriction violation is rejected after discovery and global validation in `run()`, mirroring CLI T-CLI-118b. Create `.loopx/broken/check.sh` and `.loopx/broken/check.ts` (name collision) alongside `.loopx/valid/index.sh`. Call `run("bad.name")` (bare target whose workflow-name portion contains `.`, violating the name restriction pattern `[a-zA-Z0-9_][a-zA-Z0-9_-]*`) — generator is returned (lazy). On first `next()`, the generator throws. Assert that the error mentions the name collision in `broken` — proving discovery and global validation ran before the invalid bare target name was rejected. T-API-35c covers the ordering proof for malformed colon-shape targets (`":script"`) in `run()`; this test covers the same ordering proof for the name-restriction invalid-target category, a distinct validation path under ADR-0003's expanded target validation rules. Per Spec 4.1/9.1, invalid targets are rejected "at the same point as a missing workflow (after discovery, or lazily on first iteration for the API)." *(Spec 9.1, 4.1, 5.4)*

#### `run()` Target Semantics

- **T-API-35**: `run("ralph")` runs `ralph:index`. *(Spec 9.1, 4.1)*
- **T-API-36**: `run("ralph:check-ready")` runs the `check-ready` script in the `ralph` workflow. *(Spec 9.1, 4.1)*
- **T-API-36a**: `run("ralph:check", { maxIterations: 1 })` where `.loopx/ralph/` exists with `check.sh` but no `index` script → generator yields the output from `check.sh`. This proves the programmatic API can target explicit scripts in workflows without an `index` entry point, complementing CLI coverage (T-CLI-110, T-DISC-19). *(Spec 9.1, 4.1, 2.1)*
- **T-API-37**: `run("ralph:index")` is equivalent to `run("ralph")`. *(Spec 9.1, 4.1)*
- **T-API-35e**: `run("check-ready")` where `.loopx/ralph/check-ready.sh` exists but no `.loopx/check-ready/` workflow. On first `next()`, throws (no matching workflow). Assert that `ralph:check-ready` was NOT executed (no marker file written). A bare `run()` target is always a workflow name — it must not resolve to a script inside another workflow. This is the API counterpart to T-CLI-111a. *(Spec 9.1, 2.2, 4.1)*

#### `run()` Snapshot & Cancellation

- **T-API-09b**: `run()` cwd snapshot timing. Create two project directories: `projectA` (with `.loopx/ralph/index.sh` that writes a marker file) and `projectB` (with no `.loopx/`). Call `process.chdir(projectA)`, then `const gen = run("ralph", { maxIterations: 1 })` (no explicit `cwd`, so it captures `process.cwd()`). Call `process.chdir(projectB)` before iterating. Call `gen.next()`. Assert: the generator yields successfully using `projectA`'s workflow (marker file written), not `projectB` — proving `process.cwd()` was captured at `run()` call time, not at first iteration. *(Spec 9.1, 9.5)*
- **T-API-09a**: Manual iterator cancellation during a pending `next()`. Assert child process terminated and generator completes. *(Spec 9.1)*
- **T-API-09c**: `run()` options snapshot — mutating `maxIterations` after call has no effect. Set up `.loopx/ralph/index.sh` that outputs `{"result": "ok"}` (no stop/goto). `const opts = { maxIterations: 2 }; const gen = run("ralph", opts); opts.maxIterations = 1;` Iterate `gen` to completion. Assert exactly 2 outputs are yielded, not 1 — proving the options object was snapshotted at call time. *(Spec 9.1)*

#### `run()` with AbortSignal

- **T-API-10**: `run("ralph", { signal })` — aborting terminates the loop, generator throws abort error. *(Spec 9.5)*
- **T-API-10a**: Aborting while child process is active terminates the child process group. *(Spec 9.5, 9.1)*
- **T-API-10b**: Pre-aborted signal → generator throws on first `next()`, no child spawned. *(Spec 9.5, 9.1)*
- **T-API-10c**: Signal aborted between iterations → next `next()` throws abort error. *(Spec 9.5, 9.1)*

#### `runPromise()`

- **T-API-11**: `runPromise("ralph", { maxIterations: 3 })` resolves with array of 3 `Output` objects. *(Spec 9.2)*
- **T-API-12**: `runPromise("ralph")` resolves when `stop: true`. *(Spec 9.2)*
- **T-API-13**: `runPromise("ralph")` rejects when script exits non-zero. *(Spec 9.3)*
- **T-API-14**: `runPromise("ralph", { maxIterations: 3, envFile: "local.env", cwd: project.dir })` resolves with correct outputs. *(Spec 9.2, 9.5)*

#### `runPromise()` Target Semantics

- **T-API-47**: `runPromise("ralph:check-ready", { maxIterations: 1 })` resolves with an array containing the Output from the `check-ready` script in the `ralph` workflow. This is the `runPromise()` counterpart to T-API-36 (`run()` with a qualified target). *(Spec 9.2, 4.1)*
- **T-API-48**: `runPromise("ralph:index", { maxIterations: 1 })` is equivalent to `runPromise("ralph", { maxIterations: 1 })` — both resolve with identical Output arrays. This is the `runPromise()` counterpart to T-API-37 (`run()` equivalence test). *(Spec 9.2, 4.1)*
- **T-API-48a**: `runPromise("check-ready")` where `.loopx/ralph/check-ready.sh` exists but no `.loopx/check-ready/` workflow → rejects. Assert that `ralph:check-ready` was NOT executed (no marker file written). This is the `runPromise()` counterpart to T-API-35e. *(Spec 9.2, 2.2, 4.1)*
- **T-API-47a**: `runPromise("ralph:check", { maxIterations: 1 })` where `.loopx/ralph/` exists with `check.sh` but no `index` script → resolves with an array containing the Output from `check.sh`. This proves `runPromise()` can target explicit scripts in workflows without an `index` entry point, complementing `run()` coverage (T-API-36a). *(Spec 9.2, 4.1, 2.1)*
- **T-API-47b**: `runPromise("ralph", { cwd: projectA, maxIterations: 1 })` — `RunOptions.cwd` sets `LOOPX_PROJECT_ROOT` from `cwd` but the script still executes with the workflow directory as cwd. Create a workflow in project A. Script writes both `process.cwd()` and `process.env.LOOPX_PROJECT_ROOT` to a marker file. Assert: (a) cwd equals the workflow directory path (`.loopx/ralph/`), not `projectA`, and (b) `LOOPX_PROJECT_ROOT` equals `projectA`. This is the `runPromise()` counterpart to T-API-07a. *(Spec 9.2, 9.5, 6.1)*

#### `runPromise()` with Invalid `target`

- **T-API-14a**: `runPromise(undefined as any)` returns a rejected promise (not synchronous throw). *(Spec 9.2)*
- **T-API-14a2**: `runPromise(null as any)` returns a rejected promise. *(Spec 9.2)*
- **T-API-14a3**: `runPromise(42 as any)` returns a rejected promise. *(Spec 9.2)*
- **T-API-38**: `runPromise("")` rejects (empty target). Fixture contains a valid `.loopx/ralph/index.sh`. Assert the rejection error references the invalid target format, not a missing-workflow error. *(Spec 9.2, 4.1)*
- **T-API-39**: `runPromise("a:b:c")` rejects (multiple colons). Fixture contains a valid `.loopx/ralph/index.sh`. Assert the rejection error references the invalid target format. *(Spec 9.2, 4.1)*
- **T-API-40**: `runPromise(":")` rejects (bare colon). Fixture contains a valid `.loopx/ralph/index.sh`. Assert the rejection error references the invalid target format. *(Spec 9.2, 4.1)*
- **T-API-41**: `runPromise(":script")` rejects (leading colon). Fixture contains a valid `.loopx/ralph/index.sh`. Assert the rejection error references the invalid target format. *(Spec 9.2, 4.1)*
- **T-API-42**: `runPromise("workflow:")` rejects (trailing colon). Fixture contains a valid `.loopx/ralph/index.sh`. Assert the rejection error references the invalid target format. *(Spec 9.2, 4.1)*
- **T-API-43**: `runPromise("-bad:index")` rejects (workflow name violates name restrictions). Fixture contains a valid `.loopx/ralph/index.sh`. Assert the rejection error references the name restriction violation. *(Spec 9.2, 4.1)*
- **T-API-44**: `runPromise("ralph:-bad")` rejects (script name violates name restrictions). Fixture contains a valid `.loopx/ralph/index.sh`. Assert the rejection error references the name restriction violation. *(Spec 9.2, 4.1)*
- **T-API-44a**: `runPromise("bad.name")` rejects (bare target where the workflow name violates name restrictions). Fixture contains a valid `.loopx/ralph/index.sh`. Assert the rejection error references the name restriction violation. This is the bare-name counterpart to T-API-43 (qualified target with invalid workflow name). *(Spec 9.2, 4.1)*
- **T-API-44b**: Invalid target format is rejected after discovery and global validation in `runPromise()`, mirroring CLI T-CLI-114a and `run()` generator T-API-35c. Create `.loopx/broken/check.sh` and `.loopx/broken/check.ts` (name collision) alongside `.loopx/valid/index.sh`. Call `runPromise(":script")`. Assert the promise rejects with an error that mentions the name collision in `broken` — proving discovery and global validation ran before the malformed target string was rejected. Per Spec 4.1/9.2, invalid targets in `runPromise()` are rejected "at the same point as a missing workflow (after discovery)." *(Spec 9.2, 4.1, 5.4)*
- **T-API-44c**: Invalid target with a name-restriction violation is rejected after discovery and global validation in `runPromise()`, mirroring CLI T-CLI-118b and `run()` generator T-API-35f. Create `.loopx/broken/check.sh` and `.loopx/broken/check.ts` (name collision) alongside `.loopx/valid/index.sh`. Call `runPromise("bad.name")` (bare target whose workflow-name portion contains `.`, violating the name restriction pattern `[a-zA-Z0-9_][a-zA-Z0-9_-]*`). Assert the promise rejects with an error that mentions the name collision in `broken` — proving discovery and global validation ran before the invalid bare target name was rejected. T-API-44b covers the ordering proof for malformed colon-shape targets (`":script"`) in `runPromise()`; this test covers the same ordering proof for the name-restriction invalid-target category, a distinct validation path under ADR-0003's expanded target validation rules. Per Spec 4.1/9.2, invalid targets in `runPromise()` are rejected "at the same point as a missing workflow (after discovery)." *(Spec 9.2, 4.1, 5.4)*
- **T-API-45**: `runPromise("ralph")` where workflow `ralph` exists but has no `index` script → rejects (missing default entry point). *(Spec 9.2, 4.1)*
- **T-API-45a**: `runPromise("ralph:index")` where workflow `ralph` exists but has no `index` script → rejects (missing script `index` in workflow `ralph`). The workflow has other scripts (e.g., `check.sh`) but no `index.*`. The explicit `:index` target follows the ordinary missing-script rule rather than the bare default-entry-point rule. T-API-45 covers the bare `runPromise("ralph")` case (missing-default-entry path); T-API-46 covers a generic missing script (`runPromise("ralph:missing")`); this test pins down the explicit `runPromise("ralph:index")` case. This is the `runPromise()` counterpart to T-API-20j2 and T-CLI-109a, ensuring the promise-based surface enforces the same explicit-`:index` missing rule as the CLI and `run()` generator surfaces. *(Spec 9.2, 4.1)*
- **T-API-46**: `runPromise("ralph:missing")` where workflow `ralph` exists but script `missing` does not → rejects. *(Spec 9.2, 4.1)*

#### `runPromise()` Snapshot & Options

- **T-API-14b**: `runPromise("ralph", { maxIterations: 0 })` resolves with empty array `[]`. *(Spec 9.2, 9.5)*
- **T-API-14b2**: `runPromise("ralph", { maxIterations: 0 })` skips workflow-level version checking when the workflow's `package.json` contains invalid JSON. Set up `.loopx/ralph/index.sh` and `.loopx/ralph/package.json` containing `{broken`. Assert: (a) resolves with `[]`, and (b) no `package.json` or version-related warning on stderr. This is the `runPromise` bare-target counterpart to T-API-08q (`run()` bare zero-iter invalid JSON), extending T-API-08b (runPromise bare zero-iter unsatisfied range) to the invalid-JSON `package.json` failure branch. Mirrors CLI behavior (T-CLI-119c). *(Spec 9.2, 9.5, 3.2)*
- **T-API-14b3**: `runPromise("ralph", { maxIterations: 0 })` skips workflow-level version checking when the workflow's `package.json` is unreadable (mode 000). Set up `.loopx/ralph/index.sh` and `.loopx/ralph/package.json` at mode 000. Assert: (a) resolves with `[]`, and (b) no `package.json` warning on stderr. This is the `runPromise` bare-target counterpart to T-API-08o (`run()` bare zero-iter unreadable), extending T-API-08b (runPromise bare zero-iter unsatisfied range) to the unreadable-file failure branch. Mirrors CLI behavior (T-CLI-119e). **Conditional on `process.getuid() !== 0`.** *(Spec 9.2, 9.5, 3.2)*
- **T-API-14b4**: `runPromise("ralph", { maxIterations: 0 })` skips workflow-level version checking when the workflow's `package.json` contains a valid JSON object with an invalid semver range for `loopx` (e.g., `"loopx": "not-a-range"` in `dependencies`). Set up `.loopx/ralph/index.sh` and `.loopx/ralph/package.json` accordingly. Assert: (a) resolves with `[]`, and (b) no `package.json` or version-related warning on stderr. This is the `runPromise` bare-target counterpart to T-API-08g (`run()` bare zero-iter invalid semver). Mirrors CLI behavior (T-CLI-119f). Together with T-API-08b (unsatisfied range), T-API-14b2 (invalid JSON), and T-API-14b3 (unreadable), this completes `runPromise()` bare-target `maxIterations: 0` version-check-skip parity across all four `package.json` failure modes from SPEC 3.2 — pinning down on the promise surface what `run()` already covers via T-API-08b/08g/08o/08q. *(Spec 9.2, 9.5, 3.2)*
- **T-API-14c**: `runPromise()` cwd snapshot timing. Create two project directories: `projectA` (with `.loopx/ralph/index.sh` that writes a marker file) and `projectB` (with no `.loopx/`). Call `process.chdir(projectA)`, then `const p = runPromise("ralph", { maxIterations: 1 })`. Call `process.chdir(projectB)` before awaiting. Assert: the promise resolves successfully using `projectA`'s workflow — proving `process.cwd()` was captured at `runPromise()` call time. This is the `runPromise()` counterpart to T-API-09b. *(Spec 9.2, 9.5)*
- **T-API-14d**: `runPromise()` options snapshot — mutating has no effect. Set up `.loopx/ralph/index.sh` that outputs `{"result": "ok"}` (no stop/goto). `const opts = { maxIterations: 2 }; const p = runPromise("ralph", opts); opts.maxIterations = 1;` Await `p`. Assert the resolved array has exactly 2 elements, not 1 — proving the options object was snapshotted at call time. This is the `runPromise()` counterpart to T-API-09c. *(Spec 9.2, 9.1)*
- **T-API-14e**: `runPromise("nonexistent", { maxIterations: 0 })` rejects. *(Spec 9.2, 9.5, 7.1)*
- **T-API-14f**: `runPromise("ralph", { maxIterations: 0 })` where `ralph` exists but has no `index` script → rejects. Target resolution validates the default entry point even with `maxIterations: 0`. *(Spec 9.2, 9.5, 4.1)*
- **T-API-14g**: `runPromise("ralph:missing", { maxIterations: 0 })` where `ralph` exists but script `missing` does not → rejects. *(Spec 9.2, 9.5, 4.1)*
- **T-API-14h**: `runPromise("ralph:check", { maxIterations: 0 })` where `.loopx/ralph/check.sh` exists and `.loopx/ralph/index.*` does not → resolves with empty array `[]`. This is the `runPromise` counterpart to T-API-08r. *(Spec 9.2, 9.5, 4.1)*
- **T-API-14i**: Normal-execution version mismatch warning via `runPromise()`. Same setup as T-API-08s: `.loopx/ralph/index.sh` outputs `{"result":"ok"}`, `package.json` declares an unsatisfied loopx range. Call `runPromise("ralph", { maxIterations: 1 })`. Assert: (a) resolves with one output with `result: "ok"`, and (b) stderr contains a version mismatch warning for `ralph`. This is the `runPromise` counterpart to T-API-08s. *(Spec 9.2, 3.2)*
- **T-API-14j**: Cross-workflow first-entry version warning via `runPromise()`. Same setup as T-API-08t: `.loopx/alpha/index.sh` (no `package.json`, gotos `beta:index`), `.loopx/beta/index.sh` (unsatisfied loopx range, stops). Call `runPromise("alpha")`. Assert: (a) resolves with two outputs, (b) stderr contains exactly one version mismatch warning for `beta`, and (c) no version warning for `alpha`. This is the `runPromise` counterpart to T-API-08t. *(Spec 9.2, 3.2)*
- **T-API-14j2**: Cross-workflow first-entry `package.json` failure warning via `runPromise()` — invalid JSON variant. Same setup as T-API-08t2: `.loopx/clean/index.sh` (no `package.json`, gotos `broken:index`) and `.loopx/broken/index.sh` (stops) with `.loopx/broken/package.json` containing invalid JSON. Call `runPromise("clean")`. Assert: (a) resolves with two outputs, (b) stderr contains exactly one invalid-JSON warning for `broken`, (c) no warning for `clean`, and (d) the promise resolves rather than rejecting (warning is non-fatal). This is the `runPromise` counterpart to T-API-08t2 and the API counterpart to CLI T-VER-07d. *(Spec 9.2, 3.2, 2.2)*
- **T-API-14j3**: Cross-workflow first-entry `package.json` failure warning via `runPromise()` — unreadable variant. Same setup as T-API-08t3: `.loopx/broken/package.json` is mode 000. Assert: (a) resolves with two outputs, (b) stderr contains exactly one unreadable-file warning for `broken`, (c) no warning for `clean`, and (d) the promise resolves (non-fatal). This is the `runPromise` counterpart to T-API-08t3 and the API counterpart to CLI T-VER-07e. **Conditional on `process.getuid() !== 0`.** *(Spec 9.2, 3.2, 2.2)*
- **T-API-14j4**: Cross-workflow first-entry `package.json` failure warning via `runPromise()` — invalid semver range variant. Same setup as T-API-08t4: `.loopx/broken/package.json` contains `{ "dependencies": { "loopx": "not-a-range!!!" } }`. Assert: (a) resolves with two outputs, (b) stderr contains exactly one invalid-semver warning for `broken`, (c) no warning for `clean`, and (d) the promise resolves (non-fatal). This is the `runPromise` counterpart to T-API-08t4 and the API counterpart to CLI T-VER-07f. Together with T-API-14j2 and T-API-14j3, this completes API parity for all three cross-workflow first-entry `package.json` failure branches on the `runPromise()` surface. *(Spec 9.2, 3.2, 2.2)*
- **T-API-14j5**: Cross-workflow first-entry version warning via `runPromise()` for a no-index workflow entered via qualified goto. Same setup as T-API-08t5: `.loopx/alpha/index.sh` (no `package.json`, gotos `beta:check`), `.loopx/beta/check.sh` (no `index` script, stops) with `.loopx/beta/package.json` declaring an unsatisfied loopx range. Call `runPromise("alpha")`. Assert: (a) resolves with two outputs, (b) stderr contains exactly one version mismatch warning for `beta`, and (c) no version warning for `alpha`. This is the `runPromise` counterpart to T-API-08t5 and the API counterpart to CLI T-VER-27, completing the no-index cross-workflow first-entry version-warning parity across the CLI, `run()`, and `runPromise()` surfaces. *(Spec 9.2, 3.2, 2.2, 4.1, 2.1)*
- **T-API-14j6**: Cross-workflow first-entry invalid-JSON `package.json` warning via `runPromise()` for a no-index workflow entered via qualified goto. Same setup as T-API-08t6: `.loopx/alpha/index.sh` (no `package.json`, gotos `beta:check`), `.loopx/beta/check.sh` (no `index` script, stops) with `.loopx/beta/package.json` containing invalid JSON (e.g., `{broken`). Call `runPromise("alpha")`. Assert: (a) resolves with two outputs, (b) stderr contains exactly one invalid-JSON warning for `beta`, (c) no warning for `alpha`, and (d) the promise resolves rather than rejecting (warning is non-fatal). This is the `runPromise` counterpart to T-API-08t6 and the API counterpart to CLI T-VER-27a. *(Spec 9.2, 3.2, 2.2, 4.1, 2.1)*
- **T-API-14j7**: Cross-workflow first-entry unreadable `package.json` warning via `runPromise()` for a no-index workflow entered via qualified goto. Same setup as T-API-08t7: `.loopx/beta/package.json` is mode 000. Assert: (a) resolves with two outputs, (b) stderr contains exactly one unreadable-file warning for `beta`, (c) no warning for `alpha`, and (d) the promise resolves (non-fatal). This is the `runPromise` counterpart to T-API-08t7 and the API counterpart to CLI T-VER-27b. **Conditional on `process.getuid() !== 0`.** *(Spec 9.2, 3.2, 2.2, 4.1, 2.1)*
- **T-API-14j8**: Cross-workflow first-entry invalid-semver-range `package.json` warning via `runPromise()` for a no-index workflow entered via qualified goto. Same setup as T-API-08t8: `.loopx/beta/package.json` contains `{ "dependencies": { "loopx": "not-a-range!!!" } }`. Assert: (a) resolves with two outputs, (b) stderr contains exactly one invalid-semver warning for `beta`, (c) no warning for `alpha`, and (d) the promise resolves (non-fatal). This is the `runPromise` counterpart to T-API-08t8 and the API counterpart to CLI T-VER-27c. Together with T-API-14j5 (unsatisfied range), T-API-14j6 (invalid JSON), and T-API-14j7 (unreadable), this completes `runPromise()` cross-workflow first-entry parity across all four `package.json` warning branches for qualified goto entry into no-index workflows. *(Spec 9.2, 3.2, 2.2, 4.1, 2.1)*
- **T-API-14k**: Broken workflow `package.json` warning on normal `runPromise()` execution. Same setup as T-API-08u: `.loopx/ralph/index.sh` outputs `{"result":"ok"}`, `package.json` contains invalid JSON. Call `runPromise("ralph", { maxIterations: 1 })`. Assert: (a) resolves with one output with `result: "ok"`, and (b) stderr contains a `package.json` parse-failure warning. This is the `runPromise` counterpart to T-API-08u. *(Spec 9.2, 3.2)*
- **T-API-14k2**: Starting-workflow unreadable `package.json` warning on normal `runPromise()` execution. Same setup as T-API-08u2: `.loopx/ralph/index.sh` outputs `{"result":"ok"}`, `.loopx/ralph/package.json` is mode 000 (unreadable). Call `runPromise("ralph", { maxIterations: 1 })`. Assert: (a) resolves with one output with `result: "ok"`, and (b) stderr contains an unreadable-file warning for `ralph`. This is the `runPromise` counterpart to T-API-08u2, completing starting-workflow `package.json` failure-warning parity across the `run()`/`runPromise()` surfaces for the unreadable branch. **Conditional on `process.getuid() !== 0`.** *(Spec 9.2, 3.2)*
- **T-API-14k3**: Starting-workflow invalid-semver-range `package.json` warning on normal `runPromise()` execution. Same setup as T-API-08u3: `.loopx/ralph/index.sh` outputs `{"result":"ok"}`, `.loopx/ralph/package.json` contains `{ "dependencies": { "loopx": "not-a-range!!!" } }`. Call `runPromise("ralph", { maxIterations: 1 })`. Assert: (a) resolves with one output with `result: "ok"`, and (b) stderr contains an invalid-semver warning for `ralph`. This is the `runPromise` counterpart to T-API-08u3. Together with T-API-14i (unsatisfied range), T-API-14k (invalid JSON), and T-API-14k2 (unreadable), this completes `runPromise()` normal-execution parity across all four starting-workflow `package.json` warning branches from SPEC 3.2. *(Spec 9.2, 3.2)*
- **T-API-14l**: `runPromise("ralph:check", { maxIterations: 0 })` where `.loopx/ralph/check.sh` exists, `.loopx/ralph/index.*` does not, and `.loopx/ralph/package.json` declares an unsatisfied loopx range (e.g., `{ "dependencies": { "loopx": ">=999.0.0" } }`) → resolves with empty array `[]` and no version mismatch or `package.json` warnings on stderr. This is the `runPromise` counterpart to T-API-08v, combining T-API-14h (explicit `workflow:script` target under `maxIterations: 0` in a no-index workflow) with the zero-iteration version-check skip. Ensures the `runPromise` surface shares the same "explicit target still skips version checking under zero-iteration" behavior as the generator. *(Spec 9.2, 9.5, 3.2, 4.1)*
- **T-API-14m**: `runPromise("ralph:check", { maxIterations: 0 })` where `.loopx/ralph/check.sh` exists, `.loopx/ralph/index.*` does not, and `.loopx/ralph/package.json` contains invalid JSON (e.g., `{broken`) → resolves with `[]` and no `package.json` warning on stderr. This is the `runPromise` counterpart to T-API-08w, extending T-API-14l (unsatisfied range) to the invalid-JSON `package.json` failure path. Mirrors CLI behavior (T-CLI-119i). *(Spec 9.2, 9.5, 3.2, 4.1)*
- **T-API-14n**: `runPromise("ralph:check", { maxIterations: 0 })` where `.loopx/ralph/check.sh` exists, `.loopx/ralph/index.*` does not, and `.loopx/ralph/package.json` contains a valid JSON object with an invalid semver range for `loopx` (e.g., `"loopx": "not-a-range"` in `dependencies`) → resolves with `[]` and no `package.json` or version-related warning on stderr. This is the `runPromise` counterpart to T-API-08x. Mirrors CLI behavior (T-CLI-119j). *(Spec 9.2, 9.5, 3.2, 4.1)*
- **T-API-14o**: `runPromise("ralph:check", { maxIterations: 0 })` where `.loopx/ralph/check.sh` exists, `.loopx/ralph/index.*` does not, and `.loopx/ralph/package.json` is unreadable (e.g., mode 000) → resolves with `[]` and no `package.json` warning on stderr. This is the `runPromise` counterpart to T-API-08y. Mirrors CLI behavior (T-CLI-119k). **Conditional on `process.getuid() !== 0`.** *(Spec 9.2, 9.5, 3.2, 4.1)*
- **T-API-14p**: Normal-execution version mismatch warning on explicit `workflow:script` entry into a no-index workflow via `runPromise()`. Same setup as T-API-08z: `.loopx/ralph/check.sh` (no `index` script, outputs `{"result":"ok"}`) with `.loopx/ralph/package.json` declaring an unsatisfied loopx range. Call `runPromise("ralph:check", { maxIterations: 1 })`. Assert: (a) resolves with one output with `result: "ok"`, and (b) stderr contains a version mismatch warning for `ralph`. This is the `runPromise` counterpart to T-API-08z and the API counterpart to CLI T-VER-26, completing the normal-execution version-warning parity for explicit `workflow:script` entry into no-index workflows across the CLI, `run()`, and `runPromise()` surfaces. *(Spec 9.2, 3.2, 4.1, 2.1)*
- **T-API-14p2**: Normal-execution invalid-JSON `package.json` warning on explicit `workflow:script` entry into a no-index workflow via `runPromise()`. Same setup as T-API-08z2: `.loopx/ralph/check.sh` (no `index` script, outputs `{"result":"ok"}`) with `.loopx/ralph/package.json` containing invalid JSON (e.g., `{broken`). Call `runPromise("ralph:check", { maxIterations: 1 })`. Assert: (a) resolves with one output with `result: "ok"`, and (b) stderr contains an invalid-JSON warning for `ralph`. This is the `runPromise` counterpart to T-API-08z2 and the API counterpart to CLI T-VER-26a. T-API-14m covers the same failure mode under `maxIterations: 0`. *(Spec 9.2, 3.2, 4.1, 2.1)*
- **T-API-14p3**: Normal-execution invalid-semver-range `package.json` warning on explicit `workflow:script` entry into a no-index workflow via `runPromise()`. Same setup as T-API-08z3: `.loopx/ralph/check.sh` (no `index` script, outputs `{"result":"ok"}`) with `.loopx/ralph/package.json` containing `{ "dependencies": { "loopx": "not-a-range!!!" } }`. Call `runPromise("ralph:check", { maxIterations: 1 })`. Assert: (a) resolves with one output with `result: "ok"`, and (b) stderr contains an invalid-semver warning for `ralph`. This is the `runPromise` counterpart to T-API-08z3 and the API counterpart to CLI T-VER-26b. T-API-14n covers the same failure mode under `maxIterations: 0`. *(Spec 9.2, 3.2, 4.1, 2.1)*
- **T-API-14p4**: Normal-execution unreadable `package.json` warning on explicit `workflow:script` entry into a no-index workflow via `runPromise()`. Same setup as T-API-08z4: `.loopx/ralph/check.sh` (no `index` script, outputs `{"result":"ok"}`) with `.loopx/ralph/package.json` at mode 000 (unreadable). Call `runPromise("ralph:check", { maxIterations: 1 })`. Assert: (a) resolves with one output with `result: "ok"`, and (b) stderr contains an unreadable-file warning for `ralph`. This is the `runPromise` counterpart to T-API-08z4 and the API counterpart to CLI T-VER-26c. T-API-14o covers the same failure mode under `maxIterations: 0`. Together with T-API-14p (unsatisfied range), T-API-14p2 (invalid JSON), and T-API-14p3 (invalid semver), this completes `runPromise()` normal-execution parity across all four `package.json` warning branches for explicit `workflow:script` entry into no-index workflows. **Conditional on `process.getuid() !== 0`.** *(Spec 9.2, 3.2, 4.1, 2.1)*
- **T-API-14q**: First-entry-only version-warning deduplication on re-entry via `runPromise()`. Same setup as T-API-08aa: `.loopx/ralph/index.sh` outputs `{"result":"ok"}` (no `goto`, no `stop` — the loop resets to the starting target after each iteration), `.loopx/ralph/package.json` declares an unsatisfied loopx range. Call `runPromise("ralph", { maxIterations: 3 })`. Assert: (a) resolves with exactly three outputs, and (b) stderr contains exactly one version mismatch warning for `ralph` — not one per iteration. This is the `runPromise` counterpart to T-API-08aa, ensuring ADR-0003's "first entry only" deduplication rule holds identically on the promise-based API surface. *(Spec 9.2, 3.2)*
- **T-API-14r**: Cross-workflow alternating re-entry version-warning deduplication via `runPromise()`. Same setup as T-API-08ab: two workflows `.loopx/alpha/index.sh` and `.loopx/beta/index.sh`, both with `package.json` declaring an unsatisfied loopx range, and a multi-iteration loop that alternates `alpha:index` → goto `"beta:index"` → (no goto, reset) → `alpha:index` → goto `"beta:index"` → stop. Call `runPromise("alpha")`. Assert: (a) the promise resolves with the expected outputs, (b) stderr contains exactly one version mismatch warning for `alpha` and exactly one for `beta`, and (c) no duplicate warnings appear despite both workflows being entered twice. This is the `runPromise` counterpart to T-API-08ab and the API counterpart to T-VER-04a (CLI), ensuring the alternating cross-workflow "first entry only" deduplication rule holds identically on the promise-based surface. *(Spec 9.2, 3.2, 2.2)*

#### Error Behavior

- **T-API-15**: Programmatic API never prints `result` to stdout. *(Spec 9.3)*
- **T-API-16**: Non-zero script exit causes `run()` generator to throw. *(Spec 9.3)*
- **T-API-17**: Invalid goto target causes `run()` generator to throw. *(Spec 9.3)*
- **T-API-18**: Script stderr is forwarded to the calling process's stderr. *(Spec 9.3)*
- **T-API-19**: When `run()` throws, previously yielded outputs are preserved. *(Spec 9.3)*
- **T-API-20a**: `run("nonexistent")` → generator throws on first `next()`. *(Spec 9.1, 9.3)*
- **T-API-20b**: `runPromise("nonexistent")` → rejects. *(Spec 9.3)*
- **T-API-20c**: `run("ralph")` with name collision in `.loopx/` → generator throws on first `next()`. *(Spec 9.1, 9.3)*
- **T-API-20d**: `run("ralph", { envFile: "nonexistent.env" })` → generator throws on first `next()`. *(Spec 9.1, 9.3, 9.5)*
- **T-API-20e**: `runPromise("ralph", { envFile: "nonexistent.env" })` → rejects. *(Spec 9.3, 9.5)*
- **T-API-20f**: `run("ralph", { cwd: dirWithoutLoopx })` → generator throws on first `next()`. *(Spec 9.1, 9.3)*
- **T-API-20g**: `runPromise("ralph", { cwd: dirWithoutLoopx })` → rejects. *(Spec 9.3)*
- **T-API-20j**: `run("ralph")` where workflow `ralph` exists but has no `index` script → generator throws on first `next()` (missing default entry point). *(Spec 9.1, 4.1)*
- **T-API-20j2**: `run("ralph:index")` where workflow `ralph` exists but has no `index` script → generator throws on first `next()` (missing script `index` in workflow `ralph`). The workflow has other scripts (e.g., `check.sh`) but no `index.*`. The explicit `:index` target follows the ordinary missing-script rule rather than the bare default-entry-point rule — ADR-0003 makes `index` special only when the script portion of the target is omitted. T-API-20j covers the bare `run("ralph")` case (missing-default-entry path); T-API-20k covers a generic missing script (`run("ralph:missing")`); this test pins down the explicit `run("ralph:index")` case so a buggy implementation cannot special-case `:index` to fall back to a different resolution path. This is the API counterpart to T-CLI-109a. *(Spec 9.1, 4.1)*
- **T-API-20k**: `run("ralph:missing")` where workflow `ralph` exists but script `missing` does not → generator throws on first `next()`. *(Spec 9.1, 4.1)*
- **T-API-20l**: `run("good")` in normal execution with `.loopx/` containing a sibling workflow that has an invalid script name (e.g., `.loopx/good/index.sh` valid, `.loopx/broken/-bad.sh`) → generator throws on first `next()`. Global discovery validation catches the invalid script name in the sibling before execution begins. This is the normal-execution API counterpart to CLI T-DISC-47a and extends the `maxIterations: 0` coverage (T-API-08i) to non-zero iterations — T-API-20c proves the same for sibling same-base-name collisions, but sibling name-restriction violations are a distinct validation path. *(Spec 9.1, 9.3, 5.3, 5.4)*
- **T-API-20m**: `run("good")` in normal execution with `.loopx/` containing a sibling workflow whose name is invalid (e.g., `.loopx/good/index.sh` valid, `.loopx/-bad-workflow/index.sh`) → generator throws on first `next()`. Global discovery validation catches the invalid workflow name in the sibling before execution begins. This is the normal-execution API counterpart to CLI T-DISC-47b and extends the `maxIterations: 0` coverage (T-API-08j) to non-zero iterations — the workflow-name validation path is distinct from the script-name path tested in T-API-20l. *(Spec 9.1, 9.3, 5.3, 5.4)*
- **T-API-20n**: `runPromise("good")` in normal execution with `.loopx/` containing a sibling workflow that has an invalid script name (e.g., `.loopx/good/index.sh` valid, `.loopx/broken/-bad.sh`) → rejects. This is the `runPromise` counterpart to T-API-20l, ensuring the promise-based surface enforces sibling name-restriction validation identically to the generator surface in normal execution. *(Spec 9.2, 9.3, 5.3, 5.4)*
- **T-API-20o**: `runPromise("good")` in normal execution with `.loopx/` containing a sibling workflow whose name is invalid (e.g., `.loopx/good/index.sh` valid, `.loopx/-bad-workflow/index.sh`) → rejects. This is the `runPromise` counterpart to T-API-20m. *(Spec 9.2, 9.3, 5.3, 5.4)*
- **T-API-20p**: API parity for version-check ordering when the starting target cannot be entered. Create `.loopx/ralph/check.sh` (valid workflow with no `index` script) and `.loopx/ralph/package.json` declaring an unsatisfied loopx range (e.g., `{ "dependencies": { "loopx": ">=999.0.0" } }`). Call `run("ralph")` with `maxIterations: 1`. Assert: (a) the generator throws on first `next()` with an error about the missing default entry point, and (b) stderr contains no version mismatch or `package.json`-related warnings for `ralph`. Target resolution fails before workflow-entry version checking runs — the workflow is never entered, so its `package.json` is never read. This is the API counterpart to CLI T-VER-24 and completes the ADR-0003 "version check ordering before workflow entry" symmetry between the CLI and programmatic API surfaces. *(Spec 9.1, 9.3, 7.1, 3.2)*
- **T-API-20p2**: API parity for version-check ordering when the starting target cannot be entered — `runPromise()` surface, unsatisfied range variant. Same fixture as T-API-20p: `.loopx/ralph/check.sh` (valid workflow with no `index` script) and `.loopx/ralph/package.json` declaring an unsatisfied loopx range (e.g., `{ "dependencies": { "loopx": ">=999.0.0" } }`). Call `runPromise("ralph", { maxIterations: 1 })`. Assert: (a) the promise rejects with an error about the missing default entry point, and (b) stderr contains no version mismatch or `package.json`-related warnings for `ralph`. Target resolution fails before workflow-entry version checking runs — the workflow is never entered, so its `package.json` is never read. This is the `runPromise()` counterpart to T-API-20p (`run()` generator surface) and CLI T-VER-24, closing the "missing default entry point beats version/package checking" ordering parity across all three surfaces (CLI, `run()`, `runPromise()`). ADR-0003 made explicit `index`-only default-entry semantics first-class, so the ordering rule must be pinned down on every entry surface. *(Spec 9.2, 9.3, 7.1, 3.2, 4.1)*
- **T-API-20p3**: API parity for version-check ordering when the starting target cannot be entered — `runPromise()` surface, broken JSON variant. Same setup as T-API-20p2, but `.loopx/ralph/package.json` contains `{{{INVALID` (broken JSON) instead of an unsatisfied range. Call `runPromise("ralph", { maxIterations: 1 })`. Assert: (a) the promise rejects with an error about the missing default entry point, and (b) stderr contains no JSON parse or version mismatch warnings for `ralph`. Broken-JSON counterpart to T-API-20p2 (unsatisfied range) and the `runPromise()` counterpart to CLI T-VER-24a, completing coverage of both `package.json` failure modes on the promise surface for the missing-default-entry ordering rule. Together with T-API-20p (unsatisfied range on `run()`), this pins down on the programmatic API that target resolution precedes both version-range comparison and `package.json` reading — neither branch is entered when the starting target resolution fails. *(Spec 9.2, 9.3, 7.1, 3.2, 4.1)*
- **T-API-20q**: API parity for version-check ordering when a goto target script does not exist. Create `.loopx/start/index.sh` that outputs `{ "goto": "other:missing" }`, `.loopx/other/index.sh` (valid), and `.loopx/other/package.json` containing `{{{INVALID` (broken JSON). Call `runPromise("start", { maxIterations: 2 })`. Assert: (a) the promise rejects with an error about the missing script `missing` in workflow `other`, and (b) stderr contains no `package.json` parse warnings or version mismatch warnings for `other`. Goto target resolution fails before first-entry version checking runs — the target workflow is never entered, so its `package.json` is never read. This is the API counterpart to CLI T-VER-25a. *(Spec 9.2, 9.3, 7.1, 3.2)*
- **T-API-20q2**: API parity for version-check ordering when a goto target script does not exist — unsatisfied-range variant. Create `.loopx/start/index.sh` that outputs `{ "goto": "other:missing" }`, `.loopx/other/index.sh` (valid), and `.loopx/other/package.json` containing `{ "dependencies": { "loopx": ">=999.0.0" } }` (an unsatisfied range). Call `runPromise("start", { maxIterations: 2 })`. Assert: (a) the promise rejects with an error about the missing script `missing` in workflow `other`, and (b) stderr contains no version mismatch or `package.json`-related warnings for `other`. Goto target resolution fails before first-entry version checking runs — the target workflow is never entered, so its version range is never compared. T-API-20q covers the broken-JSON variant on this path and is the API counterpart to CLI T-VER-25a; this test covers the unsatisfied-range variant and is the API counterpart to CLI T-VER-25, completing goto-target-missing-script ordering parity between CLI and `runPromise()` across both `package.json` failure modes. *(Spec 9.2, 9.3, 7.1, 3.2)*
- **T-API-20r**: API parity for version-check ordering when an explicit `workflow:script` start target names a missing script — via `run()`. Create `.loopx/ralph/index.sh` (valid workflow, `index` present) and `.loopx/ralph/package.json` declaring an unsatisfied loopx range (e.g., `{ "dependencies": { "loopx": ">=999.0.0" } }`). Call `run("ralph:missing", { maxIterations: 1 })`. Assert: (a) the generator throws on first `next()` with an error about the missing script `missing` in workflow `ralph`, and (b) stderr contains no version mismatch or `package.json`-related warnings for `ralph`. Target resolution fails before workflow-entry version checking runs — the workflow is never entered, so its `package.json` is never read. This is the `run()` API counterpart to CLI T-VER-24b and extends T-API-20p (missing default entry) and T-API-20q (missing goto target) to the explicit `workflow:script` start-target case. ADR-0003 made explicit `workflow:script` start targets first-class, so the ordering rule must hold on the API surface too. *(Spec 9.1, 9.3, 7.1, 3.2, 4.1)*
- **T-API-20s**: API parity for version-check ordering when an explicit `workflow:script` start target names a missing script — via `runPromise()`, broken JSON variant. Create `.loopx/ralph/index.sh` (valid workflow, `index` present) and `.loopx/ralph/package.json` containing `{{{INVALID` (broken JSON). Call `runPromise("ralph:missing", { maxIterations: 1 })`. Assert: (a) the promise rejects with an error about the missing script `missing` in workflow `ralph`, and (b) stderr contains no JSON parse or version mismatch warnings for `ralph`. This is the `runPromise` counterpart to T-API-20r and the API counterpart to CLI T-VER-24c — covering the broken-JSON failure mode on the promise surface and completing the ADR-0003 explicit-`workflow:script`-start ordering parity between CLI, `run()`, and `runPromise()`. *(Spec 9.2, 9.3, 7.1, 3.2, 4.1)*

#### `envFile` Option

- **T-API-21**: `run("ralph", { envFile: "local.env" })` loads the env file. *(Spec 9.5)*
- **T-API-21a**: Relative envFile path resolved against provided `cwd`. *(Spec 9.5)*
- **T-API-21b**: Relative envFile path resolved against `process.cwd()` when no `cwd` option. *(Spec 9.5)*
- **T-API-21c**: Env file parse warnings forwarded to stderr via programmatic API. *(Spec 8.1, 9.3)*
- **T-API-21d**: Global env file parse warnings forwarded to stderr. *(Spec 8.1, 9.3)*

#### `maxIterations` Validation

- **T-API-22**: `run("ralph", { maxIterations: -1 })` → generator throws on first `next()`. *(Spec 9.1, 9.5)*
- **T-API-23**: `run("ralph", { maxIterations: 1.5 })` → generator throws. *(Spec 9.1, 9.5)*
- **T-API-23a**: `run("ralph", { maxIterations: NaN })` → generator throws. *(Spec 9.1, 9.5)*
- **T-API-24**: `runPromise("ralph", { maxIterations: NaN })` → rejects. *(Spec 9.5)*
- **T-API-24a**: `runPromise("ralph", { maxIterations: -1 })` → rejects. *(Spec 9.5)*
- **T-API-24b**: `runPromise("ralph", { maxIterations: 1.5 })` → rejects. *(Spec 9.5)*

#### `runPromise()` with AbortSignal

- **T-API-25**: `runPromise("ralph", { signal })` — aborting rejects with abort error. *(Spec 9.5)*
- **T-API-25a**: Pre-aborted signal → rejects immediately, no child spawned. *(Spec 9.5)*
- **T-API-25b**: Abort between iterations → rejects. *(Spec 9.5, 9.2)*

### 4.10 Install Command

**Spec refs:** 10.1–10.9

All install tests use local servers (HTTP, file:// git repos). No network access.

#### Source Detection

- **T-INST-01**: `loopx install myorg/my-workflow` is treated as a git source (github shorthand). Verify by using `withGitURLRewrite` to redirect to a local bare repo, and asserting workflows are installed into `.loopx/`. *(Spec 10.1)*
- **T-INST-01a**: `loopx install myorg/my-workflow.git` → error, exit code 1. The shorthand must not end in `.git`. *(Spec 10.1)*
- **T-INST-02**: `loopx install https://github.com/org/repo` → treated as git (known host). *(Spec 10.1)*
- **T-INST-03**: `loopx install https://gitlab.com/org/repo` → treated as git. *(Spec 10.1)*
- **T-INST-04**: `loopx install https://bitbucket.org/org/repo` → treated as git. *(Spec 10.1)*
- **T-INST-05**: `loopx install https://example.com/repo.git` → treated as git (.git suffix). *(Spec 10.1)*
- **T-INST-06**: `loopx install http://localhost:PORT/pkg.tar.gz` → treated as tarball. *(Spec 10.1)*
- **T-INST-07**: `loopx install http://localhost:PORT/pkg.tgz` → treated as tarball. *(Spec 10.1)*
- **T-INST-08**: `loopx install http://localhost:PORT/script.ts` → rejected (single-file URL install is not supported). Error, exit code 1. *(Spec 10.1)*
- **T-INST-08a**: `loopx install https://github.com/org/repo/archive/main.tar.gz` → treated as tarball (not git). *(Spec 10.1)*
- **T-INST-08c**: `loopx install https://github.com/org/repo/` → treated as git (trailing slash allowed). *(Spec 10.1)*
- **T-INST-08d**: `loopx install http://localhost:PORT/pkg.tar.gz?token=abc` → treated as tarball. *(Spec 10.1)*
- **T-INST-08e**: `loopx install http://localhost:PORT/some-file.js` → rejected. Any URL that is not git or tarball is an error. *(Spec 10.1)*
- **T-INST-08f**: `loopx install https://github.com/org/repo/tree/main` → rejected. Known-host git detection only matches exact `/<owner>/<repo>` or `/<owner>/<repo>.git` paths. A URL with additional path segments (like `/tree/main`) is not treated as a git repo. Since it is also not a tarball URL, it is rejected with an error (exit code 1). *(Spec 10.1)*

#### Install CLI Parsing

- **T-INST-40**: `loopx install` with no source → usage error, exit code 1. *(Spec 4.2, 10)*
- **T-INST-40a**: `loopx install -w ralph` with no source → usage error, exit code 1. The `-w` flag does not substitute for the required `<source>` argument. *(Spec 4.2, 10)*
- **T-INST-40b**: `loopx install --workflow ralph` with no source → usage error, exit code 1. Same as T-INST-40a using the long-form `--workflow` flag. *(Spec 4.2, 10)*
- **T-INST-40c**: `loopx install -y` with no source → usage error, exit code 1. The `-y` flag does not substitute for the required `<source>` argument. *(Spec 4.2, 10)*
- **T-INST-40d**: `loopx install <source1> <source2>` → usage error, exit code 1. The install grammar accepts exactly one positional source argument; extra positionals are rejected. *(Spec 4.2, 10)*
- **T-INST-40e**: `loopx install -w ralph <source1> <source2>` → usage error, exit code 1. Extra positionals are rejected even when combined with the `-w` flag. *(Spec 4.2, 10)*
- **T-INST-41**: `loopx install -h` → install help, exit 0. Source not required. Assert that the help text explicitly lists: (a) `-w` / `--workflow` option with description, (b) `-y` option with description, (c) supported source types (git repos, tarballs, `org/repo` shorthand), and (d) does NOT mention single-file URL install as a supported source type — single-file URL install was removed (ADR-0003) and the help text must not advertise it. *(Spec 4.2, 10.1, 11.3)*
- **T-INST-41a**: `loopx install --help` produces identical stdout, stderr, and exit code as `loopx install -h`. Run both in the same fixture. Assert: (a) stdout is byte-identical between the two invocations, (b) stderr is byte-identical, and (c) both exit 0. This proves the `--help` long form is a true alias for `-h`, consistent with the top-level and run help `--help` parity tests (T-CLI-03, T-CLI-41). *(Spec 4.2, 11.3)*
- **T-INST-42**: `loopx install -h --unknown` → install help, exit 0 (unknown flag ignored under `-h`). *(Spec 4.2)*
- **T-INST-42a**: `loopx install -h http://localhost:PORT/pkg.tar.gz` → install help, exit 0. Start a local HTTP server that tracks incoming requests. Assert: (a) help is shown, (b) the HTTP server received zero requests, and (c) `.loopx/` was not created or modified. Proves that `-h` makes no network requests even when a valid source is provided. *(Spec 4.2, 11.3)*
- **T-INST-42b**: `loopx install http://localhost:PORT/pkg.tar.gz -h` → install help, exit 0. Same assertions as T-INST-42a (zero HTTP requests, `.loopx/` untouched). Proves `-h` after the source argument also short-circuits without network activity. *(Spec 4.2, 11.3)*
- **T-INST-42c**: `loopx install -h` with `.loopx/` containing a broken workflow tree — an invalid workflow name (e.g., `.loopx/-bad-workflow/index.sh`), a name collision (e.g., `check.sh` and `check.ts` in the same workflow), and an invalid script name (e.g., `-bad.sh`) — still exits 0. Assert: (a) help text is shown, (b) stderr contains no discovery or validation warnings, and (c) exit code is 0. This proves install help does not inspect `.loopx/`, per Spec 11.3. *(Spec 4.2, 11.3)*
- **T-INST-42d**: `loopx install --help http://localhost:PORT/pkg.tar.gz` → install help, exit 0. Start a local HTTP server that tracks incoming requests. Assert: (a) help is shown, (b) the HTTP server received zero requests, and (c) `.loopx/` was not created or modified. This is the long-form counterpart to T-INST-42a. T-INST-41a proves `--help` and `-h` produce identical output, but output parity alone would not catch an implementation that fetches the source before short-circuiting — this test verifies the behavioral guarantee that `--help` makes no network requests or filesystem changes. *(Spec 4.2, 11.3)*
- **T-INST-42e**: `loopx install --help --unknown` → install help, exit 0. The long-form `--help` in leading position short-circuits, ignoring the unrecognized `--unknown` flag. This is the `--help`-first counterpart to T-INST-42 (`-h --unknown`) and T-INST-49d (`--unknown --help`). *(Spec 4.2)*
- **T-INST-42f**: `loopx install --help --workflow` → install help, exit 0. The long-form `--help` in leading position short-circuits, ignoring the `--workflow` flag (which has no operand). This is the `--help` long-form counterpart to T-INST-48 (`-h -w`). *(Spec 4.2)*
- **T-INST-42g**: `loopx install -h <source1> <source2>` → install help, exit 0. Start a local HTTP server that tracks incoming requests. Assert: (a) help is shown, (b) the HTTP server received zero requests, and (c) `.loopx/` was not created or modified. The extra positionals do not prevent the help short-circuit and no network requests are made. This is the help-side counterpart to T-INST-40d (extra positionals without `-h` → usage error). *(Spec 4.2, 11.3)*
- **T-INST-42h**: `loopx install <source1> <source2> --help` → install help, exit 0. Start a local HTTP server that tracks incoming requests. Assert: (a) help is shown, (b) the HTTP server received zero requests, and (c) `.loopx/` was not created or modified. The `--help` after multiple positionals still short-circuits. This is the trailing-help counterpart to T-INST-42g. *(Spec 4.2, 11.3)*
- **T-INST-42i**: `loopx install --help -w a -w b` → install help, exit 0. The long-form `--help` short-circuits, ignoring the duplicate `-w` flags. This is the `--help`-first counterpart to T-INST-49b (`-w a -w b -h`). *(Spec 4.2)*
- **T-INST-42j**: `loopx install --help -y -y` → install help, exit 0. The long-form `--help` short-circuits, ignoring the duplicate `-y` flags. This is the `--help`-first counterpart to T-INST-49c (`-y -y -h`). *(Spec 4.2)*
- **T-INST-42k**: `loopx install http://localhost:PORT/script.ts -h` → install help, exit 0. Start a local HTTP server that tracks incoming requests and serves a file at `/script.ts`. Assert: (a) help is shown, (b) the HTTP server received zero requests (the rejected source triggered no network activity), (c) `.loopx/` was not created or modified, and (d) stderr contains no single-file-URL-rejection error. This proves help short-circuit suppresses source classification errors — a single-file URL is normally rejected (T-INST-08) with an error under ADR-0003, but the help short-circuit must fire before source classification. T-INST-42a/42b cover help with valid sources (no network); this test covers the stronger guarantee that help also suppresses source-type validation. *(Spec 4.2, 10.1, 11.3)*
- **T-INST-42l**: `loopx install org/repo.git --help` → install help, exit 0. Assert: (a) help is shown, (b) stderr contains no error about the `.git` suffix being disallowed in the `org/repo` shorthand, and (c) `.loopx/` was not created or modified. The `org/repo.git` form is normally rejected (T-INST-01a) because the shorthand must not end in `.git`, but the `--help` short-circuit must fire before shorthand validation. This is the long-form `--help` counterpart to T-INST-42k and proves help suppresses a second distinct source classification error (invalid `org/repo` shorthand), complementing the single-file URL coverage in T-INST-42k. *(Spec 4.2, 10.1, 11.3)*
- **T-INST-43**: `loopx install -w a -w b <source>` → usage error, exit code 1 (duplicate `-w`). *(Spec 4.2)*
- **T-INST-43a**: `loopx install --workflow a --workflow b <source>` → usage error, exit code 1 (duplicate `--workflow`). *(Spec 4.2)*
- **T-INST-43b**: `loopx install -w a --workflow b <source>` → usage error, exit code 1 (duplicate workflow flag — mixed short and long forms still count as a duplicate). *(Spec 4.2)*
- **T-INST-44**: `loopx install -y -y <source>` → usage error, exit code 1 (duplicate `-y`). *(Spec 4.2)*
- **T-INST-45**: `loopx install --unknown <source>` → usage error, exit code 1 (unrecognized flag). *(Spec 4.2)*
- **T-INST-45a**: `loopx install -x <source>` → usage error, exit code 1 (unrecognized short flag). This is the install-scoped counterpart to T-CLI-72 (`loopx run -x ralph`), ensuring short flags are rejected identically to long flags. *(Spec 4.2)*
- **T-INST-46**: `loopx install -h -w a -w b` shows install help and exits 0 (duplicate `-w` not rejected under help). *(Spec 4.2)*
- **T-INST-47**: `loopx install -h -y -y` shows install help and exits 0 (duplicate `-y` not rejected under help). *(Spec 4.2)*
- **T-INST-48**: `loopx install -h -w` shows install help and exits 0 (missing `-w` operand not rejected under help). *(Spec 4.2)*
- **T-INST-49**: `loopx install -w` (no operand for `-w`, no source) exits with code 1 (usage error). *(Spec 4.2)*
- **T-INST-49e**: `loopx install --workflow` (no operand for `--workflow`, no source) exits with code 1 (usage error). This is the long-form counterpart to T-INST-49. *(Spec 4.2)*

#### Late-Help Short-Circuit (Invalid Args Before `-h`)

- **T-INST-49a**: `loopx install --unknown -h` shows install help and exits 0. The unrecognized flag before `-h` does not prevent the help short-circuit. *(Spec 4.2)*
- **T-INST-49b**: `loopx install -w a -w b -h` shows install help and exits 0. The duplicate `-w` before `-h` does not prevent the help short-circuit. *(Spec 4.2)*
- **T-INST-49c**: `loopx install -y -y -h` shows install help and exits 0. The duplicate `-y` before `-h` does not prevent the help short-circuit. *(Spec 4.2)*
- **T-INST-49d**: `loopx install --unknown --help` shows install help and exits 0. Long-form `--help` after invalid args also short-circuits. *(Spec 4.2)*
- **T-INST-49f**: `loopx install -w -h` shows install help and exits 0. A naive parser would consume `-h` as the operand for `-w`, but the `-h` short-circuit fires unconditionally when `-h` is present — all other install-level arguments are ignored. This is the missing-operand counterpart to T-INST-49a–49d (which cover invalid or duplicate flags before `-h`). *(Spec 4.2)*
- **T-INST-49g**: `loopx install --workflow --help` shows install help and exits 0. Long-form counterpart to T-INST-49f: `--workflow` would consume `--help` as its operand in naive parsing, but the help short-circuit ignores all other arguments unconditionally. *(Spec 4.2)*

#### Workflow Classification — Single-Workflow Source

- **T-INST-50**: Git repo with root-level `index.ts`, a non-script file (`package.json`), and a pure non-script root directory (`docs/` containing only `.md` files — no supported script extensions) → single-workflow source. Entire repo installed as `.loopx/<repo-name>/`. Assert the workflow directory contains all root-level files including non-script files (`package.json`) **and** non-script directories (`docs/`). This covers the ADR-0003 rule that all root files and directories are copied for single-workflow sources, including directories that contain no script-extension files. *(Spec 10.3)*
- **T-INST-50a**: Git repo with root-level `index.js` → single-workflow source. Installed as `.loopx/<repo-name>/`. This extends install-path extension coverage (T-INST-50 covers `.ts`) to positively verify that `.js` is recognized as a supported script extension in the install single-workflow classification codepath. *(Spec 10.3, 2.1)*
- **T-INST-50b**: Parameterized: single-workflow root classification for all five supported extensions. For each extension in [`.sh`, `.js`, `.jsx`, `.ts`, `.tsx`], create a git repo with a single root-level `index.<ext>` file. Run `loopx install <source>`. Assert: the source is classified as single-workflow and installed as `.loopx/<repo-name>/`. T-INST-50 covers `.ts` and T-INST-50a covers `.js` individually; this parameterized test closes the gaps for `.sh`, `.jsx`, and `.tsx` and exercises all five extensions uniformly in the single-workflow root classification codepath. *(Spec 10.3, 2.1)*
- **T-INST-51**: Git repo with root-level `index.ts` and a `lib/` subdirectory containing `.ts` files → still single-workflow (root-level script files take precedence unconditionally). `lib/` is workflow content, not a separate workflow. Assert `.loopx/<repo-name>/lib/` exists. *(Spec 10.3)*
- **T-INST-52**: Root-level script files force single-workflow classification even when subdirectories also contain scripts. Git repo with root-level `index.sh` and two subdirectories `tools/` and `helpers/` that each contain their own top-level script files (e.g., `tools/build.sh`, `helpers/setup.ts`) — subdirectories that would themselves qualify as workflows in a multi-workflow source. `loopx install <source>` → single-workflow install. Assert: (a) `.loopx/<repo-name>/` is created (single workflow, named after the repo), (b) `.loopx/<repo-name>/tools/build.sh` and `.loopx/<repo-name>/helpers/setup.ts` exist (subdirectories are copied inside the workflow as content), (c) `.loopx/tools/` and `.loopx/helpers/` do **not** exist (the subdirectories are NOT installed as sibling workflows). This pins down the ADR-0003 "root-level script files take precedence unconditionally" rule — the presence of `index.sh` at the root forces single-workflow classification, and the would-be-workflow subdirectories are treated as workflow internals. *(Spec 10.3)*
- **T-INST-52a**: Root-level "config-style" file with a supported extension (e.g., `eslint.config.js` or `vitest.config.ts`) at the repository root forces single-workflow classification, even when subdirectories also qualify as workflows (contain their own top-level script files). The config file is a root-level file with a supported script extension, so it triggers the single-workflow rule unconditionally. Additionally, the config file is a top-level script candidate whose base name (e.g., `eslint.config`) contains a dot — violating the script naming restriction `[a-zA-Z0-9_][a-zA-Z0-9_-]*`. Assert that install classifies the source as single-workflow AND fails with a validation error about the invalid script name. The sibling subdirectories are not treated as separate workflows. *(Spec 10.3, 10.4)*
- **T-INST-52c**: Root-level non-index script file forces single-workflow classification even when subdirectories qualify as workflows. Git repo with root-level `setup.ts` (but no `index.*` file) and two subdirectories `ralph/` and `other/` that each contain their own top-level script files (e.g., `ralph/index.sh`, `other/index.sh`) — subdirectories that would qualify as workflows in a multi-workflow source. `loopx install <source>` → single-workflow install. Assert: (a) `.loopx/<repo-name>/` is created (single workflow, named after the repo), (b) `.loopx/<repo-name>/setup.ts`, `.loopx/<repo-name>/ralph/index.sh`, and `.loopx/<repo-name>/other/index.sh` exist (subdirectories are copied as workflow content), (c) `.loopx/ralph/` and `.loopx/other/` do **not** exist (the subdirectories are NOT installed as sibling workflows), and (d) no error about missing `index` — a missing default entry point is allowed at install time. T-INST-52 uses `index.sh` at the root and T-INST-52a uses a root-level file with an invalid name; this pins down that **any** valid root-level script file — not just one named `index` — forces single-workflow classification independently of the default entry point convention. *(Spec 10.3, 10.4)*
- **T-INST-52d**: Root-level "config-style" file with a supported extension in a tarball source forces single-workflow classification, same as for git sources. Create a `.tar.gz` whose source root (after any wrapper-directory stripping) contains `eslint.config.js` at the root level, plus subdirectories that would themselves qualify as workflows (e.g., `ralph/index.sh` and `other/index.sh`). `loopx install <tarball-url>` → the source is classified as single-workflow (the root-level `.js` file triggers the rule unconditionally), and install fails with a validation error about the invalid script name (`eslint.config` contains a dot that violates the naming restriction `[a-zA-Z0-9_][a-zA-Z0-9_-]*`). Assert: (a) exit code 1, (b) the error references the invalid script name, (c) `.loopx/ralph/` and `.loopx/other/` do NOT exist (sibling subdirectories were not installed as separate workflows). This is the tarball counterpart to T-INST-52a (git). Per SPEC 10.2, classification after extraction is source-type-agnostic, so the "root-level supported-extension config file forces single-workflow classification" rule must hold for both source types. *(Spec 10.2, 10.3, 10.4)*

#### Workflow Classification — Multi-Workflow Source

- **T-INST-53**: Git repo with no root-level script files but two subdirectories `ralph/` and `other/` each containing an `index.sh` → multi-workflow source. Both installed as `.loopx/ralph/` and `.loopx/other/`. *(Spec 10.3)*
- **T-INST-53a**: Multi-workflow git repo where one subdirectory qualifies via `index.jsx`. Source contains `ralph/index.sh` and `other/index.jsx`, with no root-level script files → both installed as `.loopx/ralph/` and `.loopx/other/`. This extends install-path extension coverage (T-INST-53 covers `.sh`) to positively verify that `.jsx` is recognized in the install multi-workflow classification codepath. *(Spec 10.3, 2.1)*
- **T-INST-53b**: Multi-workflow git repo where one subdirectory qualifies via `index.tsx`. Source contains `ralph/index.sh` and `other/index.tsx`, with no root-level script files → both installed as `.loopx/ralph/` and `.loopx/other/`. This extends install-path extension coverage to positively verify that `.tsx` is recognized in the install multi-workflow classification codepath. *(Spec 10.3, 2.1)*
- **T-INST-53c**: Parameterized: multi-workflow subdirectory classification for all five supported extensions. For each extension in [`.sh`, `.js`, `.jsx`, `.ts`, `.tsx`], create a multi-workflow git repo where one subdirectory (`target/`) qualifies via a single `index.<ext>` file, alongside another valid workflow `other/index.sh`, with no root-level script files. Run `loopx install <source>`. Assert: both `target` and `other` are installed. T-INST-53 covers `.sh`, T-INST-53a covers `.jsx`, and T-INST-53b covers `.tsx` individually; this parameterized test closes the gaps for `.js` and `.ts` and exercises all five extensions uniformly in the multi-workflow subdirectory classification codepath. *(Spec 10.3, 2.1)*
- **T-INST-54**: Multi-workflow repo: repo-root support files (README, LICENSE, `package.json`, etc.) are NOT copied into `.loopx/`. Only workflow directories are installed. Assert that a root `package.json` in the source does not create `.loopx/package.json` **and** that a root `README.md` in the source does not create `.loopx/README.md`. Both file types are repo-level support files that must be excluded when only workflow directories are copied. *(Spec 10.3)*
- **T-INST-54a**: Multi-workflow install preserves workflow-internal non-script files and subdirectories. Source repo contains `ralph/index.ts`, `ralph/package.json`, `ralph/lib/helpers.ts`, and `ralph/README.md` (plus `other/index.sh` to force multi-workflow classification). After install, assert `.loopx/ralph/package.json`, `.loopx/ralph/lib/helpers.ts`, and `.loopx/ralph/README.md` are all present. This verifies that the entire workflow directory — not just discovered script files — is copied. *(Spec 10.3)*
- **T-INST-54b**: Multi-workflow source-root `package.json` is ignored during validation and version checking. Source repo contains `ralph/index.sh`, `other/index.sh`, and a repo-root `package.json` that is either invalid JSON (e.g., `{broken`) or declares a loopx version range not satisfied by the running version. `loopx install <source>` succeeds, installing both workflows. Assert: no warning or error on stderr related to `package.json` or version mismatch. In the workflow model, only each workflow's own `package.json` matters for version checking — the repo-root file is a support file that is neither copied (T-INST-54) nor read for validation. *(Spec 10.3, 10.6)*
- **T-INST-54c**: Multi-workflow install does not copy root support directories. Source repo contains `ralph/index.sh`, `other/index.sh`, `docs/README.md`, and `shared/config.json`. After install, assert `.loopx/ralph/` and `.loopx/other/` exist, but `.loopx/docs/` and `.loopx/shared/` do not exist. This is the directory counterpart to T-INST-54 (which covers root support files) — T-INST-55 verifies that non-workflow subdirectories are silently skipped during classification, but does not assert their absence from the destination. A buggy installer that correctly classifies workflows but still copies all subdirectories into `.loopx/` would pass T-INST-55 but fail here. *(Spec 10.3)*
- **T-INST-54d**: Multi-workflow tarball source-root `package.json` is ignored during validation and version checking. Create a `.tar.gz` whose source root (after any wrapper-directory stripping) contains workflow subdirectories `ralph/index.sh` and `other/index.sh`, plus a source-root `package.json` that is either invalid JSON (e.g., `{broken`) or declares a loopx version range not satisfied by the running version. `loopx install <tarball-url>` succeeds, installing both workflows. Assert: (a) exit code 0, (b) both `.loopx/ralph/` and `.loopx/other/` are installed, (c) no warning or error on stderr related to `package.json` or version mismatch, and (d) `.loopx/package.json` does not exist (the source-root file was not copied). This is the tarball counterpart to T-INST-54b (git multi-workflow): per SPEC 10.2, classification after extraction is source-type-agnostic, so the "source-root `package.json` is not read for multi-workflow classification or version checking" rule must hold for both source types. *(Spec 10.2, 10.3, 10.6)*
- **T-INST-55**: Multi-workflow repo: subdirectories with no script files are silently skipped. They don't cause failure. *(Spec 10.3)*
- **T-INST-55a**: Non-recursive workflow detection during install classification. Multi-workflow source contains a candidate directory `tools/` with only nested supported-extension files (e.g., `tools/lib/helper.ts`) and no top-level script files (no `tools/*.sh|js|jsx|ts|tsx`). That directory is skipped as a non-workflow — only top-level files count for workflow detection. Other valid workflow directories in the source are installed normally. *(Spec 10.3, 2.1)*
- **T-INST-55c**: Multi-workflow source where `ralph/` contains only `index.mjs` (unsupported extension) alongside valid workflow `other/` (containing `index.sh`). `ralph/` is skipped as a non-workflow — `.mjs` is not a supported script extension, so the directory has no top-level script files. Assert: (a) only `.loopx/other/` is installed, (b) `.loopx/ralph/` does not exist, and (c) no warning or error about `ralph/`. This is the install-time counterpart to T-DISC-06/07, which cover `.mjs`/`.cjs` being unrecognized at runtime discovery. *(Spec 10.3, 2.1)*
- **T-INST-55b**: Multi-workflow source with an invalid-named non-workflow subdirectory. Source repo contains `ralph/index.sh`, `other/index.sh`, and `-bad-dir/README.md` (no script files — not a workflow). Install succeeds, installing only `ralph` and `other`. The `-bad-dir` directory is silently skipped with no error or warning about its invalid name. This locks down the rule that name validation applies only to discovered workflows — directories that don't qualify as workflows are never validated, even if their names would fail the naming restriction pattern. *(Spec 10.3)*
- **T-INST-55e**: Multi-workflow source containing a legacy-style directory-script subdirectory is handled correctly: the legacy subdirectory is skipped, and only valid workflow directories are installed. Source repo has `good/index.sh` plus `legacy/package.json` (with `{ "main": "src/run.js" }`) and `legacy/src/run.js`, but **no** top-level files with supported script extensions inside `legacy/` (the only supported-extension file is nested in `src/`). `loopx install <source>` → exits 0. Assert: (a) `.loopx/good/` is installed and contains `index.sh`, (b) `.loopx/legacy/` does **not** exist — the `legacy/` directory had no top-level script files and was silently skipped as a non-workflow. This is the multi-workflow-subdirectory counterpart to T-INST-56a (which covers the source-root legacy directory-script as a zero-workflow case). T-CLI-104c and T-DISC-20c cover runtime non-discovery of legacy directory-script layouts; this covers the install classification path for a legacy subdirectory coexisting with valid workflows. *(Spec 10.3, 2.1)*
- **T-INST-55d**: Root-level unsupported script-like files (`.mjs`/`.cjs`) do not force single-workflow classification. Source root contains `index.mjs` (or `config.cjs`) plus `ralph/index.sh` and `other/index.sh`. Because `.mjs` and `.cjs` are not supported script extensions (Spec 2.1), the root has no files with supported extensions and the source is classified as multi-workflow — both `ralph` and `other` are installed. Assert: `.loopx/ralph/` and `.loopx/other/` exist. This pins down the boundary between T-INST-50a (supported root-level files force single-workflow) and T-INST-56c/55c (unsupported extensions are ignored) for the case where valid workflow subdirectories coexist with unsupported root files. *(Spec 10.3, 2.1)*

#### Workflow Classification — Zero-Workflow Source

- **T-INST-56**: Git repo with no root-level script files and no subdirectories that qualify as workflows → error. *(Spec 10.3)*
- **T-INST-56a**: A source repo structured as a legacy directory script — root `package.json` with `main` pointing to a deeply nested file (e.g., `{ "main": "src/app/run.js" }`), with the script file only inside a nested subdirectory (`src/app/`) and no top-level files with supported script extensions. The top-level `src/` directory contains no top-level script files (`src/*.{sh,js,jsx,ts,tsx}`) so it does not qualify as a workflow — the source is classified as zero-workflow and rejected with an error. Assert exit code 1 and that the error indicates no installable workflows were found. This proves the install mechanism does not fall back to legacy directory-script install behavior — the `main` field is not used for workflow classification. *(Spec 10.3)*
- **T-INST-56e**: Legacy directory-script source is rejected as zero-workflow without migration-guidance messaging. Create a source root with a `package.json` whose `main` points to a nested file (e.g., `{ "main": "src/app/run.js" }`) and no top-level files with supported script extensions (the script file lives only inside a nested subdirectory like `src/app/run.js`). Run `loopx install <source>`. Assert: (a) exit code 1, (b) the error indicates no installable workflows were found, and (c) — **structurally** rather than by prose blacklisting — stderr does not contain a migration-guidance or deprecation warning as a separate output category alongside the zero-workflow error. Concretely: the stderr output is limited to the standard "no installable workflows found" error (and any unrelated warnings that would be emitted regardless of the legacy layout). There is no additional warning/notice/advisory line whose subject is the legacy directory-script layout (the `main` field, the nested script file, or the `package.json`-without-top-level-scripts shape are not flagged in any extra output category beyond the routine zero-workflow rejection). Prose-level phrase matching is intentionally avoided — the check targets the presence of a distinct migration-warning output category, not specific wording. T-INST-56a proves the zero-workflow rejection for this shape; this test extends it with the structural anti-migration-messaging assertion, aligning install behavior with ADR-0003's explicit "no legacy compatibility or migration tooling" consequence and mirroring runtime coverage in T-DISC-10a (flat script) and T-DISC-20c (directory script). *(Spec 10.3)*
- **T-INST-56c**: Source root containing only `index.mjs` at root level (no files with supported extensions) → zero-workflow error. `.mjs` is not a supported script extension (Spec 2.1), so no script files are found at the root level and no subdirectories qualify as workflows. This is the install-classification counterpart to T-DISC-06, which covers `.mjs` being unrecognized at runtime discovery. *(Spec 10.3, 2.1)*
- **T-INST-56d**: Source root containing only `index.cjs` at root level → zero-workflow error. `.cjs` is not a supported script extension. This is the install-classification counterpart to T-DISC-07. *(Spec 10.3, 2.1)*
- **T-INST-56b**: Tarball source with no installable workflows → error. Create a `.tar.gz` whose source root (after wrapper-directory stripping) contains no root-level script files and no subdirectories that qualify as workflows (e.g., only `README.md` and a `lib/` directory with `.ts` files nested inside). `loopx install <tarball-url>` → exits with code 1 with an error indicating no installable workflows were found. This is the tarball counterpart to T-INST-56 (git zero-workflow) — the classification logic is source-type-agnostic, so both source types must reject zero-workflow sources. *(Spec 10.3, 10.2)*

#### Selective Workflow Installation

- **T-INST-57**: `loopx install -w ralph <multi-workflow-source>` installs only `ralph`. Assert `.loopx/ralph/` exists but `.loopx/other/` does not. *(Spec 10.8)*
- **T-INST-57a**: `loopx install --workflow ralph <multi-workflow-source>` is equivalent to `loopx install -w ralph <source>`. Assert `.loopx/ralph/` exists but `.loopx/other/` does not. This tests the long-form `--workflow` flag. *(Spec 4.2, 10.8)*
- **T-INST-57b**: `loopx install -w ralph <multi-workflow-source>` where the source root also contains `README.md`, `package.json`, `docs/`, `shared/`, and a sibling workflow `other/` (with `index.sh`) → only `.loopx/ralph/` is created. Assert: no source-root support files or directories (`README.md`, `package.json`, `docs/`, `shared/`) are copied into `.loopx/`, and `.loopx/other/` does not exist. This is the `-w` counterpart to T-INST-54 / T-INST-54c, which prove self-containment for full multi-workflow installs — the same rule must hold on the selective `-w` code path. *(Spec 10.3, 10.8)*
- **T-INST-57c**: `loopx install -w ralph <multi-workflow-tarball>` installs only `ralph`. Create a `.tar.gz` whose source root (after any wrapper-directory stripping) contains subdirectories `ralph/` (with `index.sh`) and `other/` (with `index.sh`), with no root-level script files. Run `loopx install -w ralph <tarball-url>`. Assert: (a) `.loopx/ralph/` is installed and contains `index.sh`, and (b) `.loopx/other/` does not exist. T-INST-57 / T-INST-57a / T-INST-57b cover the `-w` selective-install path with git-backed sources; this test explicitly exercises the tarball source path. Per SPEC 10.2, classification after extraction is source-type-agnostic, so the selective-install behavior must hold identically for tarball and git sources — this closes the gap left by the otherwise git-heavy `-w` coverage. *(Spec 10.2, 10.8)*
- **T-INST-58**: `loopx install -w nonexistent <multi-workflow-source>` → error (workflow not in source). *(Spec 10.8)*
- **T-INST-59**: `loopx install -w ralph <single-workflow-source>` → error (`-w` is invalid for single-workflow sources). The source must have root-level script files (e.g., `index.ts`) **and** subdirectories containing supported-extension files (e.g., `lib/helpers.ts`, `src/utils.js`), so the test genuinely proves that root-level scripts force single-workflow classification even in the presence of subdirectories with script-extension files. Using `-w` is an error regardless of the name provided. *(Spec 10.3, 10.8)*
- **T-INST-59a**: `loopx install --workflow ralph <single-workflow-source>` → error. Long-form `--workflow` parity with T-INST-59: `--workflow` is invalid for single-workflow sources, same as `-w`. *(Spec 10.8, 4.2)*
- **T-INST-59b**: `loopx install -w ralph <single-workflow-source>` → error, where the source root contains a **non-index** script file (e.g., `setup.ts`) **and** subdirectories that would themselves qualify as workflows (e.g., `lib/helpers.ts`, `src/utils.js`). T-INST-59 / T-INST-59a use a root-level `index.ts` and so can be satisfied by an implementation that only treats `index.*` as the single-workflow trigger; this test uses a non-index root script so it proves the `-w` rejection fires for **any** root-level script file, not just the default entry point. Aligns the `-w` rejection coverage with T-INST-52c (which proves the same non-index root-script classification rule at the classification level). *(Spec 10.3, 10.8)*
- **T-INST-60**: With `-w`, only the selected workflow is validated. Invalid sibling workflows don't block installation. *(Spec 10.8)*
- **T-INST-60a**: With `-w`, source-validation failures in unselected sibling workflows do not block installation. Multi-workflow source where `ralph/` is valid (contains `index.sh`) and `broken/` has an invalid script name (e.g., `broken/-bad.sh`). `loopx install -w ralph <source>` succeeds and `.loopx/ralph/` is created — the invalid script name in `broken/` is not evaluated because `-w ralph` limits preflight to the selected workflow only. *(Spec 10.8, 10.4)*
- **T-INST-60b**: With `-w`, version mismatches in unselected sibling workflows do not block installation and emit no warnings. Multi-workflow source where `ralph/` has no version declaration (no `package.json`) and `other/` declares a loopx range not satisfied by the running version. `loopx install -w ralph <source>` succeeds — `other/`'s version mismatch is not evaluated because `-w ralph` limits preflight to the selected workflow only. Assert: exit code 0 **and** stderr contains no version-mismatch warning for `other/`. *(Spec 10.8, 10.6)*
- **T-INST-60c**: With `-w`, destination collisions for unselected sibling workflows do not block installation. Multi-workflow source contains `ralph/` (with `index.sh`) and `other/` (with `index.sh`). `.loopx/other/` already exists as a workflow (contains at least one script file). `loopx install -w ralph <source>` succeeds without `-y` — `other/`'s destination collision is not evaluated because `-w ralph` limits preflight to the selected workflow only. *(Spec 10.8, 10.5)*
- **T-INST-60d**: With `-w`, an invalid workflow name on an unselected sibling does not block installation. Multi-workflow source contains `ralph/` (with `index.sh`) and `-bad-name/` (with `index.sh` — valid scripts but invalid workflow name). `loopx install -w ralph <source>` succeeds — the invalid workflow name in `-bad-name/` is not evaluated because `-w ralph` limits preflight to the selected workflow only. *(Spec 10.8, 5.3)*
- **T-INST-60e**: With `-w`, a same-base-name collision in an unselected sibling does not block installation. Multi-workflow source contains `ralph/` (with `index.sh`) and `other/` (with `check.sh` and `check.ts`). `loopx install -w ralph <source>` succeeds — `other/`'s same-base-name collision is not evaluated because `-w ralph` limits preflight to the selected workflow only. *(Spec 10.8, 10.4)*
- **T-INST-60f**: With `-w`, a broken `package.json` in an unselected sibling workflow emits no warning. Multi-workflow source where `ralph/` is valid (contains `index.sh`, no `package.json`) and `broken/` contains `index.sh` plus a `package.json` with invalid JSON content (e.g., `{broken`). `loopx install -w ralph <source>` succeeds. Assert: no `package.json`-related warning or error on stderr. The broken sibling's `package.json` is never read because `-w ralph` limits all validation — including version checking — to the selected workflow only. *(Spec 10.8, 10.6)*
- **T-INST-60g**: With `-w`, the selected workflow's own invalid script names are still fatal. Multi-workflow source where `broken/` contains `-bad.sh` (invalid script name) and `ralph/` is valid (contains `index.sh`). `loopx install -w broken <source>` → exits with code 1. T-INST-60a proves unselected siblings' invalid names are ignored; this proves the selected workflow itself is not exempt from install-time validation under `-w`. *(Spec 10.8, 10.4)*
- **T-INST-60h**: With `-w`, the selected workflow's own same-base-name collisions are still fatal. Multi-workflow source where `broken/` contains `check.sh` and `check.ts` (same base name, different extensions) and `ralph/` is valid (contains `index.sh`). `loopx install -w broken <source>` → exits with code 1. T-INST-60e proves unselected siblings' collisions are ignored; this proves the selected workflow itself is still checked. *(Spec 10.8, 10.4)*
- **T-INST-60i**: With `-w`, the selected workflow's own version mismatch is still a blocking error. Multi-workflow source where `ralph/` contains `index.sh` plus a `package.json` declaring a `loopx` version range not satisfied by the running version, and `other/` is valid (contains `index.sh`, no `package.json`). `loopx install -w ralph <source>` → exits with code 1. T-INST-60b proves unselected siblings' version mismatches are ignored; this proves the selected workflow's version declaration is still enforced under `-w`. *(Spec 10.8, 10.6)*
- **T-INST-60j**: With `-w -y`, the selected workflow's version mismatch is overridden. Same source as T-INST-60i. `loopx install -w -y ralph <source>` succeeds. Assert `.loopx/ralph/` is created and contains `index.sh` and the workflow's `package.json` with its version declaration preserved. *(Spec 10.8, 10.6)*
- **T-INST-60k**: With `-w`, the selected workflow's own destination collision is still a blocking error. Multi-workflow source where `ralph/` contains `index.sh` and `other/` is valid (contains `index.sh`). `.loopx/ralph/` already exists as a workflow (contains at least one top-level script file). `loopx install -w ralph <source>` → exits with code 1. T-INST-60c proves unselected siblings' destination collisions are ignored; this proves the selected workflow's collision is still enforced under `-w`. *(Spec 10.8, 10.5)*
- **T-INST-60l**: With `-w -y`, the selected workflow's destination collision is overridden. Same setup as T-INST-60k. `loopx install -w -y ralph <source>` succeeds. Assert `.loopx/ralph/` contains the new workflow content from the source (not the old content). `.loopx/other/` does not exist — only the selected workflow is installed. *(Spec 10.8, 10.5)*
- **T-INST-60p**: With `-w -y`, a non-workflow destination for the selected workflow still causes failure. Multi-workflow source where `ralph/` contains `index.sh` and `other/` is valid (contains `index.sh`). `.loopx/ralph` already exists but is not a workflow by structure (e.g., a plain file, an empty directory, or a symlink to a non-workflow target). `loopx install -w ralph -y <source>` → exits with code 1. The `-y` flag overrides workflow-path collisions and version mismatches, but does not override non-workflow destination paths — even on the selective `-w` code path. T-INST-60k/60l cover the `-w` collision path where the destination is a real workflow; T-INST-68/69/70a/70c cover non-workflow collision refusal on the generic (non-`-w`) path. This combination is worth testing because `-w` often gets its own code path. *(Spec 10.8, 10.5)*
- **T-INST-60m**: With `-w`, selecting a workflow with an invalid name causes install to fail. Multi-workflow source contains `-bad-name/` (with `index.sh` — valid scripts but invalid workflow name) and `good/` (with `index.sh`). `loopx install -w -bad-name <source>` → exits with code 1. T-INST-60d proves an unselected invalid workflow name does not block `-w`; this proves the selected workflow's name is still validated even under `-w`. *(Spec 10.8, 5.3)*
- **T-INST-60n**: `--workflow` long form exercises the same selective-validation semantics as `-w`. Multi-workflow source where `ralph/` is valid (contains `index.sh`) and `broken/` has an invalid script name (e.g., `broken/-bad.sh`). `.loopx/` initially empty. `loopx install --workflow ralph <source>` succeeds and `.loopx/ralph/` is created — the invalid script name in `broken/` is not evaluated. This mirrors T-INST-60a but uses the `--workflow` long form to verify that selective validation is not inadvertently tied to the short `-w` parsing path. *(Spec 10.8, 10.4, 4.2)*
- **T-INST-60o**: With `-w`, selecting a subdirectory that does not qualify as a workflow is an error. Multi-workflow source contains `good/index.sh` and `legacy/package.json` (with `{ "main": "src/run.js" }`) plus `legacy/src/run.js`, but no top-level script files inside `legacy/`. `loopx install -w legacy <source>` → exits with code 1 (named workflow does not exist in source). `legacy/` is not a workflow because it has no top-level supported-extension files — the `-w` flag does not cause loopx to relax workflow detection rules. This is the selective-install counterpart to T-INST-55e (which covers the same legacy subdirectory being silently skipped during full multi-workflow install). *(Spec 10.8, 10.3)*
- **T-INST-60q**: With `-w`, the selected workflow's own `package.json` with invalid JSON emits a single non-fatal warning and the install still succeeds. Multi-workflow source where `ralph/` contains `index.sh` plus a `package.json` with invalid JSON content (e.g., `{broken`), and `other/` is valid (contains `index.sh`, no `package.json`). `loopx install -w ralph <source>` → exit code 0. Assert: (a) stderr contains exactly one `package.json` parse-failure warning for `ralph`, (b) `.loopx/ralph/` is installed and contains both `index.sh` and the broken `package.json` (file is preserved as-is), and (c) `.loopx/other/` does not exist. T-INST-75 proves invalid JSON emits a non-fatal warning on the generic install path; T-INST-60f proves the warning is suppressed for unselected siblings under `-w`; this test pins down that the selected workflow under `-w` still receives the normal non-fatal warning behavior — the `-w` code path does not accidentally promote the warning to a fatal error or suppress it entirely for the selected workflow. *(Spec 10.8, 10.6, 3.2)*
- **T-INST-60r**: With `-w`, the selected workflow's own unreadable `package.json` emits a single non-fatal warning and the install still succeeds. Same structure as T-INST-60q, but `ralph/package.json` is set to mode 000 (unreadable) instead of containing invalid JSON. **Source must be a tarball** (or another non-git source path), since Git does not reliably preserve mode 000 file permissions across clone. `loopx install -w ralph <tarball-url>` → exit code 0. Assert: (a) stderr contains exactly one `package.json` read-failure warning for `ralph`, (b) `.loopx/ralph/` is installed and contains `index.sh` and the unreadable `package.json`, and (c) `.loopx/other/` does not exist. This is the unreadable-file counterpart to T-INST-60q (invalid JSON) — T-INST-74 covers the generic path; this test covers the selective `-w` path. **Conditional on `process.getuid() !== 0`.** *(Spec 10.8, 10.6, 3.2)*
- **T-INST-60s**: With `-w`, the selected workflow's own `package.json` with an invalid semver range for `loopx` emits a single non-fatal warning and the install still succeeds. Same structure as T-INST-60q, but `ralph/package.json` contains valid JSON with an invalid semver range (e.g., `{ "dependencies": { "loopx": "not-a-range!!!" } }`) instead of invalid JSON. `loopx install -w ralph <source>` → exit code 0. Assert: (a) stderr contains exactly one invalid-semver warning for `ralph`, (b) `.loopx/ralph/` is installed and contains `index.sh` and the `package.json` with its original (invalid) range preserved, and (c) `.loopx/other/` does not exist. This is the invalid-semver counterpart to T-INST-60q (invalid JSON) and T-INST-60r (unreadable) — T-INST-76 covers the generic path; this test covers the selective `-w` path. Together, T-INST-60q/60r/60s prove the `-w` code path preserves the non-fatal-warning behavior across all three `package.json` failure branches for the selected workflow. *(Spec 10.8, 10.6, 3.2)*

#### Install-time Validation

- **T-INST-61**: Workflow with invalid script name (e.g., `-bad.sh`) → install fails. *(Spec 10.4)*
- **T-INST-62**: Workflow with same-base-name collision (e.g., `check.sh` and `check.ts`) → install fails. *(Spec 10.4)*
- **T-INST-62a**: Workflow source with both `index.sh` and `index.ts` → install fails. This is the `index`-specific variant of T-INST-62 — a buggy installer could special-case `index` and still pass the generic same-base-name collision test (T-INST-62). *(Spec 10.4, 2.1)*
- **T-INST-63**: Derived workflow name must match name restriction rules. Invalid name → install fails. *(Spec 10.4)*
- **T-INST-63a**: Digit-start workflow name is valid at install time. Single-workflow source whose derived name starts with a digit (e.g., repo named `3checks` containing `check.sh`). `loopx install <source>` succeeds and installs to `.loopx/3checks/`. This covers the install-time workflow-name validation path separately from runtime discovery (T-DISC-26a/26b), since install has its own name-validation code path. *(Spec 10.4, 5.3)*
- **T-INST-63b**: Install rejects a workflow name containing `:`. Source whose derived workflow name includes a colon (e.g., a tarball archive named `my:workflow.tar.gz` containing root-level `index.sh`). `loopx install <source>` → exits with code 1. The `:` is the reserved target delimiter and is explicitly disallowed in names. This mirrors runtime discovery coverage (T-DISC-32) at the install-time validation code path. *(Spec 10.4, 5.3)*
- **T-INST-63c**: Install rejects a script base name containing `:`. Single-workflow source containing a script file with `:` in its base name (e.g., `check:ready.sh` alongside a valid `index.sh`). `loopx install <source>` → exits with code 1. This mirrors runtime discovery coverage (T-DISC-31) at the install-time validation code path. *(Spec 10.4, 5.3)*
- **T-INST-63d**: Numeric script names are valid at install time. Single-workflow source containing `index.sh`, `1start.sh`, and `42.sh`. `loopx install <source>` succeeds. Assert `.loopx/<repo-name>/` contains all three scripts. This is the install-time positive counterpart to T-DISC-30a/30b (digit-start and all-digit script names valid at runtime discovery) — runtime naming allows these, but install-time script-name validation is only covered explicitly with negative cases (T-INST-61, T-INST-63c) without a symmetric positive case for numeric names. *(Spec 10.4, 5.3)*
- **T-INST-63e**: Install rejects a multi-workflow subdirectory name containing `:`. Multi-workflow source whose source root (after any wrapper-directory stripping) contains a subdirectory named with `:` (e.g., `foo:bar/index.sh`) alongside a valid sibling workflow (e.g., `other/index.sh`) and no root-level script files. `loopx install <source>` → exits with code 1 with a name-restriction error identifying the offending subdirectory name. Per the install atomicity rules (Spec 10.7), no workflows are written — assert `.loopx/foo:bar/` does not exist AND `.loopx/other/` does not exist. T-INST-63b covers the single-workflow tarball archive-name derivation path (archive name `my:workflow.tar.gz`); this test exercises the **second** install-time workflow name source — multi-workflow subdirectory-name derivation — ensuring ADR-0003's reserved-delimiter `:` rule fires on both derivation paths. A buggy implementation could reject `:` only in the archive-name path and silently install (or skip) a `:`-named subdirectory in the multi-workflow path. *(Spec 10.4, 10.3, 5.3, 10.7)*
- **T-INST-64**: Missing `index` script is allowed at install time for single-workflow sources. A single-workflow source whose root contains `check.sh` but no `index.*` file. `loopx install <source>` succeeds. Assert the installed workflow is present under `.loopx/<repo-name>/` and contains `check.sh`. This explicitly covers the single-workflow classification path introduced by ADR-0003 — root-level script files make the source single-workflow, and missing `index` is still allowed. A bug could exist where a multi-workflow subdirectory can omit `index` but a single-workflow source incorrectly requires it. *(Spec 10.4, 10.3)*
- **T-INST-64b**: Missing `index` script is allowed at install time for multi-workflow sources. Multi-workflow source with `tools/check.sh` (no `tools/index.*`) and `other/index.sh` (to force multi-workflow classification). `loopx install <source>` succeeds. Assert both `.loopx/tools/` and `.loopx/other/` are installed, and `.loopx/tools/` contains `check.sh`. This complements the single-workflow path (T-INST-64) — a bug could allow missing index in single-workflow sources but incorrectly require it in multi-workflow subdirectories. *(Spec 10.4, 10.3)*
- **T-INST-64c**: Missing `index` script is allowed at install time for multi-workflow sources with `-w` scoping. Same source as T-INST-64b. `loopx install -w tools <source>` succeeds. Assert `.loopx/tools/` is installed and contains `check.sh`, and `.loopx/other/` does not exist. This covers the selective-install path for a workflow without an index script. *(Spec 10.4, 10.8)*
- **T-INST-64a**: Install-time validation is non-recursive within a workflow. Single-workflow source has a top-level `index.ts` plus a nested `lib/` subdirectory containing `-bad.ts` (invalid script name) and both `check.sh` and `check.ts` (same-base-name collision). Install succeeds because nested files within a workflow are not discovered or validated as scripts — only top-level files are checked. Assert exit code 0 and that `.loopx/<repo-name>/lib/-bad.ts`, `.loopx/<repo-name>/lib/check.sh`, and `.loopx/<repo-name>/lib/check.ts` are all present in the installed workflow (copied as workflow content, not rejected as invalid scripts). *(Spec 10.4, 2.1)*
- **T-INST-64d**: Install-time validation is non-recursive within workflows in a multi-workflow source. Multi-workflow source with two workflows: `ralph/index.sh` plus `ralph/lib/-bad.ts` (invalid script name) and `ralph/lib/check.sh` + `ralph/lib/check.ts` (same-base-name collision), and `other/index.sh` (a second workflow to force multi-workflow classification). Install succeeds because nested files within a workflow are not discovered or validated as scripts — only top-level files are checked. Assert exit code 0 and that `.loopx/ralph/lib/-bad.ts`, `.loopx/ralph/lib/check.sh`, and `.loopx/ralph/lib/check.ts` are all present in the installed workflow (copied as workflow content, not rejected as invalid scripts). This is the multi-workflow counterpart to T-INST-64a (which covers the single-workflow path). *(Spec 10.4, 2.1)*
- **T-INST-52b**: Multi-workflow source with `ralph/index.sh`, `ralph/eslint.config.js`, and `other/index.sh` → install fails because every top-level file with a supported extension inside a workflow directory is a discovered script, and `eslint.config` violates the script name restriction `[a-zA-Z0-9_][a-zA-Z0-9_-]*` (the dot is not allowed). Assert exit code 1 and that the error references the invalid script name. This is the install-time mirror of T-DISC-15a / T-DISC-15b, which test the same "no opt-out" rule at runtime discovery — a buggy installer could special-case config/helper-style files during workflow-directory scanning and still pass the current suite. *(Spec 2.1, 5.3, 10.4)*

#### Collision Handling

- **T-INST-65**: Path does not exist → workflow installed without collision check. *(Spec 10.5)*
- **T-INST-66**: Path exists and is a workflow by structure → install refused with error. *(Spec 10.5)*
- **T-INST-67**: Path exists and is a workflow by structure, with `-y` → existing workflow replaced. *(Spec 10.5)*
- **T-INST-67a**: Path exists and is a workflow by structure but would fail runtime validation, with `-y` → existing workflow replaced. Set up `.loopx/foo/` containing a script with an invalid name (`-bad.sh`) and a same-base-name collision (`check.sh` + `check.ts`). `loopx install -y <source>` where the source contains a valid workflow named `foo`. Assert the existing invalid workflow is replaced successfully. The collision structural check requires only that the destination path is a directory with at least one top-level file with a supported script extension — it does not perform full runtime validation. *(Spec 10.5)*
- **T-INST-68**: Path exists but is NOT a workflow by structure (e.g., directory with no script files, or a non-directory entry) → install refused with error, even with `-y`. *(Spec 10.5)*
- **T-INST-69**: `-y` must not replace non-workflow entries. A plain file at `.loopx/<name>` is refused even with `-y`. *(Spec 10.5)*
- **T-INST-70**: Symlinked workflow collision: structural check follows the symlink target. `.loopx/foo` is a symlink pointing to a directory that contains at least one top-level file with a supported script extension. `loopx install <source>` where the source contains a workflow named `foo` → install refused with collision error. The structural check followed the symlink and found a workflow at the target. *(Spec 10.5)*
- **T-INST-70b**: Symlinked workflow with `-y`: removes the symlink itself, not the target directory. `.loopx/foo` is a symlink pointing to a directory that qualifies as a workflow (contains a top-level script file). `loopx install -y <source>` where the source contains a workflow named `foo` → install succeeds. Assert: (a) `.loopx/foo` is now a regular directory (not a symlink) containing the new workflow content, and (b) the original symlink target directory still exists and is unmodified. *(Spec 10.5)*
- **T-INST-70a**: Symlink-to-non-workflow collision refusal. `.loopx/foo` is a symlink whose target is a directory with no top-level script files (e.g., the target contains only `lib/helper.ts` nested in a subdirectory). `loopx install -y <source>` where the source contains a workflow named `foo` → install refuses with an error, even with `-y`. The structural check follows the symlink, finds the target is not a workflow (no top-level script files), and treats it as a non-workflow destination path. *(Spec 10.5)*
- **T-INST-70c**: Symlink-to-file collision refusal. `.loopx/foo` is a symlink whose target is a regular file (not a directory). `loopx install -y <source>` where the source contains a workflow named `foo` → install refuses with an error, even with `-y`. A symlink to a file is a non-directory filesystem entry — it cannot be a workflow by structure (workflows are directories containing script files), so `-y` must not replace it. This completes the symlink/non-directory branch: T-INST-70/70b cover symlink-to-workflow-directory, T-INST-70a covers symlink-to-non-workflow-directory, and this test covers symlink-to-file. *(Spec 10.5)*
- **T-INST-70d**: Symlink-to-structurally-valid-but-full-validation-invalid workflow is replaceable with `-y`. Create a directory outside `.loopx/` (e.g., `/tmp/invalid-workflow/`) that is structurally a workflow (contains at least one top-level file with a supported script extension, e.g., `index.sh`) but would fail full runtime validation — it contains a same-base-name collision (`check.sh` and `check.ts`) and an invalid script name (`-bad.sh`). Then symlink `.loopx/foo → /tmp/invalid-workflow/`. Run `loopx install -y <source>` where the source contains a valid workflow named `foo`. Assert: (a) exit code 0, (b) `.loopx/foo` is now a regular directory (symlink replaced) containing the new workflow content, and (c) the original symlink target directory `/tmp/invalid-workflow/` still exists and is unmodified (symlink itself was removed, not the target). T-INST-67a proves this "local structural check only" rule for regular-directory replacements, and T-INST-70b proves symlink-to-valid-workflow replaces; this test completes the coverage by proving the rule holds on the symlink path even when the target would fail full validation. *(Spec 10.5)*
- **T-INST-71**: `-y` replaceability check is local to `.loopx/<workflow-name>` — broken siblings elsewhere under `.loopx/` do not affect collision evaluation. Set up: `.loopx/foo/` exists as a replaceable workflow (contains at least one top-level file with a supported script extension), and an unrelated sibling `.loopx/broken/` exists as a non-workflow directory (e.g., contains only a `README.md` and no script files). `loopx install -y <source>` where the source contains a valid workflow named `foo`. Assert: install succeeds and `.loopx/foo/` is replaced with the new workflow content. The structural check inspects only the target path `.loopx/foo/`, not the entire `.loopx/` tree — the broken sibling is irrelevant. *(Spec 10.5)*
- **T-INST-71a**: `-y` replaceability check is local to `.loopx/<workflow-name>` — invalid sibling *workflows* elsewhere under `.loopx/` do not affect collision evaluation. Set up: `.loopx/foo/` exists as a replaceable workflow (contains `index.sh`), and `.loopx/broken/` exists as a workflow that would fail runtime validation (e.g., contains `check.sh` and `check.ts` — same-base-name collision, or `-bad.sh` — invalid script name). `loopx install -y <source>` where the source contains a valid workflow named `foo`. Assert: install succeeds and `.loopx/foo/` is replaced with the new workflow content. This strengthens T-INST-71 (which uses a non-workflow sibling) to prove that even invalid workflows elsewhere under `.loopx/` are ignored during collision evaluation — the install mechanism inspects only the target path. *(Spec 10.5)*
- **T-INST-97**: Installing workflow `foo` succeeds when a non-workflow file `.loopx/foo.sh` exists. The collision check targets `.loopx/foo/` (directory), not `.loopx/foo.sh` (file) — they are different filesystem paths, so there is no collision. *(Spec 10.5)*

#### Version Checking on Install

- **T-INST-72**: Workflow declares a loopx version range not satisfied by running version → install refused with error. *(Spec 10.6)*
- **T-INST-73**: With `-y`, version mismatch is overridden and install proceeds. Version declaration preserved. *(Spec 10.6)*
- **T-INST-72a**: Install-time version check for a no-index workflow with version mismatch. Single-workflow source containing `check.sh` (no `index` script) and a `package.json` declaring a loopx range not satisfied by the running version. `loopx install <source>` → exits with code 1 (version mismatch error). This combines the no-index install path (T-INST-64) with version checking (T-INST-72) — both covered separately, but the combination tests that the version check still runs for workflows that lack a default entry point. *(Spec 10.6, 10.4)*
- **T-INST-73a**: Same setup as T-INST-72a with `-y`. `loopx install -y <source>` → exits 0. Assert the workflow is installed with `check.sh` and `package.json` version declaration preserved. This is the `-y` override counterpart to T-INST-72a. *(Spec 10.6, 10.4)*
- **T-INST-74**: Workflow `package.json` unreadable → warning, install proceeds (no version validation). **Source must be a tarball** (or another non-git source path), since Git does not reliably preserve mode 000 file permissions across clone. **Conditional on `process.getuid() !== 0`.** *(Spec 10.6, 3.2)*
- **T-INST-74a**: Install-time `package.json` unreadable warning for a no-index workflow. Single-workflow source containing `check.sh` (no `index.*` script) and a `package.json` file with mode 000 (unreadable). **Source must be a tarball** (or another non-git source path). Run `loopx install <tarball-url>`. Assert: (a) exit code 0, (b) stderr contains an unreadable-file warning for the workflow, and (c) the workflow is installed at `.loopx/<name>/` and contains `check.sh` and the unreadable `package.json`. This combines the no-index install path (T-INST-64) with the unreadable-`package.json` warning path (T-INST-74) — both covered separately, but the combination tests that the `package.json` failure warning still fires for workflows without a default entry point. A buggy implementation could scope the `package.json` read/warn code to the same guard that triggers version comparison, and silently skip both on no-index workflows. **Conditional on `process.getuid() !== 0`.** *(Spec 10.6, 3.2, 10.4)*
- **T-INST-75**: Workflow `package.json` invalid JSON → warning, install proceeds. *(Spec 10.6, 3.2)*
- **T-INST-75a**: Install-time `package.json` invalid-JSON warning for a no-index workflow. Single-workflow source containing `check.sh` (no `index.*` script) and a `package.json` containing invalid JSON (e.g., `{broken`). Run `loopx install <source>`. Assert: (a) exit code 0, (b) stderr contains an invalid-JSON warning for the workflow, and (c) the workflow is installed at `.loopx/<name>/` and contains `check.sh` and the broken `package.json` (file is preserved as-is). This is the invalid-JSON counterpart to T-INST-74a (unreadable), combining the no-index install path (T-INST-64) with the invalid-JSON warning path (T-INST-75). *(Spec 10.6, 3.2, 10.4)*
- **T-INST-76**: Workflow `package.json` invalid semver range → warning, install proceeds. *(Spec 10.6, 3.2)*
- **T-INST-76a**: Install-time `package.json` invalid-semver-range warning for a no-index workflow. Single-workflow source containing `check.sh` (no `index.*` script) and a `package.json` containing valid JSON with an invalid semver range for `loopx` (e.g., `{ "dependencies": { "loopx": "not-a-range!!!" } }`). Run `loopx install <source>`. Assert: (a) exit code 0, (b) stderr contains an invalid-semver warning for the workflow, and (c) the workflow is installed at `.loopx/<name>/` and contains `check.sh` and the `package.json` with its original (invalid) range preserved. This is the invalid-semver counterpart to T-INST-74a (unreadable) and T-INST-75a (invalid JSON), combining the no-index install path (T-INST-64) with the invalid-semver warning path (T-INST-76). Together T-INST-74a/75a/76a close the install-time `package.json` failure-warning coverage gap for no-index workflows across all three non-blocking failure branches — complementing T-INST-72a/73a which cover the blocking version-mismatch branch on the same path. *(Spec 10.6, 3.2, 10.4)*

#### Install Atomicity

- **T-INST-77**: Multi-workflow install: all workflows pass preflight → all installed. *(Spec 10.7)*
- **T-INST-78**: Multi-workflow install: one workflow fails preflight (e.g., name collision at destination) → entire install fails, no workflows written. Assert `.loopx/` unchanged. *(Spec 10.7)*
- **T-INST-79**: Staging failure leaves `.loopx/` unchanged. Multi-workflow source (**must be a tarball** or another non-git source path — Git does not reliably preserve mode 000 file permissions across clone) where `ralph/` is valid (contains `index.sh`) and `broken/` contains a script file (`index.sh`) plus a non-script file with permissions set to `000` (unreadable). `loopx install <tarball-url>` → staging fails when trying to copy the unreadable file in `broken/`. Assert: exit code 1, `.loopx/` is unchanged (neither `ralph/` nor `broken/` was written), and the error message identifies the failing workflow and the underlying cause. **Conditional on `process.getuid() !== 0`.** *(Spec 10.7)*
- **T-INST-80**: Multi-workflow install with `-y` succeeds despite destination collisions and version mismatches. Multi-workflow source where `ralph/` (with `index.sh`) has a destination collision (`.loopx/ralph/` already exists as a workflow with different content) and `other/` (with `index.sh` and a `package.json` declaring a loopx version range not satisfied by the running version) has a version mismatch. `loopx install -y <source>` → exits 0. Assert: `.loopx/ralph/` contains the new content from the source (replaced), and `.loopx/other/` is installed with its `package.json` version declaration preserved. *(Spec 10.7)*
- **T-INST-80a**: Multi-workflow install with multiple preflight failures across different workflows (e.g., workflow A has a name collision at destination, workflow B has an invalid script name, workflow C declares a loopx version range not satisfied by the running version) → single aggregated error report listing all failures across all workflows, including the version mismatch. No workflows written. *(Spec 10.7)*
- **T-INST-80b**: `-y` replacement preserves the existing workflow when staging fails. Multi-workflow source (**must be a tarball** or another non-git source path — Git does not reliably preserve mode 000 file permissions across clone) where `ralph/` is valid (has `index.sh`) and `other/` contains a script file (`index.sh`) plus a non-script file with permissions set to `000` (unreadable). `.loopx/ralph/` already exists as a workflow with known content. `loopx install -y <tarball-url>` → staging fails when trying to copy the unreadable file in `other/`. Assert: exit code 1, the existing `.loopx/ralph/` is still intact with its original content (not removed or modified — the commit phase never ran). **Conditional on `process.getuid() !== 0`.** *(Spec 10.7)*
- **T-INST-80c**: Commit-phase failure reports which workflows were and were not committed. Multi-workflow source with three workflows: `alpha/`, `beta/`, `gamma/` (each with `index.sh`). Set `NODE_ENV=test` and `LOOPX_TEST_INSTALL_FAULT=commit-fail-after:1` in the process environment to simulate a rename failure after committing one workflow (see section 1.4, install fault injection seam — the seam is only honored when `NODE_ENV=test`). Assert: (a) exit code 1, (b) error output identifies which workflow(s) were successfully committed and which were not, and (c) exactly one workflow directory exists in `.loopx/`. *(Spec 10.7)*
- **T-INST-80d**: Install-time `package.json` warning behavior is "once per affected workflow" and is not accidentally deduplicated by runtime-style first-entry logic. Install two workflows (**from a tarball source** or another non-git source path — Git does not reliably preserve mode 000 file permissions across clone), each with an unreadable `package.json` → each workflow's warning appears independently (two warnings, not one). **Conditional on `process.getuid() !== 0`.** *(Spec 3.2, 10.6)*
- **T-INST-80e**: Install-time `package.json` warning behavior for invalid semver ranges is "once per affected workflow." Install two workflows, each with a valid `package.json` containing an invalid semver range for `loopx` (e.g., `"loopx": "not-a-range"`) → each workflow's warning appears independently (two warnings, not one). Install proceeds for both workflows (invalid semver skips version check, does not block install). This is the invalid-semver counterpart to T-INST-80d (unreadable files). *(Spec 3.2, 10.6)*
- **T-INST-80f**: Install-time `package.json` warning behavior for invalid JSON is "once per affected workflow." Install two workflows, each with a `package.json` containing invalid JSON (e.g., `{broken`) → each workflow's warning appears independently (two warnings, not one). Install proceeds for both workflows (invalid JSON skips version check, does not block install). This is the invalid-JSON counterpart to T-INST-80d (unreadable files) and T-INST-80e (invalid semver). *(Spec 3.2, 10.6)*
- **T-INST-80g**: `-y` does not override a zero-workflow source. `loopx install -y <source>` where the source contains no root-level script files and no subdirectories that qualify as workflows → error, exit code 1, regardless of `-y`. *(Spec 10.3, 10.7)*
- **T-INST-80h**: `-y` does not override invalid workflow or script names. `loopx install -y <source>` where the source contains a workflow with an invalid script name (e.g., `-bad.sh`) → error, exit code 1, regardless of `-y`. *(Spec 10.4, 10.7)*
- **T-INST-80i**: `-y` does not override same-base-name collisions within a workflow. `loopx install -y <source>` where the source contains a workflow with `check.sh` and `check.ts` (same base name, different extensions) → error, exit code 1, regardless of `-y`. *(Spec 10.4, 10.7)*
- **T-INST-80j**: `-y` does not override an invalid workflow name. `loopx install -y <source>` where the derived workflow name violates `[a-zA-Z0-9_][a-zA-Z0-9_-]*` (e.g., source directory named `bad.name`) → error, exit code 1, regardless of `-y`. *(Spec 10.4, 10.7)*

#### Tarball Install

- **T-INST-81**: Multi-workflow tarball install with exact name derivation. Create a `.tar.gz` whose source root (after any wrapper-directory stripping) contains subdirectories `ralph/` (with `index.sh`) and `other/` (with `index.sh`). Install the tarball. Assert installed paths are exactly `.loopx/ralph/` and `.loopx/other/`, with the expected scripts present. Workflow names are derived from the source-root subdirectory names. *(Spec 10.2)*
- **T-INST-82**: Wrapper-directory stripping for multi-workflow tarball. Create a `.tar.gz` with a single top-level directory `pkg/` containing `pkg/ralph/index.sh` and `pkg/other/index.sh`. After extraction, `pkg/` is stripped and the source root becomes the contents of `pkg/`. Assert installed paths are `.loopx/ralph/` and `.loopx/other/` (not `.loopx/pkg/`). *(Spec 10.2)*
- **T-INST-83**: No wrapper-directory stripping for multi-entry tarball. Create a `.tar.gz` with multiple top-level entries `ralph/index.sh` and `other/index.sh` (no single wrapper directory). After extraction, the entries are used directly as the source root. Assert installed paths are `.loopx/ralph/` and `.loopx/other/`. *(Spec 10.2)*
- **T-INST-83a**: Multi-workflow tarball self-containment. Create a `.tar.gz` whose source root (after any wrapper-directory stripping) contains two workflow subdirectories `ralph/` (with `index.sh`) and `other/` (with `index.sh`), plus root-level support files `README.md` and `LICENSE`, a root-level support directory `docs/` (containing `docs/guide.md`), and a non-workflow directory `shared/` (containing only `shared/config.json` — no top-level script files). `loopx install <tarball-url>` → exit code 0. Assert: (a) `.loopx/ralph/` and `.loopx/other/` are installed and contain their respective scripts, (b) `.loopx/README.md`, `.loopx/LICENSE`, `.loopx/docs/`, and `.loopx/shared/` do NOT exist — no root support files or directories are copied. Per SPEC 10.2, classification after extraction is source-type-agnostic, so the multi-workflow self-containment rules that apply to git sources (T-INST-54 covers root support files, T-INST-54c covers root support directories, T-INST-55 covers non-workflow subdirectories skipped) must apply equally to tarball sources. Existing tarball coverage (T-INST-81–83) pins down wrapper stripping and workflow-name derivation but does not assert self-containment; this test closes that gap. *(Spec 10.2, 10.3)*
- **T-INST-84**: `.tgz` extension handled identically. *(Spec 10.2)*
- **T-INST-85**: Single-workflow tarball: workflow name derived from archive name (URL last segment minus `.tar.gz`/`.tgz`, query/fragment stripped). *(Spec 10.2)*
- **T-INST-86**: Tarball URL with query string → query stripped from archive-name derivation. *(Spec 10.2)*
- **T-INST-86a**: Tarball URL with fragment → fragment stripped from archive-name derivation. `loopx install http://localhost:PORT/pkg.tar.gz#v1` installs a single-workflow source. Assert the installed workflow is named `pkg` (fragment `#v1` stripped before deriving the archive name). *(Spec 10.2)*
- **T-INST-85a**: Single-workflow tarball with wrapper-directory stripping. Create a `.tar.gz` named `my-agent.tar.gz` with a single top-level wrapper directory (e.g., `wrapper/`) containing a single-workflow source at its root (e.g., `wrapper/index.sh`, `wrapper/check.sh` — root-level script files). Install the tarball. Assert: (a) the wrapper directory is stripped before classification (the source is classified as single-workflow from the unwrapped contents), (b) the installed workflow name is `my-agent` (derived from the archive name, not the wrapper directory name `wrapper`), and (c) the installed workflow at `.loopx/my-agent/` contains the expected scripts. This combines wrapper-directory stripping (tested for multi-workflow in T-INST-82) with single-workflow archive-name derivation (tested without wrapping in T-INST-85). *(Spec 10.2)*
- **T-INST-85b**: Single-workflow tarball with root-level script files plus subdirectories containing supported-extension files. Create a `.tar.gz` named `my-agent.tar.gz` whose source root (after any wrapper-directory stripping) contains root-level script files (e.g., `index.sh`, `check.sh`) plus subdirectories with supported-extension files (e.g., `lib/helpers.ts`, `src/utils.js`) and non-script root-level files (`package.json`, `README.md`). Install the tarball. Assert: (a) the source is classified as single-workflow (root-level script files take precedence unconditionally), (b) the installed workflow name is `my-agent` (derived from the archive name), (c) all root-level files and subdirectories are copied into `.loopx/my-agent/` (including `lib/`, `src/`, `package.json`, `README.md`), and (d) no sibling workflows are created from the subdirectories. This is the tarball counterpart to the git-source root-level-script precedence tests (T-INST-50–52). *(Spec 10.2, 10.3)*

#### Git Install

- **T-INST-87**: Shallow clone (`--depth 1`). Verify clone has only 1 commit. *(Spec 10.2)*
- **T-INST-88**: Single-workflow git repo: name derived from repo URL minus `.git`. *(Spec 10.2)*
- **T-INST-89**: Multi-workflow git repo: workflow names derived from subdirectory names. *(Spec 10.2)*

#### Common Rules

- **T-INST-90**: `.loopx/` directory created if it doesn't exist. *(Spec 10)*
- **T-INST-91**: loopx does not run `npm install` / `bun install` after clone/extract. *(Spec 10.9)*
- **T-INST-92**: HTTP 404 during tarball download → error, exit code 1, no partial directory. *(Spec 10.9)*
- **T-INST-93**: Git clone failure (non-existent repo) → error, exit code 1, no partial directory. *(Spec 10.9)*
- **T-INST-94**: Tarball extraction failure (corrupt archive) → error, exit code 1, no partial directory. *(Spec 10.9)*
- **T-INST-95**: Empty tarball (valid `.tar.gz` with no entries) → error, exit code 1. *(Spec 10.9)*
- **T-INST-96**: Successful single-workflow git install → installed workflow is runnable via `loopx run <name>`. *(Spec 10)*
- **T-INST-97a**: Single-workflow install failure cleanup. Simulate a single-workflow install that fails after the target directory `.loopx/<name>/` has been partially created (e.g., by serving a tarball that extracts successfully but fails post-download validation). Assert: (a) exit code 1, (b) the partially created `.loopx/<name>/` directory is removed, and (c) `.loopx/` is left clean (no partial workflow directory remains). *(Spec 10.9)*
- **T-INST-97b**: Successful install does not create `.loopx/package.json`. Run a successful single-workflow git install into a project. Assert: (a) exit code 0, (b) the workflow is installed at `.loopx/<name>/`, and (c) `.loopx/package.json` does not exist. There is no `.loopx/`-level manifest — version authority lives only in the project root `package.json` and each workflow's own `package.json`. *(Spec 10.6)*

#### Global Install Smoke Test

- **T-INST-GLOBAL-01**: Full global install lifecycle, including workflow-side `import "loopx"` resolution. `npm pack` the built loopx package, install the resulting tarball into an isolated global prefix, and create a fixture project with a `.loopx/ralph/index.ts` script whose content is `import { output } from "loopx"; output({ stop: true });`. Run `<tempdir>/bin/loopx run ralph` (no `-n`) against the fixture project. Assert: (a) exit code 0 (the loop halted cleanly via `stop: true`, proving the import resolved and `output()` executed), and (b) the script actually ran (e.g., marker file written before the `output()` call, or infer from the clean `stop: true` exit). The fixture must exercise `import "loopx"` — just asserting "a TS workflow runs globally" is too weak for Spec 3.1 under the workflow model; this proves a global install is sufficient for workflow JS/TS scripts that import loopx helpers. The spawn environment **must not leak dev-tree binaries into the installed loopx**: PATH must be constructed to include only the isolated global prefix's `bin/` and a minimal system PATH (e.g., `/usr/bin`, `/usr/local/bin`, and whatever directory provides the Node/Bun interpreter under test), with all ancestor `node_modules/.bin` entries filtered out — passing `process.env.PATH` through unchanged is forbidden, because `npm run`/`npx` prepend the loopx repo's `./node_modules/.bin` before invoking vitest, which would silently supply `tsx`, `bun`, and any other binary the runner spawns from the dev tree and mask a missing declared dependency in the published package. The child process's cwd must likewise sit outside the loopx repo so that no ancestor-walked `node_modules/` can resolve transpilers or other runtime binaries. The test must also guard against symlink-based leakage (e.g., `npm install -g .` from a local path creating a symlink back into the dev `dist/`): install from the packed tarball, not a directory, and assert that the installed `loop-extender` package root is a real directory, not a symlink, before running the fixture. *(Spec 3.1, 3.3)*
- **T-INST-GLOBAL-01a**: `[Bun]` Full global install lifecycle under Bun. Same fixture, spawn-environment requirements (scrubbed PATH with no dev-tree `node_modules/.bin`, cwd outside the loopx repo, real-directory install from packed tarball), and assertions as T-INST-GLOBAL-01 (workflow `index.ts` uses `import { output } from "loopx"; output({ stop: true });`), but run via Bun. Proves global install plus workflow-side `import "loopx"` resolution both work under Bun. *(Spec 3.1, 3.3)*

### 4.11 Signal Handling

**Spec refs:** 7.3

Signal tests use the `signal-ready-then-sleep`, `signal-trap-exit`, `signal-trap-ignore`, and `spawn-grandchild` fixtures inside workflows. All signal fixtures follow the ready-protocol.

- **T-SIG-01**: Send SIGINT to loopx while a script is running. Assert loopx exits with code 130. *(Spec 7.3)*
- **T-SIG-02**: Send SIGTERM to loopx while a script is running. Assert exit code 143. *(Spec 7.3)*
- **T-SIG-03**: After SIGINT, the child script process is no longer running. *(Spec 7.3)*
- **T-SIG-04**: Grace period: child traps SIGTERM and exits within 2 seconds → no SIGKILL needed. *(Spec 7.3)*
- **T-SIG-05**: Grace period exceeded: child traps SIGTERM and hangs → SIGKILL after ~5 seconds. *(Spec 7.3)*
- **T-SIG-06**: Process group signal: script spawns a grandchild. Both terminated after SIGTERM. *(Spec 7.3)*
- **T-SIG-07**: Between-iterations signal. Assert loopx exits immediately. `@flaky-retry(3)`. *(Spec 7.3)*
- **T-SIG-08**: Signal identity preserved (SIGINT forwarded as SIGINT, SIGTERM as SIGTERM). *(Spec 7.3)*

### 4.12 CLI Delegation

**Spec refs:** 3.2

#### Setup

Delegation tests create the following structure:
```
/tmp/test-project/
  package.json            ← declares loopx as dependency
  node_modules/
    .bin/
      loopx → symlink or wrapper script pointing to a "local" build
  .loopx/
    ralph/
      index.sh → script that writes LOOPX_BIN to a file
```

The "global" binary is the primary build. The "local" binary is a separate build or a wrapper that sets a marker.

#### Tests

- **T-DEL-01**: When `node_modules/.bin/loopx` exists in CWD and project-root `package.json` declares `loopx` in `dependencies`, the global binary delegates to it. Verify by having the local binary write a marker file. *(Spec 3.2)*
- **T-DEL-02**: Delegation checks CWD only, not ancestor directories. Create a parent directory with a `package.json` that declares `loopx` as a dependency and a corresponding `node_modules/.bin/loopx`. Run loopx from a child directory (which has no `node_modules/.bin/loopx` and no `package.json`). Assert the global binary runs (no delegation). The parent must have a `package.json` declaring `loopx` so the test proves ancestor traversal was actually removed — without it, the test could pass for the weaker reason that the parent binary is undeclared (per T-DEL-16), not because ancestor traversal is not performed. *(Spec 3.2)*
- **T-DEL-03**: Delegation works before `.loopx/` exists. Run `loopx version` from a project root that has `package.json` declaring loopx and `node_modules/.bin/loopx`. Assert the local binary handles the command. *(Spec 3.2)*
- **T-DEL-04**: `LOOPX_DELEGATED=1` in environment prevents delegation. Even if `node_modules/.bin/loopx` exists, the global binary runs. *(Spec 3.2)*
- **T-DEL-05**: After delegation, `LOOPX_BIN` contains the resolved realpath of the local binary (not the global one, not a symlink). *(Spec 3.2)*
- **T-DEL-06**: After delegation, `import from "loopx"` in scripts resolves to the **local (delegated-to) version's** package. The local (delegated-to) `node_modules/loopx` package must export a sentinel value that differs from the global CLI's package. The test script imports from `"loopx"` and writes the sentinel to a marker file. Assert: the marker file contains the delegated package's sentinel, proving module resolution actually points to the local version and not just that delegation occurred at the binary level. *(Spec 3.2, 3.3)*
- **T-DEL-07**: Delegation sets `LOOPX_DELEGATED=1` in the delegated process. *(Spec 3.2)*
- **T-DEL-08**: Delegation happens before command handling. Run global binary with `version` → local binary handles it. *(Spec 3.2)*
- **T-DEL-09**: `LOOPX_DELEGATED=""` (empty string) prevents delegation. *(Spec 3.2)*
- **T-DEL-10**: Delegation preserves SIGINT exit code (130). *(Spec 3.2, 7.3, 12)*
- **T-DEL-11**: Delegation preserves SIGTERM exit code (143). *(Spec 3.2, 7.3, 12)*

#### Project-Root `package.json` Failure Modes

- **T-DEL-12**: No `package.json` at project root → no delegation. Place a marker-writing binary at `node_modules/.bin/loopx` in the project root (so a delegatable binary exists on the filesystem). Run `loopx version` via the global binary. Assert: (a) the global install runs (marker file is NOT created), (b) no warning on stderr, and (c) exit code 0 with the global version string. Without the local binary in the fixture, "no delegation" is trivially true — this setup ensures the decision is driven by the missing `package.json`, not the absent binary. *(Spec 3.2)*
- **T-DEL-13**: Unreadable `package.json` → warning on stderr. Delegation skipped, global runs. Place a marker-writing binary at `node_modules/.bin/loopx` in the project root. Create a `package.json` at the project root and set its permissions to `000` (unreadable). Run `loopx version` via the global binary. Assert: (a) the global install runs (marker file is NOT created), (b) stderr contains a warning about the unreadable `package.json`, and (c) exit code 0 with the global version string. Without the local binary in the fixture, "delegation skipped" passes without exercising the `package.json`-driven decision path. **Conditional on `process.getuid() !== 0`.** *(Spec 3.2)*
- **T-DEL-14**: Invalid JSON in `package.json` → warning on stderr. Delegation skipped, global runs. Place a marker-writing binary at `node_modules/.bin/loopx` in the project root. Create a `package.json` at the project root containing invalid JSON (e.g., `{broken`). Run `loopx version` via the global binary. Assert: (a) the global install runs (marker file is NOT created), (b) stderr contains a warning about the invalid JSON, and (c) exit code 0 with the global version string. Without the local binary in the fixture, "delegation skipped" passes without exercising the `package.json`-driven decision path. *(Spec 3.2)*
- **T-DEL-14a**: Delegation failure warning on a non-version command. Same setup as T-DEL-14 (project root with invalid-JSON `package.json` and a marker-writing `node_modules/.bin/loopx`). Run `loopx install -h` via the global binary. Assert: (a) the global install runs (marker file is NOT created), (b) stderr contains a warning about the invalid JSON, and (c) exit code 0 with install help output. T-DEL-13 and T-DEL-14 prove delegation failure modes on `loopx version`; this proves the same failure-mode warnings fire for a non-version, non-run command, pinning down that delegation failure warnings happen before command parsing for all commands. *(Spec 3.2)*
- **T-DEL-14b**: Delegation failure warning on bare invocation / top-level help. Same setup as T-DEL-14 (project root with invalid-JSON `package.json` and a marker-writing `node_modules/.bin/loopx`). Run bare `loopx` (no arguments) via the global binary. Assert: (a) the global install runs (marker file is NOT created — delegation was skipped due to the broken `package.json`), (b) stderr contains a warning about the invalid JSON, and (c) exit code 0 with top-level help output. T-DEL-13/T-DEL-14/T-DEL-14a prove delegation failure-mode warnings on `loopx version` and `loopx install -h`; this test extends failure-mode coverage to the bare-invocation / top-level-help path. T-DEL-22 and T-DEL-23 cover the positive (successful) delegation case on top-level help and bare invocation respectively; this test covers the negative (skipped-with-warning) case, pinning down that the "delegation happens before command parsing for all commands" rule holds on that path even when delegation is skipped. *(Spec 3.2)*
- **T-DEL-15**: `loopx` declared in `package.json` but `node_modules/.bin/loopx` does not exist → warning on stderr. Delegation skipped, global runs. *(Spec 3.2)*
- **T-DEL-16**: `node_modules/.bin/loopx` exists but `loopx` not declared in any dependency field → no delegation, no warning. The binary is undeclared. *(Spec 3.2)*
- **T-DEL-17**: Project-root `package.json` declares `loopx` in `optionalDependencies` (not `dependencies` or `devDependencies`) and `node_modules/.bin/loopx` exists → delegation occurs. `optionalDependencies` is checked at the project root level for locating a local binary. *(Spec 3.2)*
- **T-DEL-18**: Project-root `package.json` declares `loopx` in `devDependencies` (not `dependencies` or `optionalDependencies`) and `node_modules/.bin/loopx` exists → delegation occurs. `devDependencies` is checked at the project root level for locating a local binary. *(Spec 3.2)*
- **T-DEL-27**: Project-root `package.json` declares `loopx` only in `peerDependencies` (not in `dependencies`, `devDependencies`, or `optionalDependencies`) and `node_modules/.bin/loopx` exists → no delegation, no warning. Per SPEC 3.2, project-root delegation checks only `dependencies`, `devDependencies`, and `optionalDependencies` — `peerDependencies` is not one of the enumerated fields. Place a marker-writing binary at `node_modules/.bin/loopx` in the project root so a delegatable binary exists on the filesystem. Create a project-root `package.json` declaring `loopx` only under `peerDependencies` with any range. Run `loopx version` via the global binary. Assert: (a) the global install runs (marker file is NOT created), (b) stderr contains no warning (this is the "not declared in any checked dependency field" path from T-DEL-16, not the "declared but binary missing" path from T-DEL-15), and (c) exit code 0 with the global version string. T-DEL-17 / T-DEL-18 prove the positive cases for `optionalDependencies` and `devDependencies`, and T-DEL-16 proves the "no declaration" case; this closes the gap by proving that `peerDependencies` is not implicitly treated as one of the checked fields. **Classification:** derived-spec coverage, not core ADR-0003 acceptance coverage. SPEC 3.2 enumerates the three delegation-checked fields explicitly (`dependencies`, `devDependencies`, `optionalDependencies`) but does not explicitly discuss `peerDependencies`; this test validates an exclusion that follows from the enumerated-list semantics rather than from a direct ADR-0003 statement. Keep as a useful boundary test, but do not gate ADR-0003 acceptance on it. *(Spec 3.2)*
- **T-DEL-19**: Delegation is presence-based, not range-based. Project-root `package.json` declares `loopx` in `dependencies` with a semver range NOT satisfied by the local binary's actual version (e.g., `"loopx": "^99.0.0"`), and `node_modules/.bin/loopx` exists → delegation still occurs. The global binary delegates based on declaration presence and binary existence, without comparing the declared range against the local binary's version. Verify by having the local binary write a marker file. *(Spec 3.2)*
- **T-DEL-20**: Workflow-local `package.json` and `node_modules/.bin/loopx` do not trigger delegation. Create a project root with no `package.json`. Create `.loopx/ralph/package.json` declaring `loopx` in `dependencies` and place a marker-writing binary at `.loopx/ralph/node_modules/.bin/loopx`. Create `.loopx/ralph/index.sh`. Run `loopx run -n 1 ralph`. Assert: (a) the global binary runs (marker file is NOT created), and (b) execution succeeds normally. Delegation is based on the project-root `package.json` only — workflow-level version declarations are not used for delegation. *(Spec 3.2)*
- **T-DEL-21**: Delegation applies to non-version, non-run commands. Set up a project root with `package.json` declaring `loopx` in `dependencies` and a corresponding marker-writing `node_modules/.bin/loopx`. Run `loopx install -h` via the global binary. Assert the local binary handles the command (marker file created). This pins down that the simplified delegation model (cwd-only, command-agnostic, before command parsing) applies to commands beyond `version` and `run` — including commands that do not require `.loopx/`. *(Spec 3.2)*
- **T-DEL-22**: Delegation applies to top-level help. Same delegation setup as T-DEL-21. Run `loopx -h` via the global binary. Assert the local binary handles the command (marker file created). Spec 3.2 says delegation happens before command parsing, so the top-level help short-circuit path must also delegate. This extends T-DEL-08 (version), T-DEL-21 (install -h) to the top-level help path. *(Spec 3.2)*
- **T-DEL-23**: Delegation applies to bare invocation. Same delegation setup as T-DEL-21. Run bare `loopx` (no arguments) via the global binary. Assert the local binary handles the command (marker file created). Bare `loopx` is equivalent to `loopx -h` (Spec 4.1), but delegation occurs before that equivalence is resolved — a bad implementation could skip delegation for the zero-argument case. *(Spec 3.2)*

#### Delegation × Version-Check Interaction

- **T-DEL-24**: Runtime delegation × version checking. Set up delegation: project root `package.json` declares `loopx` in `dependencies` with `node_modules/.bin/loopx` present. The local (delegated-to) binary reports version `2.0.0`. Create `.loopx/ralph/index.sh` with a `package.json` declaring `"loopx": "^2.0.0"` in `dependencies`. Run `loopx run -n 1 ralph` via the global binary. Assert: (a) delegation occurs (local binary handles the command), and (b) no version mismatch warning on stderr — the version check compares the workflow's declared range against the delegated local version (`2.0.0`), not the global launcher version. This closes the gap between delegation (T-DEL-01–23) and runtime version checking (T-VER-01–25), which are each tested in isolation but never in combination. *(Spec 3.2)*
- **T-DEL-25**: Install-time delegation × version checking. Same delegation setup as T-DEL-24: local binary reports version `2.0.0`. Source workflow declares `"loopx": "^2.0.0"` in its `package.json`. Run `loopx install <source>` via the global binary. Assert: (a) delegation occurs, (b) install succeeds without version mismatch error, and (c) the workflow is installed in `.loopx/`. The install-time version check must compare the workflow's declared range against the effective delegated version, not the global launcher version. *(Spec 3.2, 10.6)*

#### Additional Delegated Subcommand Coverage

- **T-DEL-26**: Delegation applies to `env list`. Same delegation setup as T-DEL-21. Run `loopx env list` via the global binary. Assert the local binary handles the command (marker file created). T-DEL-08 covers `version`, T-DEL-21 covers `install -h`, T-DEL-22 covers `-h`, and T-DEL-23 covers bare invocation — this extends delegation coverage to a non-help, non-version, non-install subcommand, fully pinning down the "all commands" claim from Spec 3.2. *(Spec 3.2)*

### 4.13 Workflow-Level Version Checking

**Spec refs:** 3.2

- **T-VER-01**: Workflow `package.json` declares a loopx range satisfied by the running version → execution proceeds, no warning. *(Spec 3.2)*
- **T-VER-02**: Workflow `package.json` declares a loopx range NOT satisfied → warning on stderr, execution continues (non-fatal). *(Spec 3.2)*
- **T-VER-03**: Warning occurs only on first entry to a workflow. Re-entering the same workflow (via loop reset or goto) does not repeat the warning. *(Spec 3.2)*
- **T-VER-04**: Cross-workflow first-entry warning. Starting workflow has no version declaration. Goto to a second workflow that declares an unsatisfied range → warning emitted on first entry to second workflow. *(Spec 3.2)*
- **T-VER-04a**: Cross-workflow alternating re-entry version-warning deduplication. Create two workflows: `.loopx/alpha/index.sh` and `.loopx/beta/index.sh`, both with `package.json` declaring an unsatisfied loopx range. Set up a multi-iteration loop where execution alternates: `alpha:index` → goto `beta:index` → (no goto, reset) → `alpha:index` → goto `beta:index` → stop. Assert: (a) stderr contains exactly one version mismatch warning for `alpha` and exactly one for `beta`, (b) no duplicate warnings appear despite both workflows being entered twice. This makes the ADR-0003 cross-workflow "first entry only" intent explicit — T-VER-03 covers single-workflow re-entry and T-VER-04 covers first entry to a second workflow, but neither covers the full A→B→A→B alternation pattern. *(Spec 3.2)*
- **T-VER-05**: Starting workflow checked before first iteration. *(Spec 3.2)*
- **T-VER-06**: `-n 0` skips workflow version warnings. Set up workflow with unsatisfied version range. Assert no warning on stderr. *(Spec 3.2)*
- **T-VER-07**: Workflow `package.json` unreadable → warning, execution continues. **Conditional on `process.getuid() !== 0`.** *(Spec 3.2)*
- **T-VER-07a**: Runtime `package.json` failure warning follows "first entry only" dedupe. Create a workflow with invalid JSON in its `package.json`. Run a loop that re-enters the workflow multiple times (e.g., via loop reset). Assert that the `package.json` failure warning appears exactly once on stderr, not on each re-entry. This locks down the same "first entry only" rule that T-VER-03 tests for version mismatch warnings, applied to `package.json` failure warnings (unreadable, invalid JSON, invalid semver range). *(Spec 3.2)*
- **T-VER-07b**: Runtime `package.json` failure warning follows "first entry only" dedupe for invalid semver ranges. Create a workflow with a valid `package.json` containing an invalid semver range for `loopx` (e.g., `"loopx": "not-a-range"`). Run a loop that re-enters the workflow multiple times. Assert that the invalid-semver warning appears exactly once on stderr. This is the invalid-semver counterpart to T-VER-07a (invalid JSON). *(Spec 3.2)*
- **T-VER-07c**: Runtime `package.json` failure warning follows "first entry only" dedupe for unreadable workflow `package.json`. Create a workflow with an unreadable `package.json` (e.g., mode 000). Run a loop that re-enters the workflow multiple times (e.g., via loop reset). Assert that the unreadable-file warning appears exactly once on stderr, not on each re-entry. This is the unreadable-file counterpart to T-VER-07a (invalid JSON) and T-VER-07b (invalid semver). **Conditional on `process.getuid() !== 0`.** *(Spec 3.2)*
- **T-VER-07d**: Cross-workflow `package.json` failure warning via goto. Create two workflows: `.loopx/clean/index.sh` (no `package.json` or a valid one with no loopx declaration) and `.loopx/broken/index.sh` with a `package.json` containing invalid JSON (e.g., `{broken`). Set up a loop where `clean:index` emits a goto to `broken:index`, and `broken:index` completes without goto (triggering loop reset). Run for multiple iterations. Assert: (a) the invalid-JSON warning for `broken` is emitted exactly once on stderr (on first entry via goto), (b) no warning is emitted for `clean`, and (c) execution continues normally (the invalid `package.json` does not block the goto transition). This covers the failure-warning path when a workflow is first entered cross-workflow — T-VER-07a covers re-entry deduplication within a single workflow, and T-VER-04 covers version-mismatch warnings on cross-workflow goto, but neither covers `package.json` failure warnings on cross-workflow first entry. *(Spec 3.2)*
- **T-VER-07e**: Cross-workflow `package.json` failure warning via goto — unreadable variant. Same structure as T-VER-07d: create `.loopx/clean/index.sh` (no `package.json` or a valid one with no loopx declaration) and `.loopx/broken/index.sh` with an unreadable `package.json` (mode 000). Set up a loop where `clean:index` gotos `broken:index`, and `broken:index` completes without goto (triggering loop reset). Run for multiple iterations. Assert: (a) the unreadable-file warning for `broken` is emitted exactly once on stderr (on first entry via goto), (b) no warning is emitted for `clean`, and (c) execution continues normally. This is the unreadable-file counterpart to T-VER-07d (invalid JSON) — T-VER-07c covers re-entry dedupe for unreadable files within a single workflow, but not the cross-workflow first-entry path. **Conditional on `process.getuid() !== 0`.** *(Spec 3.2)*
- **T-VER-07f**: Cross-workflow `package.json` failure warning via goto — invalid semver range variant. Same structure as T-VER-07d: create `.loopx/clean/index.sh` (no `package.json` or a valid one with no loopx declaration) and `.loopx/broken/index.sh` with a `package.json` containing `{ "dependencies": { "loopx": "not-a-range!!!" } }` (valid JSON but invalid semver range). Set up a loop where `clean:index` gotos `broken:index`, and `broken:index` completes without goto (triggering loop reset). Run for multiple iterations. Assert: (a) the invalid-semver warning for `broken` is emitted exactly once on stderr (on first entry via goto), (b) no warning is emitted for `clean`, and (c) execution continues normally. This is the invalid-semver counterpart to T-VER-07d (invalid JSON) and T-VER-07e (unreadable). *(Spec 3.2)*
- **T-VER-08**: Workflow `package.json` invalid JSON → warning, execution continues. *(Spec 3.2)*
- **T-VER-09**: Workflow `package.json` invalid semver range → warning, execution continues. *(Spec 3.2)*
- **T-VER-10**: `dependencies` range wins over `devDependencies` when both are present. Set up a workflow `package.json` with `dependencies.loopx` having a satisfied range and `devDependencies.loopx` having an unsatisfied range → no version mismatch warning on stderr. Reverse the ranges (`dependencies.loopx` unsatisfied, `devDependencies.loopx` satisfied) → version mismatch warning on stderr, execution continues. *(Spec 3.2)*
- **T-VER-10a**: Runtime: `dependencies.loopx` has an invalid semver range (e.g., `"not-a-range"`), `devDependencies.loopx` has a valid but unsatisfied range (e.g., `">=999.0.0"`). Assert: (a) stderr contains a warning about the invalid semver range in `dependencies`, (b) stderr does NOT contain a version mismatch warning (the version check is skipped, not failed), and (c) execution continues. The `dependencies` field takes precedence — when it is present but invalid, loopx warns and skips version checking entirely. It must not fall back to `devDependencies.loopx`. *(Spec 3.2)*
- **T-VER-10b**: Runtime: `dependencies.loopx` has a valid, satisfied range, `devDependencies.loopx` has an invalid semver range (e.g., `"not-a-range"`). Assert: (a) no version mismatch warning on stderr, (b) no invalid-semver warning on stderr, and (c) execution continues normally. When `dependencies.loopx` is present, `devDependencies.loopx` is ignored entirely — it is not read or validated, even if malformed. T-VER-10 proves precedence with two valid ranges; T-VER-10a proves no fallback when `dependencies` is invalid. This test closes the converse gap: `dependencies` is valid and satisfied, so `devDependencies` must be invisible regardless of its content. *(Spec 3.2)*
- **T-VER-11**: `optionalDependencies` ignored at workflow level. Workflow `package.json` declares `loopx` only in `optionalDependencies` with an unsatisfied range → no version warning at runtime. *(Spec 3.2)*
- **T-VER-11a**: Runtime: `optionalDependencies.loopx` with an invalid semver range (e.g., `"not-a-range"`) is ignored. Workflow `package.json` declares `loopx` only in `optionalDependencies` with an invalid semver range — no `dependencies.loopx` or `devDependencies.loopx` present. Assert: (a) exit code 0, (b) no version mismatch warning on stderr, and (c) no invalid-semver or `package.json` warning on stderr. T-VER-11 covers a valid-but-unsatisfied `optionalDependencies.loopx`; this extends coverage to the malformed case, proving the field is fully invisible at the workflow level — it is not read or validated, even when malformed. An implementation that read `optionalDependencies.loopx` only to emit invalid-semver warnings would fail this test. *(Spec 3.2)*
- **T-VER-11b**: Runtime: `peerDependencies.loopx` is ignored at the workflow level. Workflow `package.json` declares `loopx` only in `peerDependencies` with a valid but unsatisfied range (e.g., `">=999.0.0"`) — no `dependencies.loopx`, `devDependencies.loopx`, or `optionalDependencies.loopx` present. Create `.loopx/ralph/index.sh` and run `loopx run -n 1 ralph`. Assert: (a) exit code 0, (b) no version mismatch warning on stderr, and (c) no `package.json`-related warning on stderr. Per SPEC 3.2, workflow-level version checking reads only `dependencies` and `devDependencies` (with `optionalDependencies` explicitly ignored at the workflow level). T-VER-11 / T-VER-11a prove `optionalDependencies` is ignored at runtime; this test proves `peerDependencies` is also outside the checked set — the field is fully invisible at the workflow level and must not trigger a mismatch warning. **Classification:** derived-spec coverage, not core ADR-0003 acceptance coverage. SPEC 3.2 enumerates the workflow-level checked fields explicitly (`dependencies`, `devDependencies`; with `optionalDependencies` explicitly excluded) but does not explicitly discuss `peerDependencies`; this test validates an exclusion that follows from the enumerated-list semantics rather than from a direct ADR-0003 statement. Keep as a useful boundary test, but do not gate ADR-0003 acceptance on it. *(Spec 3.2)*
- **T-VER-11c**: Runtime: `optionalDependencies.loopx` does not rescue an unsatisfied `dependencies.loopx`. Workflow `package.json` declares `loopx` in BOTH `dependencies` (with an unsatisfied range, e.g., `">=999.0.0"`) AND `optionalDependencies` (with a satisfied range, e.g., `"*"` or the running version's exact value) — no `devDependencies.loopx`. Create `.loopx/ralph/index.sh` and run `loopx run -n 1 ralph`. Assert: (a) exit code 0, and (b) stderr contains a version mismatch warning for `ralph`. Because `optionalDependencies` is intentionally not checked at the workflow level (Spec 3.2), its satisfied range must not suppress the `dependencies` mismatch warning. T-VER-11 / T-VER-11a prove `optionalDependencies` alone is ignored at runtime, and T-VER-14a pins down the mixed case for `devDependencies` + `optionalDependencies`; this test closes the symmetric gap for `dependencies` + `optionalDependencies`, covering the highest-precedence workflow-level version-check field (Spec 3.2: `dependencies` wins over `devDependencies`) in the mixed-field configuration. An implementation that wrongly merged `optionalDependencies` into the workflow-level check would suppress the mismatch warning and fail this test. *(Spec 3.2)*
- **T-VER-12**: Install-time version checking: `dependencies` range wins over `devDependencies` when both are present in a workflow's `package.json`. Set up `dependencies.loopx` with a satisfied range and `devDependencies.loopx` with an unsatisfied range → install succeeds (no version mismatch error). Reverse the ranges → install fails. *(Spec 3.2, 10.6)*
- **T-VER-12a**: Install-time: `dependencies.loopx` has an invalid semver range, `devDependencies.loopx` has a valid but unsatisfied range. Assert: (a) stderr contains a warning about the invalid semver range in `dependencies`, (b) install succeeds (the version check is skipped, not failed — invalid semver does not block install per Spec 3.2), and (c) no version mismatch error is reported. The `dependencies` field takes precedence — when it is present but invalid, the version check is skipped entirely. It must not fall back to `devDependencies.loopx`. This is the install-time counterpart to T-VER-10a. *(Spec 3.2, 10.6)*
- **T-VER-12b**: Install-time: `dependencies.loopx` has a valid, satisfied range, `devDependencies.loopx` has an invalid semver range (e.g., `"not-a-range"`). Assert: (a) install succeeds, (b) no invalid-semver warning on stderr, and (c) no version mismatch error. When `dependencies.loopx` is present, `devDependencies.loopx` is ignored entirely at install time — it is not read or validated, even if malformed. This is the install-time counterpart to T-VER-10b. *(Spec 3.2, 10.6)*
- **T-VER-13**: Install-time version checking: `optionalDependencies.loopx` is ignored at the workflow level. Workflow `package.json` declares `loopx` only in `optionalDependencies` with an unsatisfied range → install succeeds (no version check performed). *(Spec 3.2, 10.6)*
- **T-VER-13a**: Install-time: `optionalDependencies.loopx` with an invalid semver range (e.g., `"not-a-range"`) is ignored. A workflow source's `package.json` declares `loopx` only in `optionalDependencies` with an invalid semver range — no `dependencies.loopx` or `devDependencies.loopx` present. Run `loopx install <source>`. Assert: (a) exit code 0, (b) the workflow is installed, (c) no version mismatch error, and (d) no invalid-semver or `package.json` warning on stderr. This is the install-time counterpart to T-VER-11a, extending T-VER-13 (valid-but-unsatisfied) to the malformed case. Proves `optionalDependencies.loopx` is fully invisible at the workflow level at install time as well. *(Spec 3.2, 10.6)*
- **T-VER-13b**: Install-time: `peerDependencies.loopx` is ignored at the workflow level. A workflow source's `package.json` declares `loopx` only in `peerDependencies` with a valid but unsatisfied range (e.g., `">=999.0.0"`) — no `dependencies.loopx`, `devDependencies.loopx`, or `optionalDependencies.loopx` present. Run `loopx install <source>`. Assert: (a) exit code 0, (b) the workflow is installed, (c) no version mismatch error, and (d) no `package.json`-related warning on stderr. Per SPEC 3.2, install-time version checking uses the same rules as runtime — only `dependencies` and `devDependencies` are read. T-VER-13 / T-VER-13a prove `optionalDependencies` is ignored at install time; this is the `peerDependencies` counterpart and the install-time mirror of T-VER-11b, locking down that the excluded-dependency-field set is the same at install time as at runtime. **Classification:** derived-spec coverage, not core ADR-0003 acceptance coverage. SPEC 3.2 enumerates the workflow-level checked fields explicitly (`dependencies`, `devDependencies`; with `optionalDependencies` explicitly excluded) but does not explicitly discuss `peerDependencies`; this test validates an exclusion that follows from the enumerated-list semantics rather than from a direct ADR-0003 statement. Keep as a useful boundary test, but do not gate ADR-0003 acceptance on it. *(Spec 3.2, 10.6)*
- **T-VER-13c**: Install-time: `optionalDependencies.loopx` does not rescue an unsatisfied `dependencies.loopx`. Workflow source's `package.json` declares `loopx` in BOTH `dependencies` (with an unsatisfied range, e.g., `">=999.0.0"`) AND `optionalDependencies` (with a satisfied range, e.g., `"*"` or the running version's exact value) — no `devDependencies.loopx`. Run `loopx install <source>`. Assert: (a) exit code 1 with a version mismatch error, and (b) the workflow is not installed. With `-y`, the install succeeds (override). This is the install-time counterpart to T-VER-11c — the "ignore `optionalDependencies` at the workflow level" rule applies identically at install time (Spec 3.2 and 10.6), and a satisfied `optionalDependencies.loopx` must not suppress the install-blocking mismatch detected via `dependencies.loopx`. T-VER-13 / T-VER-13a prove `optionalDependencies` alone is ignored at install time, and T-VER-15a pins down the mixed case for `devDependencies` + `optionalDependencies` at install time; this test closes the symmetric gap for `dependencies` + `optionalDependencies` at install time, covering the highest-precedence workflow-level version-check field (Spec 3.2: `dependencies` wins over `devDependencies`) in the mixed-field configuration. *(Spec 3.2, 10.6)*
- **T-VER-14**: Runtime version checking: `devDependencies.loopx` only (no `dependencies.loopx`). Workflow `package.json` declares `loopx` only in `devDependencies` with an unsatisfied range → warning on stderr, execution continues. This proves the `devDependencies`-only path works independently of the `dependencies`-over-`devDependencies` precedence rule tested in T-VER-10. *(Spec 3.2)*
- **T-VER-14a**: Runtime: `optionalDependencies.loopx` does not rescue an unsatisfied `devDependencies.loopx`. Workflow `package.json` declares `loopx` in BOTH `devDependencies` (with an unsatisfied range, e.g., `">=999.0.0"`) AND `optionalDependencies` (with a satisfied range, e.g., `"*"` or the running version's exact value) — no `dependencies.loopx`. Create `.loopx/ralph/index.sh` and run `loopx run -n 1 ralph`. Assert: (a) exit code 0, and (b) stderr contains a version mismatch warning for `ralph`. Because `optionalDependencies` is intentionally not checked at the workflow level (Spec 3.2), its satisfied range must not suppress the `devDependencies` mismatch warning. T-VER-11 / T-VER-11a prove `optionalDependencies` alone is ignored, and T-VER-14 proves `devDependencies`-only unsatisfied warns; this test pins down the mixed case where a satisfied `optionalDependencies` could appear to "rescue" the check if an implementation wrongly merged fields. *(Spec 3.2)*
- **T-VER-15**: Install-time version checking: `devDependencies.loopx` only (no `dependencies.loopx`). Workflow `package.json` declares `loopx` only in `devDependencies` with an unsatisfied range → install refused with version mismatch error. This proves the `devDependencies`-only install path works independently of the precedence rule tested in T-VER-12. *(Spec 3.2, 10.6)*
- **T-VER-15a**: Install-time: `optionalDependencies.loopx` does not rescue an unsatisfied `devDependencies.loopx`. Workflow source's `package.json` declares `loopx` in BOTH `devDependencies` (with an unsatisfied range, e.g., `">=999.0.0"`) AND `optionalDependencies` (with a satisfied range, e.g., `"*"` or the running version's exact value) — no `dependencies.loopx`. Run `loopx install <source>`. Assert: (a) exit code 1 with a version mismatch error, and (b) the workflow is not installed. With `-y`, the install succeeds (override). This is the install-time counterpart to T-VER-14a — the "ignore `optionalDependencies` at the workflow level" rule applies identically at install time (Spec 3.2 and 10.6), and a satisfied `optionalDependencies.loopx` must not suppress the install-blocking mismatch detected via `devDependencies.loopx`. T-VER-13 / T-VER-13a prove `optionalDependencies` alone is ignored at install time, and T-VER-15 proves `devDependencies`-only unsatisfied blocks install; this test pins down the mixed case. *(Spec 3.2, 10.6)*
- **T-VER-16**: Runtime: workflow has a valid `package.json` with no `loopx` declared in any dependency field (e.g., `{ "name": "my-workflow", "version": "1.0.0" }`) → no version check is performed, no warning emitted. Execution proceeds normally. This explicitly tests the "valid JSON, no `loopx` dependency declared → no version check" rule from Spec 3.2. *(Spec 3.2)*
- **T-VER-17**: Install-time: workflow source has a valid `package.json` with no `loopx` declared in any dependency field → no version check is performed, install succeeds without version-related errors or warnings. *(Spec 3.2, 10.6)*
- **T-VER-18**: Unentered sibling workflows are not version-checked. Create `.loopx/good/index.sh` (the starting workflow, no `package.json`) and `.loopx/sibling/index.sh` with a `package.json` declaring a loopx range NOT satisfied by the running version. Run `loopx run -n 1 good` (the starting workflow completes without ever entering `sibling`). Assert: (a) exit code 0, and (b) no version mismatch warning on stderr for `sibling`. Version checks are entry-scoped — only workflows actually entered during the loop have their `package.json` checked. *(Spec 3.2)*
- **T-VER-18a**: Unentered sibling workflow with broken `package.json` emits no warning. Create `.loopx/good/index.sh` (the starting workflow, no `package.json`) and `.loopx/sibling/index.sh` with a `package.json` containing invalid JSON (e.g., `{{{INVALID`). Run `loopx run -n 1 good`. Assert: (a) exit code 0, and (b) stderr contains no `package.json`-related warnings (no JSON parse warning, no version warning). T-VER-18 covers an unentered sibling with an unsatisfied range; this test extends coverage to the `package.json` failure-warning path (invalid JSON), proving that `package.json` failure warnings are also entry-scoped — the sibling's `package.json` is never read because the sibling workflow is never entered. *(Spec 3.2)*
- **T-VER-19**: `loopx run -h` does not perform workflow version or `package.json` checks. Create `.loopx/ralph/index.sh` with a `package.json` declaring a loopx range NOT satisfied by the running version. Run `loopx run -h`. Assert: (a) help output is displayed, (b) exit code 0, and (c) stderr contains no version mismatch warnings. Version checking is entry-scoped — `run -h` performs discovery and validation (names, collisions) but does not enter any workflow, so version checks do not run. *(Spec 3.2, 11.2)*
- **T-VER-19a**: `loopx run -h` does not read workflow `package.json` — unreadable file variant. Create `.loopx/ralph/index.sh` with a `package.json` set to mode 000 (unreadable). Run `loopx run -h`. Assert: (a) help output is displayed, (b) exit code 0, and (c) stderr contains no `package.json`-related read warnings. An implementation that wrongly reads workflow `package.json` during help would emit a read-failure warning; this test catches that. **Conditional on `process.getuid() !== 0`.** *(Spec 3.2, 11.2)*
- **T-VER-19b**: `loopx run -h` does not read workflow `package.json` — invalid JSON variant. Create `.loopx/ralph/index.sh` with a `package.json` containing `{{{INVALID`. Run `loopx run -h`. Assert: (a) help output is displayed, (b) exit code 0, and (c) stderr contains no JSON parse warnings. An implementation that wrongly reads workflow `package.json` during help would emit a parse-failure warning. *(Spec 3.2, 11.2)*
- **T-VER-19c**: `loopx run -h` does not read workflow `package.json` — invalid semver variant. Create `.loopx/ralph/index.sh` with a `package.json` containing `{ "dependencies": { "loopx": "not-a-range!!!" } }`. Run `loopx run -h`. Assert: (a) help output is displayed, (b) exit code 0, and (c) stderr contains no semver/version warnings. An implementation that wrongly reads workflow `package.json` during help would emit an invalid-semver warning. *(Spec 3.2, 11.2)*
- **T-VER-20**: Workflow `package.json` is not re-read after first entry (mutation test). Create `.loopx/ralph/index.sh` with a `package.json` declaring a loopx range SATISFIED by the running version. Set up a multi-iteration loop where the script mutates its own `package.json` to an UNSATISFIED range after the first iteration (e.g., rewrites the loopx version field to `">=999.0.0"`), then re-enters the workflow (via loop reset). Assert: no version mismatch warning appears on any iteration, proving the file was not re-read after first entry. This goes beyond T-VER-03 (which proves the warning is not repeated) by proving the file itself is not re-checked — if the implementation re-read `package.json` on re-entry, the mutated range would trigger a new warning. *(Spec 3.2)*
- **T-VER-20a**: Workflow `package.json` is not re-read after first entry — absent-then-broken mutation. Create `.loopx/ralph/index.sh` with no `package.json` in the workflow directory at loop start. Set up a multi-iteration loop where the script creates `.loopx/ralph/package.json` containing invalid JSON (e.g., `{broken`) after its first iteration, then re-enters the workflow via loop reset. Assert: no `package.json` failure warning (invalid-JSON parse warning) appears on stderr on later iterations, proving the file itself is not re-read after first entry. T-VER-20 proves "not re-read" for the satisfied-then-unsatisfied version-range mutation path; this test proves "not re-read" for the absent-then-broken `package.json` failure path — a distinct code path where the initial first-entry read found no file at all, so an implementation could plausibly retry the read on re-entry and emit a new parse warning. This closes the `package.json`-failure branch of the Spec 3.2 "subsequent entries do not re-read `package.json` or repeat warnings" rule. *(Spec 3.2)*
- **T-VER-21**: Workflow with no `package.json` runs with no version-check warning. Create `.loopx/ralph/index.sh` with no `package.json` in the workflow directory. Run `loopx run -n 1 ralph`. Assert: (a) exit code 0, (b) stderr contains no version-related warnings or `package.json`-related warnings. This locks down the "normal case" from Spec 3.2: absent `package.json` means no version check is performed and no warnings are emitted. An implementation that wrongly warns on missing `package.json` would fail this test. *(Spec 3.2)*
- **T-VER-22**: Workflow with no `package.json` installs with no version-related warning. Set up a single-workflow install source with no `package.json`. Run `loopx install <source>`. Assert: (a) exit code 0, (b) stderr contains no version-related warnings or `package.json`-related warnings, (c) the workflow is installed in `.loopx/`. This is the install-time counterpart to T-VER-21. *(Spec 3.2, 10.6)*
- **T-VER-23**: A stray `.loopx/package.json` is ignored for runtime version checking. Create `.loopx/package.json` containing `{ "dependencies": { "loopx": ">=999.0.0" } }` (an unsatisfied range). Create `.loopx/ralph/index.sh` with no workflow-level `package.json`. Run `loopx run -n 1 ralph`. Assert: (a) exit code 0, and (b) no version mismatch warning on stderr. The `.loopx/package.json` file is not a recognized manifest — version authority lives only in the project root `package.json` (for delegation) and each workflow's own `package.json` (for runtime/install-time validation). *(Spec 3.2)*
- **T-VER-23a**: A pre-existing stray `.loopx/package.json` is ignored at install time. In the target project, create `.loopx/package.json` containing `{ "dependencies": { "loopx": ">=999.0.0" } }` (an unsatisfied range) **before** running install. Then run `loopx install <single-workflow-source>` where the source has no `package.json`. Assert: (a) exit code 0, (b) the workflow is installed at `.loopx/<name>/`, (c) the stray `.loopx/package.json` is preserved unchanged, and (d) no version mismatch or `package.json` warnings on stderr. The `.loopx/package.json` is not a recognized manifest at install time either — install only reads and validates each workflow's own `package.json`. This is the install-time counterpart to T-VER-23 (runtime). T-INST-97b proves install does not *create* `.loopx/package.json`; this test proves install does not *read* a pre-existing one. *(Spec 3.2, 10.6)*
- **T-VER-24**: No version/package warning when the starting target cannot be entered. Create `.loopx/ralph/check.sh` (valid workflow with no `index` script) and `.loopx/ralph/package.json` containing `{ "dependencies": { "loopx": ">=999.0.0" } }` (an unsatisfied range). Run `loopx run ralph`. Assert: (a) exit code 1 with an error about missing default entry point (`index`), and (b) stderr contains no version mismatch or `package.json`-related warnings. Target resolution (Spec 7.1 step 3) fails before workflow-entry version checking (step 5) is reached — the workflow is never entered, so its `package.json` is never read. *(Spec 7.1, 3.2)*
- **T-VER-24a**: No `package.json` failure warning when the starting target cannot be entered — broken JSON variant. Create `.loopx/ralph/check.sh` (valid workflow with no `index` script) and `.loopx/ralph/package.json` containing `{{{INVALID`. Run `loopx run ralph`. Assert: (a) exit code 1 with an error about missing default entry point, and (b) stderr contains no JSON parse warnings. This extends T-VER-24 from the unsatisfied-range path to the invalid-JSON `package.json` failure path. *(Spec 7.1, 3.2)*
- **T-VER-24b**: No version/package warning when an explicit `workflow:script` start target names a missing script — unsatisfied range variant. Create `.loopx/ralph/index.sh` (valid workflow, `index` present) and `.loopx/ralph/package.json` containing `{ "dependencies": { "loopx": ">=999.0.0" } }` (an unsatisfied range). Run `loopx run ralph:missing` (explicit target where `missing` is not a script in `ralph`). Assert: (a) exit code 1 with an error about the missing script `missing` in workflow `ralph`, and (b) stderr contains no version mismatch or `package.json`-related warnings for `ralph`. Target resolution fails before workflow-entry version checking runs — the workflow is never entered, so its `package.json` is never read. This is the explicit-`workflow:script`-start counterpart to T-VER-24 (bare target missing default entry) and T-VER-25 (goto target missing script). ADR-0003 made explicit `workflow:script` start targets first-class, so the ordering rule that target resolution precedes version checking must hold for them too. *(Spec 7.1, 3.2, 4.1)*
- **T-VER-24c**: No `package.json` failure warning when an explicit `workflow:script` start target names a missing script — broken JSON variant. Same setup as T-VER-24b but `.loopx/ralph/package.json` contains `{{{INVALID` (broken JSON) instead of an unsatisfied range. Run `loopx run ralph:missing`. Assert: (a) exit code 1 with missing-script error for `missing` in `ralph`, and (b) stderr contains no JSON parse warnings for `ralph`. This extends T-VER-24b from the unsatisfied-range path to the invalid-JSON `package.json` failure path, mirroring the T-VER-24 → T-VER-24a split for the bare-target missing-default-entry case and the T-VER-25 → T-VER-25a split for the goto-target-missing-script case. *(Spec 7.1, 3.2, 4.1)*
- **T-VER-24d**: No version/package warning when an explicit `:index` start target names a non-existent `index` in a workflow without one — unsatisfied range variant. Create `.loopx/ralph/check.sh` (valid workflow with no `index.*` script) and `.loopx/ralph/package.json` containing `{ "dependencies": { "loopx": ">=999.0.0" } }` (an unsatisfied range). Run `loopx run ralph:index`. Assert: (a) exit code 1 with an error about the missing script `index` in workflow `ralph`, and (b) stderr contains no version mismatch or `package.json`-related warnings for `ralph`. Target resolution fails before workflow-entry version checking runs — the workflow is never entered, so its `package.json` is never read. This is the **combined** case that T-VER-24 (bare target, missing default entry), T-VER-24b (explicit `workflow:missing` target), and T-CLI-109a / T-API-20j2 / T-API-45a (plain error shape for `workflow:index` with no index) do not jointly cover: the explicit `:index` target on a workflow that has no index AND a workflow-level version declaration. ADR-0003 makes `index` special only when the script portion is omitted, so the explicit `:index` path must enforce the same "target resolution precedes version checking" ordering as any other missing script. *(Spec 7.1, 3.2, 4.1)*
- **T-VER-24e**: No `package.json` failure warning when an explicit `:index` start target names a non-existent `index` in a workflow without one — broken JSON variant. Same setup as T-VER-24d but `.loopx/ralph/package.json` contains `{{{INVALID` (broken JSON) instead of an unsatisfied range. Run `loopx run ralph:index`. Assert: (a) exit code 1 with an error about the missing script `index` in workflow `ralph`, and (b) stderr contains no JSON parse warnings for `ralph`. This extends T-VER-24d from the unsatisfied-range path to the invalid-JSON `package.json` failure path, mirroring the T-VER-24 → T-VER-24a and T-VER-24b → T-VER-24c splits. Together T-VER-24d/24e close the combined-case gap across both `package.json` failure branches for the explicit-`:index`-on-no-index-workflow path. *(Spec 7.1, 3.2, 4.1)*
- **T-VER-25**: No version/package warning when a goto target script does not exist. Create `.loopx/start/index.sh` that outputs `{ "goto": "other:missing" }`. Create `.loopx/other/index.sh` (valid workflow) with `.loopx/other/package.json` containing `{ "dependencies": { "loopx": ">=999.0.0" } }` (an unsatisfied range). Run `loopx run -n 2 start`. Assert: (a) exit code 1 with an error about missing script `missing` in workflow `other`, and (b) stderr contains no version mismatch or `package.json`-related warnings for `other`. Goto target resolution (Spec 7.1 step 11.d) fails before the first-entry version check (step 11.e) — the target workflow is never entered, so its `package.json` is never read. *(Spec 7.1, 3.2)*
- **T-VER-25a**: No `package.json` failure warning when a goto target script does not exist — broken JSON variant. Same setup as T-VER-25 but `.loopx/other/package.json` contains `{{{INVALID` instead of an unsatisfied range. Assert: (a) exit code 1 with missing-script error, and (b) no JSON parse warnings on stderr for `other`. *(Spec 7.1, 3.2)*
- **T-VER-25b**: No version/package warning when a goto emits `workflow:index` but the target workflow has no `index` — unsatisfied range variant. Create `.loopx/start/index.sh` that outputs `{ "goto": "other:index" }`. Create `.loopx/other/check.sh` (valid workflow with no `index.*` script) and `.loopx/other/package.json` containing `{ "dependencies": { "loopx": ">=999.0.0" } }` (an unsatisfied range). Run `loopx run -n 2 start`. Assert: (a) exit code 1 with an error about the missing script `index` in workflow `other`, and (b) stderr contains no version mismatch or `package.json`-related warnings for `other`. Goto target resolution fails before the first-entry version check — the target workflow is never entered, so its `package.json` is never read. This is the **combined** case that T-LOOP-31c (generic missing `other:index` goto error shape) and T-VER-25 / T-VER-25a (generic missing goto script `other:missing` with unsatisfied range / broken JSON) do not jointly cover: the specific `:index` goto target on a workflow that has no index AND a workflow-level version declaration. ADR-0003 makes `index` special only when the script portion is omitted, and that rule must hold on the cross-workflow goto path as well — so the qualified `workflow:index` goto target into a no-index workflow must follow the ordinary missing-script ordering rule, never entering the workflow and never emitting version/package warnings for it. *(Spec 7.1, 3.2, 2.2, 4.1)*
- **T-VER-25c**: No `package.json` failure warning when a goto emits `workflow:index` but the target workflow has no `index` — broken JSON variant. Same setup as T-VER-25b but `.loopx/other/package.json` contains `{{{INVALID` (broken JSON) instead of an unsatisfied range. Run `loopx run -n 2 start`. Assert: (a) exit code 1 with an error about the missing script `index` in workflow `other`, and (b) stderr contains no JSON parse warnings for `other`. This extends T-VER-25b from the unsatisfied-range path to the invalid-JSON `package.json` failure path, mirroring the T-VER-25 → T-VER-25a split. Together T-VER-25b/25c close the combined-case gap across both `package.json` failure branches for the goto-`workflow:index`-into-no-index-workflow path. *(Spec 7.1, 3.2, 2.2, 4.1)*
- **T-VER-26**: Runtime version check fires on explicit script entry into a no-index workflow. Create `.loopx/ralph/check.sh` (no `index` script) with a `package.json` declaring an unsatisfied loopx range. `loopx run -n 1 ralph:check` → (a) warning on stderr about version mismatch, (b) exit code 0, (c) `check.sh` executed (marker file written). This combines no-index (T-CLI-110, T-DISC-19) with version checking (T-VER-02) — both are individually covered, but the combination tests that version checking still runs when entry is via an explicit script in a workflow without a default entry point. *(Spec 3.2, 4.1, 2.1)*
- **T-VER-26a**: Runtime `package.json` failure warning on explicit-script entry into a no-index workflow — invalid JSON variant. Create `.loopx/ralph/check.sh` (no `index` script) and `.loopx/ralph/package.json` containing invalid JSON (e.g., `{broken`). `loopx run -n 1 ralph:check` → (a) warning on stderr about the invalid `package.json`, (b) exit code 0, (c) `check.sh` executed (marker file written). Extends T-VER-26 (unsatisfied range on explicit entry into a no-index workflow) to the invalid-JSON `package.json` failure path. T-VER-08 covers invalid JSON on normal (bare) workflow entry; this test pins down that the same warning fires when entering via an explicit `workflow:script` target in a workflow without a default entry point. This is the normal-execution counterpart to the explicit-target `-n 0` coverage in T-CLI-119i. *(Spec 3.2, 4.1)*
- **T-VER-26b**: Runtime `package.json` failure warning on explicit-script entry into a no-index workflow — invalid semver range variant. Same structure as T-VER-26a, but `.loopx/ralph/package.json` contains `{ "dependencies": { "loopx": "not-a-range!!!" } }` (valid JSON, invalid semver range). Assert: (a) warning on stderr about the invalid semver range, (b) exit code 0, (c) `check.sh` executed. Invalid-semver counterpart to T-VER-26a; normal-execution counterpart to T-CLI-119j. T-VER-09 covers invalid semver on normal (bare) workflow entry. *(Spec 3.2, 4.1)*
- **T-VER-26c**: Runtime `package.json` failure warning on explicit-script entry into a no-index workflow — unreadable variant. Same structure as T-VER-26a, but `.loopx/ralph/package.json` is unreadable (e.g., mode 000). Assert: (a) warning on stderr about the unreadable `package.json`, (b) exit code 0, (c) `check.sh` executed. Unreadable-file counterpart to T-VER-26a and T-VER-26b; normal-execution counterpart to T-CLI-119k. T-VER-07 covers unreadable on normal (bare) workflow entry. **Conditional on `process.getuid() !== 0`.** *(Spec 3.2, 4.1)*
- **T-VER-27**: Cross-workflow first-entry version warning for a no-index workflow entered via qualified goto. Create two workflows: `.loopx/alpha/index.sh` (no `package.json`, emits `goto:"beta:check"`) and `.loopx/beta/check.sh` (no `index` script) with `package.json` declaring an unsatisfied loopx range. `loopx run -n 2 alpha`. Assert: (a) `beta:check` executes (marker file), (b) stderr contains a version mismatch warning for `beta` on first entry, and (c) no warning for `alpha`. This combines cross-workflow goto into a no-index workflow (T-LOOP-30a) with version checking (T-VER-04) — both covered separately, but the combination tests that the first-entry version check fires when the transition target is an explicit script in a workflow that has no default entry point. *(Spec 3.2, 2.2, 4.1)*
- **T-VER-27a**: Cross-workflow first-entry `package.json` failure warning for a no-index workflow entered via qualified goto — invalid JSON variant. Create two workflows: `.loopx/clean/index.sh` (no `package.json` or a valid one with no loopx declaration, emits `goto:"broken:check"`) and `.loopx/broken/check.sh` (no `index` script) with `package.json` containing invalid JSON (e.g., `{broken`). Set up a loop where `clean:index` gotos `broken:check`, and `broken:check` completes without goto (triggering loop reset). Run for multiple iterations (e.g., `-n 4`). Assert: (a) `broken:check` executes (marker file), (b) stderr contains exactly one invalid-JSON warning for `broken` (emitted on first entry via goto), (c) no warning is emitted for `clean`, and (d) execution continues normally. T-VER-07d covers cross-workflow goto into `broken:index` (index present); T-VER-27 covers cross-workflow goto into a no-index workflow with version mismatch; this test is the combination — cross-workflow goto into a no-index workflow (entered via explicit `workflow:script` qualified goto) with an invalid-JSON `package.json`. ADR-0003 made explicit `workflow:script` entry into no-index workflows a first-class path, so `package.json` failure warnings must fire on this path too. *(Spec 3.2, 2.2, 4.1)*
- **T-VER-27b**: Cross-workflow first-entry `package.json` failure warning for a no-index workflow entered via qualified goto — unreadable variant. Same structure as T-VER-27a, but `.loopx/broken/package.json` is set to mode 000 (unreadable) instead of containing invalid JSON. Assert: (a) `broken:check` executes (marker file), (b) stderr contains exactly one unreadable-file warning for `broken` (emitted on first entry via goto), (c) no warning for `clean`, and (d) execution continues normally. Unreadable-file counterpart to T-VER-27a (invalid JSON) — T-VER-07e covers the same `package.json` failure mode on cross-workflow goto into a workflow *with* an `index` script; this test covers the no-index path. **Conditional on `process.getuid() !== 0`.** *(Spec 3.2, 2.2, 4.1)*
- **T-VER-27c**: Cross-workflow first-entry `package.json` failure warning for a no-index workflow entered via qualified goto — invalid semver range variant. Same structure as T-VER-27a, but `.loopx/broken/package.json` contains `{ "dependencies": { "loopx": "not-a-range!!!" } }` (valid JSON but invalid semver range) instead of invalid JSON. Assert: (a) `broken:check` executes (marker file), (b) stderr contains exactly one invalid-semver warning for `broken` (emitted on first entry via goto), (c) no warning for `clean`, and (d) execution continues normally. Invalid-semver counterpart to T-VER-27a (invalid JSON) and T-VER-27b (unreadable) — T-VER-07f covers the same `package.json` failure mode on cross-workflow goto into a workflow *with* an `index` script; this test covers the no-index path. Together, T-VER-27a/27b/27c prove that all three `package.json` failure-warning branches fire on cross-workflow first entry into a no-index workflow via qualified goto, not just the version-mismatch branch (T-VER-27). *(Spec 3.2, 2.2, 4.1)*

### 4.14 Exit Codes (Cross-Cutting)

**Spec refs:** 12

- **T-EXIT-01**: Clean exit via `stop: true` → code 0. *(Spec 12)*
- **T-EXIT-02**: Clean exit via `-n` limit reached → code 0. *(Spec 12)*
- **T-EXIT-03**: Clean exit via `-n 0` → code 0. *(Spec 12)*
- **T-EXIT-04**: Successful subcommand (`loopx version`) → code 0. *(Spec 12)*
- **T-EXIT-05**: Script exits non-zero → code 1. *(Spec 12)*
- **T-EXIT-06**: Validation failure (name collision) → code 1. *(Spec 12)*
- **T-EXIT-07**: Invalid goto target → code 1. *(Spec 12)*
- **T-EXIT-08**: Missing workflow → code 1. *(Spec 12)*
- **T-EXIT-09**: Missing `.loopx/` directory → code 1. *(Spec 12)*
- **T-EXIT-10**: Usage error (invalid `-n`) → code 1. *(Spec 12)*
- **T-EXIT-11**: Missing `-e` file → code 1. *(Spec 12)*
- **T-EXIT-12**: SIGINT → code 130. *(Spec 12)*
- **T-EXIT-13**: SIGTERM → code 143. *(Spec 12)*
- **T-EXIT-14**: `loopx run` with no target → code 1 (usage error). *(Spec 12)*
- **T-EXIT-15**: `loopx ralph` (unrecognized subcommand) → code 1 (usage error). *(Spec 12)*
- **T-EXIT-16**: `loopx --unknown` → code 1 (usage error). *(Spec 12)*
- **T-EXIT-17**: Invalid target string (e.g., `":script"`) → code 1. *(Spec 12)*

---

## 5. Fuzz Testing

Fuzz tests use `fast-check` for property-based testing. They are designed to find edge cases that manual test enumeration misses.

### 5.1 Structured Output Fuzzer

**File:** `tests/fuzz/output-parsing.fuzz.test.ts`

**Approach:** Generate random strings and feed them as the stdout of a script in a workflow. Verify invariants hold for all inputs.

#### Generators

| Generator | Description |
|-----------|-------------|
| `arbitraryJSON` | Random valid JSON values (objects, arrays, strings, numbers, booleans, null) |
| `arbitraryString` | Random strings including unicode, control characters, empty, very long |
| `arbitraryOutputObject` | Random objects with `result`, `goto`, `stop` fields of various types |
| `arbitraryMalformedJSON` | Strings that look like JSON but are malformed |

#### Properties

- **F-PARSE-01: No crashes.** For any string written to stdout, loopx does not crash. Exits with code 0 or code 1. Never any other exit code for non-signal cases.
- **F-PARSE-02: Deterministic parsing.** Same stdout → same behavior.
- **F-PARSE-03: Type safety of parsed output.** `result` is always string, `goto` is always string, `stop` is always `true`.
- **F-PARSE-04: Raw fallback consistency.** Non-structured stdout → entire stdout becomes `result`.
- **F-PARSE-05: Non-ASCII safe.** UTF-8 with NUL bytes, control characters, high Unicode does not cause crashes.

**Iterations:** At least 1000 at unit-parser level (via `parseOutput` seam), 50–100 at E2E level.

### 5.2 Env File Fuzzer

**File:** `tests/fuzz/env-parsing.fuzz.test.ts`

#### Properties

- **F-ENV-01: No crashes.**
- **F-ENV-02: Deterministic parsing.**
- **F-ENV-03: Keys and values are strings.**
- **F-ENV-04: Last-wins for duplicates.**
- **F-ENV-05: Comment lines never produce variables.**

**Iterations:** At least 1000 at unit-parser level (via `parseEnvFile` seam), 50–100 at E2E level.

---

## 6. Supplementary Unit Tests

### 6.1 Output Parsing Unit Tests

**File:** `tests/unit/parse-output.test.ts`

Uses the `parseOutput` internal seam (section 1.4). Tests the parser function directly with valid JSON objects, type coercion cases, edge cases, non-object JSON values, and malformed JSON.

### 6.2 Env Parsing Unit Tests

**File:** `tests/unit/parse-env.test.ts`

Uses the `parseEnvFile` internal seam (section 1.4). Tests standard KEY=VALUE pairs, comments, blank lines, quoted values, duplicate keys, and edge cases.

### 6.3 Source Detection Unit Tests

**File:** `tests/unit/source-detection.test.ts`

Test the source classification logic (section 10.1) in isolation:

- `org/repo` → git (github)
- Various URLs → correct source type (`"git"` or `"tarball"`)
- URLs that would be single-file → throws (single-file URL install removed)
- Edge cases: URLs with ports, auth, paths, query strings

### 6.4 Compile-Time Type Tests

**File:** `tests/unit/types.test.ts`

**Required execution method:** Vitest typecheck mode, `tsc --noEmit`, or `tsd`.

- **T-TYPE-01**: `import type { Output, RunOptions } from "loopx"` compiles without error. *(Spec 9.5)*
- **T-TYPE-02**: `Output` has optional `result?: string`, `goto?: string`, `stop?: boolean` fields. *(Spec 9.5)*
- **T-TYPE-03**: `RunOptions` has optional `maxIterations?: number`, `envFile?: string`, `signal?: AbortSignal`, `cwd?: string` fields. *(Spec 9.5)*
- **T-TYPE-04**: `run()` returns `AsyncGenerator<Output>`. *(Spec 9.1, 9.5)*
- **T-TYPE-05**: `runPromise()` returns `Promise<Output[]>`. *(Spec 9.2, 9.5)*
- **T-TYPE-06**: `run()` and `runPromise()` accept an optional `RunOptions` second argument. *(Spec 9.1, 9.2, 9.5)*
- **T-TYPE-07**: `run()` and `runPromise()` require `target` as the first argument (`string`). Omitting `target` is a static type error. *(Spec 9.1, 9.2, 9.5)*

---

## 7. Edge Cases & Boundary Tests

- **T-EDGE-01**: Very long result string (~1 MB). Handled without truncation or hang. *(Spec 2.3)*
- **T-EDGE-02**: Result containing JSON-special characters. Correct serialization/deserialization. *(Spec 2.3)*
- **T-EDGE-03**: Script that writes stdout in multiple `write()` calls. Full output captured. *(Spec 2.3)*
- **T-EDGE-04**: Script that writes to both stdout and stderr. No interleaving issues. *(Spec 6.2, 6.3)*
- **T-EDGE-05**: Unicode in result values and env values preserved. Unicode in workflow/script names rejected (ASCII-only pattern). *(Spec 2.3, 5.3, 8.1)*
- **T-EDGE-06**: Deeply nested goto chain (A → B → C → ... → Z) including cross-workflow hops. Correct execution order and iteration counting. *(Spec 7.1)*
- **T-EDGE-07**: Script that produces output on stdout but also reads from stdin when no input is available. No deadlock. *(Spec 6.7)*
- **T-EDGE-11**: `-n` with very large value (e.g., `999999`). No integer overflow. *(Spec 4.2)*
- **T-EDGE-12**: Empty `.loopx/` directory (exists but no workflows). `loopx run ralph` → error. `loopx run -h` → run help with no workflows listed. *(Spec 4.1, 11.2)*
- **T-EDGE-14**: Env file with no newline at end of file. Last line still parsed. *(Spec 8.1)*
- **T-EDGE-15**: Env file that is completely empty (0 bytes). No error, no variables loaded. *(Spec 8.1)*

---

## 8. CI Configuration

### 8.1 Runtime Matrix

| Runtime | Versions |
|---------|----------|
| Node.js | 20.6 (minimum), latest LTS, latest current |
| Bun | 1.0 (minimum), latest |

### 8.2 Pipeline Stages

1. **Build**: Compile/bundle loopx.
2. **Phase 0 (Harness)**: Run `tests/harness/`. Fail the pipeline if any fail.
3. **Typecheck**: Run `tsc --noEmit` or `vitest typecheck` on `tests/unit/types.test.ts`.
4. **Unit Tests**: Run `tests/unit/`.
5. **E2E Tests**: Run `tests/e2e/`. Parameterized over runtime matrix.
6. **Fuzz Tests**: Run `tests/fuzz/` with CI-appropriate iteration count (e.g., 5000).
7. **Stub Validation** (optional, periodic): Run spec tests against stub binary.

### 8.3 Timeouts

| Suite | Timeout per test |
|-------|-----------------|
| Harness | 10s |
| Unit | 5s |
| E2E | 30s |
| E2E (signals) | 60s |
| Fuzz | 120s |

### 8.4 Parallelism

- Vitest runs test files in parallel by default. Each test file uses isolated temp directories.
- Signal tests should run serially within their file.
- Install tests that start local servers should share a single server instance per file.

---

## 9. Pending Spec Decisions

All previously identified spec problems (SP-15 through SP-31) have been resolved.

**Currently pending:**
- SP-32 (SSH/SCP URL classification — SPEC.md section 10.1 does not mention SSH or SCP-style URLs. No tests added until resolved.)

---

## Appendix A: Spec Requirement Traceability Matrix

Maps each SPEC.md section to the test IDs that verify it.

| Spec Section | Description | Test IDs |
|-------------|-------------|----------|
| 1 | Overview (ESM-only) | T-MOD-22 |
| 2.1 | Workflow and Script | T-DISC-01–20c, T-DISC-14a–14b, T-DISC-21a, T-DISC-15a–15b, T-DISC-25–38, T-DISC-26a–26b, T-EXEC-15–16a, T-MOD-03a, T-MOD-03c, T-INST-50a–50b, T-INST-52b, T-INST-53a–53c, T-INST-55c–55e, T-INST-56c–56d, T-INST-62a, T-INST-64d, T-INST-74a, T-INST-75a, T-INST-76a, T-API-08t5, T-API-08t6–08t8, T-API-08z, T-API-08z2–08z4, T-API-14j5, T-API-14j6–14j8, T-API-14p, T-API-14p2–14p4, T-API-36a, T-API-47a, T-VER-24d, T-VER-24e, T-VER-25b, T-VER-25c, T-VER-26, T-VER-26a–26c, T-VER-27a–27c |
| 2.2 | Loop (state machine, goto) | T-LOOP-01–05, T-LOOP-15a, T-LOOP-16–19, T-LOOP-19a–19b, T-LOOP-30–43, T-LOOP-30a, T-LOOP-31a–31c, T-LOOP-32a, T-EXEC-16b, T-MOD-05a, T-MOD-21a, T-CLI-111a, T-API-08ab, T-API-08t2–08t8, T-API-14j2–14j8, T-API-14r, T-API-35e, T-API-48a, T-VER-25b, T-VER-25c, T-VER-27, T-VER-27a–27c |
| 2.3 | Structured Output | T-PARSE-01–29, T-PARSE-12a, T-PARSE-20a, F-PARSE-01–05 |
| 3.1 | Global Install | T-INST-GLOBAL-01, T-INST-GLOBAL-01a |
| 3.2 | Local Version Pinning & Delegation | T-DEL-01–27, T-DEL-14a, T-DEL-14b, T-VER-01–27, T-VER-04a, T-VER-07a–07f, T-VER-10a–10b, T-VER-11a, T-VER-11b, T-VER-11c, T-VER-12a–12b, T-VER-13a, T-VER-13b, T-VER-13c, T-VER-14a, T-VER-15a, T-VER-18a, T-VER-19a–19c, T-VER-20a, T-VER-23a, T-VER-24a, T-VER-24b, T-VER-24c, T-VER-24d, T-VER-24e, T-VER-25a, T-VER-25b, T-VER-25c, T-VER-26a–26c, T-VER-27a–27c, T-CLI-119, T-CLI-119c, T-CLI-119e–119f, T-CLI-119h, T-CLI-119i–119k, T-MOD-03b, T-API-08aa, T-API-08ab, T-API-08b, T-API-08g, T-API-08o, T-API-08q, T-API-08s–08v, T-API-08u2, T-API-08u3, T-API-08w–08y, T-API-08z, T-API-08z2–08z4, T-API-08t2–08t8, T-API-14b2–14b4, T-API-14i–14l, T-API-14j2–14j8, T-API-14k2, T-API-14k3, T-API-14m–14o, T-API-14p, T-API-14p2–14p4, T-API-14q, T-API-14r, T-API-20p, T-API-20p2, T-API-20p3, T-API-20q, T-API-20q2, T-API-20r, T-API-20s, T-INST-60q–60s, T-INST-72a, T-INST-73a, T-INST-74a, T-INST-75a, T-INST-76a |
| 3.3 | Module Resolution | T-MOD-01–03, T-MOD-03a–03c, T-DEL-06, T-INST-GLOBAL-01, T-INST-GLOBAL-01a |
| 3.4 | Bash Script Binary Access | T-MOD-19–21, T-MOD-21a |
| 4.1 | Running Scripts (run subcommand, target validation) | T-CLI-11–13, T-CLI-27–33, T-CLI-59–60, T-CLI-64–66, T-CLI-78a–78d, T-CLI-80–81, T-CLI-85, T-CLI-96, T-CLI-107–118, T-CLI-109a, T-CLI-111a, T-CLI-114a, T-CLI-118a, T-CLI-118b, T-CLI-119a–119b, T-CLI-119d, T-CLI-119g–119h, T-CLI-119i–119k, T-DISC-33–37, T-API-08c–08d, T-API-08n, T-API-08n1, T-API-08r, T-API-08t5, T-API-08t6–08t8, T-API-08v, T-API-08w–08y, T-API-08z, T-API-08z2–08z4, T-API-14f–14h, T-API-14j5, T-API-14j6–14j8, T-API-14l, T-API-14m–14o, T-API-14p, T-API-14p2–14p4, T-API-20j–20k, T-API-20j2, T-API-20p2, T-API-20p3, T-API-20r, T-API-20s, T-API-35a–35f, T-API-36a, T-API-40–48, T-API-45a, T-API-47a, T-API-48a, T-API-44a–44c, T-LOOP-30a, T-LOOP-31a, T-LOOP-31c, T-LOOP-38–42, T-VER-24b, T-VER-24c, T-VER-24d, T-VER-24e, T-VER-25b, T-VER-25c, T-VER-26, T-VER-26a–26c, T-VER-27, T-VER-27a–27c |
| 4.2 | Options (-n, -e, run -h, install -h, top-level -h) | T-CLI-02–06, T-CLI-07b–07c, T-CLI-07e–07g, T-CLI-07j, T-CLI-14–22f, T-CLI-19a, T-CLI-20a–20b, T-CLI-28, T-CLI-34–100, T-CLI-78a–78d, T-CLI-101–102, T-CLI-101a, T-CLI-104–106, T-CLI-119–119h, T-CLI-119i–119k, T-ENV-25b–25c, T-INST-40–49, T-INST-40a–40e, T-INST-45a, T-INST-49a–49g, T-INST-41a, T-INST-42a–42l, T-INST-43a–43b, T-INST-57a, T-INST-59a–59b, T-INST-60n, T-API-08e–08q |
| 4.3 | Subcommands | T-SUB-01–19, T-SUB-02a–02k, T-SUB-06a–06b, T-SUB-14a–14k, T-CLI-66, T-CLI-80–81, T-MOD-21a |
| 5.1 | Discovery | T-DISC-01–16, T-DISC-10a–10g, T-DISC-14a–14b, T-DISC-38–42c, T-DISC-39a, T-DISC-40a–40i, T-DISC-48, T-DISC-48a, T-CLI-42–43, T-CLI-104–104e, T-CLI-121–122 |
| 5.2 | Name Collision | T-DISC-21–24, T-DISC-21a, T-DISC-40e, T-CLI-22b, T-CLI-43, T-CLI-43a, T-API-08h |
| 5.3 | Name Restrictions | T-DISC-15a–15b, T-DISC-25–32, T-DISC-26a–26b, T-DISC-40c–40d, T-DISC-40f–40i, T-DISC-47a, T-DISC-47b, T-CLI-44, T-CLI-22d–22e, T-CLI-102, T-CLI-120, T-CLI-120a, T-CLI-120b, T-LOOP-40–42, T-EDGE-05, T-API-08i–08j, T-API-20l–20o, T-INST-52b, T-INST-60d, T-INST-60m, T-INST-63a–63e |
| 5.4 | Validation Scope | T-DISC-43–47, T-DISC-47a, T-DISC-47b, T-SUB-02h, T-SUB-06, T-SUB-13, T-SUB-19, T-CLI-28, T-CLI-114a, T-CLI-118b, T-API-20l–20o, T-API-35c, T-API-35f, T-API-44b, T-API-44c |
| 6.1 | Working Directory | T-EXEC-01–03, T-EXEC-03a, T-EXEC-16, T-EXEC-16b, T-API-07a, T-API-47b |
| 6.2 | Bash Scripts | T-EXEC-05–07 |
| 6.3 | JS/TS Scripts | T-EXEC-08–14 |
| 6.4 | output() Function | T-MOD-04–14a, T-MOD-05a, T-MOD-13a–13p |
| 6.5 | input() Function | T-MOD-15–18 |
| 6.6 | Input Piping | T-LOOP-11–15, T-LOOP-15a |
| 6.7 | Initial Input | T-LOOP-14 |
| 7.1 | Basic Loop | T-LOOP-01–10, T-LOOP-25, T-CLI-119a–119b, T-CLI-119g–119h, T-CLI-119i–119k, T-VER-24–25, T-VER-24a, T-VER-24b, T-VER-24c, T-VER-24d, T-VER-24e, T-VER-25a, T-VER-25b, T-VER-25c, T-API-08w–08y, T-API-14m–14o, T-API-20p, T-API-20p2, T-API-20p3, T-API-20q, T-API-20q2, T-API-20r, T-API-20s |
| 7.2 | Error Handling | T-LOOP-18–24, T-LOOP-18a, T-LOOP-19a, T-LOOP-31c, T-LOOP-34–42, T-DISC-42a–42b, T-VER-25b, T-VER-25c |
| 7.3 | Signal Handling | T-SIG-01–08 |
| 8.1 | Global Env Storage | T-ENV-01–15f, T-ENV-05a–05e, T-ENV-25–25c, T-CLI-22c, F-ENV-01–05, T-API-08k–08m |
| 8.2 | Local Env Override | T-ENV-16–19, T-ENV-17a, T-ENV-25a, T-CLI-22f, T-API-08p, T-API-08p2 |
| 8.3 | Env Injection Precedence | T-ENV-20–24, T-ENV-20a, T-ENV-20b, T-ENV-21a, T-ENV-21b, T-ENV-21c, T-ENV-21d, T-ENV-24a, T-ENV-24b, T-EXEC-03a, T-EXEC-04–04c, T-DISC-39a |
| 9.1 | run() | T-API-01–09c, T-API-08a–08e, T-API-08g–08m, T-API-08n1, T-API-08o–08v, T-API-08u2, T-API-08u3, T-API-08w–08y, T-API-08z, T-API-08z2–08z4, T-API-08aa, T-API-08ab, T-API-08t2–08t8, T-API-10–10c, T-API-20h–20i, T-API-20j–20m, T-API-20j2, T-API-20p, T-API-20r, T-API-30–37, T-API-35a–35f, T-API-36a, T-PARSE-20a, T-TYPE-04, T-TYPE-06–07 |
| 9.2 | runPromise() | T-API-08f, T-API-08n, T-API-08p2, T-API-11–14l, T-API-14b2–14b4, T-API-14j2–14j8, T-API-14k2, T-API-14k3, T-API-14m–14o, T-API-14p, T-API-14p2–14p4, T-API-14q, T-API-14r, T-API-14a–14a3, T-API-20n, T-API-20o, T-API-20p2, T-API-20p3, T-API-20q, T-API-20q2, T-API-20s, T-API-25–25b, T-API-38–48, T-API-45a, T-API-47a–47b, T-API-48a, T-API-44a–44c, T-PARSE-20a, T-TYPE-05–07 |
| 9.3 | API Error Behavior | T-API-15–19, T-API-20a–20s, T-API-20p2, T-API-20p3, T-API-20q2, T-API-21c–21d |
| 9.4 | output() and input() (script-side) | *(Same as 6.4/6.5)* |
| 9.5 | Types / RunOptions | T-API-07–08, T-API-07a, T-API-08b–08r, T-API-08n1, T-API-08v, T-API-08w–08y, T-API-10–10c, T-API-14b2–14b4, T-API-14f–14h, T-API-14l, T-API-14m–14o, T-API-20d–20e, T-API-21–21b, T-API-22–25b, T-API-23a, T-API-24a–24b, T-API-47b, T-DISC-48a, T-TYPE-01–07 |
| 10.1 | Source Detection | T-INST-01–01a, T-INST-02–08f, T-INST-41, T-INST-42k, T-INST-42l |
| 10.2 | Source Type Details | T-INST-52d, T-INST-54d, T-INST-56b, T-INST-57c, T-INST-81–89, T-INST-83a, T-INST-85a–85b, T-INST-86a |
| 10.3 | Workflow Classification | T-INST-50–56, T-INST-50a–50b, T-INST-52a, T-INST-52c, T-INST-52d, T-INST-53a–53c, T-INST-54a–54d, T-INST-55a–55e, T-INST-56a–56e, T-INST-57b, T-INST-60o, T-INST-63e, T-INST-64, T-INST-64b, T-INST-80g, T-INST-83a, T-INST-85b |
| 10.4 | Install-time Validation | T-INST-52a–52d, T-INST-61–64, T-INST-62a, T-INST-63a–63e, T-INST-64a–64d, T-INST-72a, T-INST-73a, T-INST-74a, T-INST-75a, T-INST-76a, T-INST-80h–80j, T-INST-60a, T-INST-60e, T-INST-60g, T-INST-60h, T-INST-60n |
| 10.5 | Collision Handling | T-INST-65–71, T-INST-67a, T-INST-70a–70d, T-INST-71a, T-INST-97, T-INST-60c, T-INST-60k, T-INST-60l, T-INST-60p |
| 10.6 | Version Checking on Install | T-INST-72–76, T-INST-72a, T-INST-73a, T-INST-74a, T-INST-75a, T-INST-76a, T-INST-97b, T-VER-12–13, T-VER-12a–12b, T-VER-13a, T-VER-13b, T-VER-13c, T-VER-15, T-VER-15a, T-VER-17, T-VER-22, T-VER-23a, T-INST-80d–80f, T-INST-54b, T-INST-54d, T-INST-60b, T-INST-60f, T-INST-60i, T-INST-60j, T-INST-60q–60s, T-DEL-25 |
| 10.7 | Install Atomicity | T-INST-63e, T-INST-77–80j |
| 10.8 | Selective Workflow Installation | T-INST-57–60, T-INST-57a–57c, T-INST-59a–59b, T-INST-60a–60p, T-INST-60q–60s, T-INST-64c |
| 10.9 | Common Rules | T-INST-90–96, T-INST-97a |
| 11.1 | Top-Level Help | T-CLI-02–06, T-CLI-07e–07g, T-CLI-07j, T-CLI-28, T-CLI-39, T-CLI-61, T-CLI-65, T-CLI-90–91 |
| 11.2 | Run Help | T-CLI-40–43a, T-CLI-40a, T-CLI-62, T-CLI-67–78, T-CLI-84, T-CLI-92–95, T-CLI-101–102, T-CLI-101a, T-CLI-104–106, T-CLI-104a–104e, T-CLI-120–122, T-CLI-120a, T-CLI-120b, T-DISC-10d–10g, T-DISC-15b, T-DISC-38, T-DISC-40b–40e, T-DISC-40g–40i, T-VER-19, T-VER-19a–19c |
| 11.3 | Install Help | T-INST-41–42, T-INST-41a, T-INST-42a–42l, T-INST-49a–49g |
| 12 | Exit Codes | T-EXIT-01–17 |
| 13 | Summary of Special Values | *(Summary-only section — LOOPX_BIN: T-MOD-19–21, T-MOD-21a, T-ENV-20, T-ENV-20a, T-ENV-20b, T-DEL-05; LOOPX_PROJECT_ROOT: T-EXEC-03–03a, T-ENV-21, T-ENV-21a, T-ENV-21d; LOOPX_WORKFLOW: T-EXEC-04–04c, T-ENV-21b, T-ENV-21c; LOOPX_DELEGATED: T-DEL-04, T-DEL-07, T-DEL-09, T-ENV-24a; `index` convention: T-DISC-17–20, T-CLI-108–110, T-CLI-109a, T-INST-64, T-INST-64b–64d, T-INST-74a, T-INST-75a, T-INST-76a, T-LOOP-31c, T-API-20j2, T-API-20p2, T-API-20p3, T-API-45a, T-VER-24d, T-VER-24e, T-VER-25b, T-VER-25c; `:` delimiter: T-CLI-112–118, T-CLI-120a, T-CLI-120b, T-LOOP-36–42, T-API-30–44, T-INST-63b, T-INST-63c, T-INST-63e)* |