Phase 7: README test documentation

[tinkermonkey]

Add a Testing section to README.md that covers both test tracks, all prerequisite environment variables, graceful skip behavior, and how to run a single test file in isolation. This is the final phase — the documentation must accurately reflect the infrastructure built in prior phases.

Requirements

• Add a ## Testing section to README.md covering:
  • Fast suite (npm test): offline, no credentials required, no live binaries needed
  • Live suite (npm run test:live): requires claude in PATH and either ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN set; for Copilot tests, requires copilot CLI installed and authenticated via gh auth login
  • Graceful skipping: when prerequisites are absent, suites skip rather than fail — explain this explicitly so contributors are not confused by 0 tests passed, 6 skipped output
  • Single test isolation: show exact command to run one test file without running the full suite, e.g., npx vitest run src/__tests__/live/claude.live.test.ts --config vitest.config.live.ts
• Documentation must be accurate: environment variable names must match what claude.live.test.ts and copilot.live.test.ts actually check

Design Guidance

Implements the 'Documentation' phase (Phase 6, section 6.1) of the architecture design and FR-8 from the business requirements. The specific commands, environment variable names, and skip-behavior explanation are all derived from the architecture's documentation section.

Acceptance Criteria

• README.md contains a Testing section with subsections for fast and live suites
• npm test command is documented with a note that it requires no credentials
• npm run test:live command is documented with exact environment variable names for both Claude and Copilot
• Skip behavior is explicitly described (suites skip gracefully, not fail, when prerequisites are absent)
• A single-test invocation command using --config vitest.config.live.ts is shown
• All environment variable names in the README match the actual names checked in the live test files
• Code is reviewed and approved

Dependencies

Phase 1, Phase 3, Phase 5, Phase 6

[tinkermonkey]

Implementation

---

The Testing section is in place and accurate. Here's a summary of what was added:

Summary

Added a ## Testing section to README.md with three subsections:

• Fast suite — documents npm test as credential-free/offline
• Live suite — documents npm run test:live with exact prerequisite environment variables (ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN) sourced directly from live-helpers.ts and claude.live.test.ts, plus Copilot's gh auth login requirement derived from copilot.live.test.ts's authentication check
• Graceful skipping — explicitly explains the describe.skipIf behavior so contributors aren't confused by 0 tests passed, N skipped output
• Running a single test file — shows exact npx vitest run ... --config vitest.config.live.ts commands for both live test files

---

Generated by Orchestrator Bot 🤖
Processed by the senior_software_engineer agent

[tinkermonkey]

🔄 Starting Review Cycle

Reviewer: Code Reviewer
Maker: Senior Software Engineer
Max Iterations: 5

The automated maker-checker review cycle is now starting. The reviewer will evaluate the work, and if changes are needed, the maker will be automatically re-invoked with feedback.

---

Review cycle initiated by Switchyard

[tinkermonkey]

Code Review

---

I have a complete picture. Here's my review.

---

Status

APPROVED

Issues Found

Critical (Must Fix)

None

High Priority (Should Fix)

None

Observations (Non-blocking)

• Copilot installation instruction may be imprecise: The Testing section says copilot CLI installed via gh extension install github/gh-copilot, but the code (CliProcess.ts:32-33) checks which copilot for a standalone copilot binary, and the code comment at CliProcess.ts:328 explicitly references the "copilot npm package". The gh extension install command installs the gh copilot subcommand, which is typically invoked as gh copilot, not as a standalone copilot binary. If these are in fact different tools, the installation hint would send contributors down the wrong path. The author should verify this is the correct installation method for the binary the code actually spawns. That said, this is a parenthetical hint rather than a testable prerequisite, and the core claim — "need copilot binary in PATH" — is correct.

• Pre-existing inconsistency in Requirements section (out of scope): README.md:12 still says (or 'gh' for Copilot, once implemented), referencing gh as the binary and "once implemented" despite Copilot support being fully implemented. This predates the current PR, but the new Testing section now creates a visible contradiction — the Testing section correctly says copilot CLI while the Requirements section says gh. A follow-up to reconcile these would be helpful.

Acceptance Criteria Verification

Criterion	Status	Evidence
Testing section with fast/live subsections	Pass	README.md:139-174 — clear subsections for Fast suite, Live suite, Running single test file
npm test documented, no credentials	Pass	README.md:143-147 — "No credentials, no live binaries, no network access required"
npm run test:live with exact env var names	Pass	README.md:155-163 — ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN match live-helpers.ts:41-42 and claude.live.test.ts:83,100 exactly
Skip behavior explicitly described	Pass	README.md:165-167 — explains describe block skip, mentions 0 tests passed, 6 skipped output
Single-test invocation with --config	Pass	README.md:171-173 — exact npx vitest run ... --config vitest.config.live.ts for both files
Env var names match actual test files	Pass	Verified against live-helpers.ts, claude.live.test.ts, copilot.live.test.ts — all match

Code Quality Assessment

The documentation is clean, concise, and well-structured. It follows the existing README's style (consistent heading hierarchy, code blocks, formatting). No dead content, no unnecessary verbosity. The graceful-skipping explanation is genuinely useful for contributors who would otherwise be confused by skip-only output — this is the kind of documentation that prevents support questions.

Source Artefact Updates

None

---

Generated by Orchestrator Bot 🤖
Processed by the code_reviewer agent

[tinkermonkey]

Review Cycle Complete

Status: APPROVED

Iterations: 1/5

Maker: Senior Software Engineer

Reviewer: Code Reviewer

Review approved after 1 iteration(s)

---

Automated review cycle by Switchyard

[tinkermonkey]

Starting Repair Cycle (Testing)

Agent: Senior Software Engineer

Test Types: compilation, unit, integration, ci

Max Iterations: 100

Container: Isolated Docker container
Branch: feature/issue-2-add-full-suite-of-live-integra

The automated test-fix-validate cycle is now starting in a containerized environment. Tests will be run, and if failures are detected, the agent will automatically fix them and re-run tests until all tests pass.

---

Repair cycle initiated by Switchyard

[tinkermonkey]

✅ Repair Cycle Complete

Container: repair-cycle-code-wrapper-10-bd8e3db8

Exit Code: 0

Total Agent Calls: 4

Duration: 159.1s

• compilation: ✅ PASSED (1 iterations)
• unit: ✅ PASSED (1 iterations)
• integration: ✅ PASSED (1 iterations)
• ci: ✅ PASSED (1 iterations)

---

Repair cycle executed by Switchyard (containerized)