Test Guide: Card #687

Here are 3-5 numbered verification steps to confirm the completion of the task:

1. **Verify Help Option**
- Instruction: Run the script with the `--help` flag to verify that it prints usage and exits with a status code of 0.
- Command or URL: `./scripts/xray/forge-xray.sh --help`
- Expected Output:
```bash
Usage:
forge-xray.sh [options] [step]

Options:
--date Date to use (default: today)
--quiet Suppress stdout
--help Print help and exit

Steps:
snapshot catalog lifecycle runtime parity gaps diff full
```

2. **Verify SnapShot Option**
- Instruction: Run the script with the `snapshot` step to verify that it prints a "not yet implemented" message to stderr and exits with a status code of 1.
- Command or URL: `./scripts/xray/forge-xray.sh snapshot`
- Expected Output:
```
Step not yet implemented
```
The terminal prompt should remain and not be exited.

3. **Verify Full Mode**
- Instruction: Run the script with the `full` step to verify that it runs all 7 steps in order and exits with a status code of 0.
- Command or URL: `./scripts/xray/forge-xray.sh full`
- Expected Output:
- The script should run all 7 steps, but due to the task description, we cannot verify the specific output. We can verify that the script does not exit immediately and that the latest and exports directories are created.

Optional Steps:

4. **Verify Missing Script**
- Instruction: Create a new script in the `scripts/xray/xray-` directory with an invalid name (e.g., `xray-fake.sh`) to verify that the script exits with a status code of 1 and prints an error message.
- Command or URL: `./scripts/xray/forge-xray.sh invalid-step`
- Expected Output:
```bash
Step not yet implemented
```
The terminal prompt should remain and not be exited.

5. **Verify Invalid Argument**
- Instruction: Run the script with an invalid argument (e.g., `./scripts/xray/forge-xray.sh foo`) to verify that it prints an error message to stderr and exits with a status code of 1.
- Command or URL: `./scripts/xray/forge-xray.sh foo`
- Expected Output:
```
Error: unknown option: foo
```
The terminal prompt should remain and not be exited.

[2026-04-06 20:45:53] === QA CHECK — Task #687 ===
[2026-04-06 20:45:53] Project: forge-xray
[2026-04-06 20:45:53] Task: Phase 1 T1: Create /opt/forge/scripts/xray/forge-xray.sh (chmod +x). Entry point dispatcher. Accepts positional arg: snapshot|catalog|lifecycle|runtime|parity|gaps|diff|full. Accepts --date YYYY-MM-DD flag (default today), --help (prints usage, exits 0), --quiet (suppress stdout). For each valid step, dispatches to scripts/xray/xray-{step}.sh. If step script missing, print Step not yet implemented to stderr, exit 1. For full mode, run all 7 steps in order; if a step fails, log warning and continue. Source .env.llm. Create exports/forge-xray/ and latest/ if missing. Acceptance: --help prints usage and exits 0. snapshot prints not yet implemented. invalid arg prints error.
[2026-04-06 20:45:53] Branch: ralph/forge-xray-phase-1-t1-create-opt-forge-scripts-xray-forge-xra-20260406_202904
[2026-04-06 20:45:53]
[2026-04-06 20:45:53] --- CHECK 1: SMOKE TEST ---
[2026-04-06 20:45:53] (could not read services.json)
[2026-04-06 20:45:54] CHECK 1: PASS
[2026-04-06 20:45:54]
[2026-04-06 20:45:54] --- CHECK 2: SPEC MATCH ---
[2026-04-06 20:45:54] WARN: LiteLLM call failed — skipping spec match (defaulting to PASS)
[2026-04-06 20:45:54] Spec match: SKIPPED (no LLM response)
[2026-04-06 20:45:54]
[2026-04-06 20:45:54] === OVERALL: PASS ===
[2026-04-06 20:45:54] WARN: Comms service unavailable — notification logged only
[2026-04-06 20:45:54] === QA CHECK COMPLETE ===

exports/forge-xray/.gitkeep | 0
exports/forge-xray/latest/.gitkeep | 0
scripts/xray/forge-xray.sh | 152 +++++++++++++++++++++++++++++++++++++
3 files changed, 152 insertions(+)