chore: main-side cleanup — docs + spec + python/TS parity

[drewdrewthis]

Summary

Consolidated main-side cleanup PR: docs housekeeping + spec housekeeping + python/TS parity fixes. Surfaced by a directory-structure audit on PR #561. Lands the changes for the follow-up issues listed under Closes below (most already closed; see that section).

File-structure changes

What moved, what was deleted, what was added (the recordings tree moved wholesale — 68 files — shown collapsed):

docs/
  voice-bug-bash.md                          ✖ deleted (orphan QA guide, zero refs)
  voice-twilio.md                            ✖ deleted (superseded by voice/adapters/twilio.mdx)
  voice/
    capability-matrix.md                     ✖ deleted ─┐ folded into the published mdx
    happy-path-elevenlabs.md                 ──► docs/docs/pages/voice/happy-path-elevenlabs.mdx   (published)
    happy-path-openai-realtime.md            ──► docs/docs/pages/voice/happy-path-openai-realtime.mdx (published)
  LOW_RISK_PULL_REQUESTS.md                  ──► .github/LOW_RISK_PULL_REQUESTS.md   (GitHub-process doc)
  docs/pages/voice/capability-matrix.mdx     ✎ edited (now the single source-of-truth; sidebar in docs/vocs.config.tsx)

javascript/
  docs/voice/capability-matrix.md            ✖ deleted ─┘ (was a divergent copy)

python/
  recordings/                                ──► python/outputs/recordings/   (whole tree: 18 demos, 68 files)
  outputs/README.md                          ✚ added (documents the new outputs/ parent)
  scenario/voice/assets/noise/*.wav          ✎ refreshed (cafe/street/office/airport + babble)
  scenario/voice/capabilities.py             ✎ edited (error msg → published capability-matrix URL)

javascript/src/voice/capabilities.ts         ✎ edited (error msg → published capability-matrix URL)
.github/workflows/pr-auto-approve.yml        ✎ edited (HTTP-406 oversized-diff handling; new LOW_RISK path)
javascript/tsconfig.json                     ✎ edited (removed duplicate "target" key)
specs/langwatch-pr-gate-pattern.feature      ✎ edited (dropped a stale, no-longer-meaningful scenario)

Changes

Docs housekeeping

• Delete two orphan docs — docs/voice-bug-bash.md (zero refs, stale to closed PR #355) and docs/voice-twilio.md (superseded by the published voice/adapters/twilio.mdx).
• Publish the two happy-path guides — docs/voice/happy-path-{elevenlabs,openai-realtime}.md → docs/docs/pages/voice/*.mdx, with sidebar entries in docs/vocs.config.tsx so they render on the docs site.
• Fold 3 capability-matrix files into 1 published source-of-truth — deleted docs/voice/capability-matrix.md and javascript/docs/voice/capability-matrix.md; merged into the existing docs/docs/pages/voice/capability-matrix.mdx. The error messages in python/scenario/voice/capabilities.py and javascript/src/voice/capabilities.ts now point at the published URL, and the JS contract-surface test (javascript/src/voice/__tests__/voice-contract-surface.test.ts) points at the published mdx.

Process / infra

• Move docs/LOW_RISK_PULL_REQUESTS.md → .github/ — GitHub-process docs idiomatically live alongside CODEOWNERS and PULL_REQUEST_TEMPLATE. The path is load-bearing in .github/workflows/pr-auto-approve.yml; the workflow regex, validator script, and spec assertions were updated in the same change. Verified via scripts/validate-pr-auto-approve.sh.
• Catch HTTP 406 in pr-auto-approve.yml diff fetch + harden reason interpolation — gh pr diff hits GitHub's 20k-line API cap on huge PRs (observed on #561, run 26644602950) and crashes the evaluate step before reaching the workflow's own oversized-diff guard. Two parts: (1) wrap the fetch with a grep-specific catch on the 20k-line error string (auth/network failures still exit 1); (2) emit oversized_reason via heredoc and pass it through the env: pattern to the fail-fast step (the documented GitHub Actions anti-shell-injection pattern, even when the source is gh stderr). Supersedes PR #572. Closes ci: evaluate workflow hard-fails on PRs >20k-line diff instead of its oversized path #571.
• Fix a duplicate "target" key in javascript/tsconfig.json — a pre-existing defect that broke the JS test suite under Node 24's strict JSON parser (it was already failing on main). This change unblocks that suite.

Spec housekeeping

• Remove the stale PR #1 does not modify the legacy approval workflows scenario in specs/langwatch-pr-gate-pattern.feature. It asserted PR Add Mintlify documentation #1 left approval-or-hotfix.yml and low-risk-evaluation.yml untouched, but both workflows have since been deleted on main, so the assertion is no longer meaningful. The matching traceability comment is updated to mark it removed. (The separate deletion scenarios for those two workflows in the same spec are unaffected.)

Python / TS parity

• Rename python/recordings/ → python/outputs/recordings/ — mirrors the TS rename + nest in PR #561. outputs/ is the parent for all test-run artifacts (recordings now, traces/logs/screenshots later): "outputs" describes the purpose, "recordings" the format. The helper module and function names are preserved (_recording_helper.py, save_demo_recording); a new python/outputs/README.md documents the parent dir.
• Refresh python/scenario/voice/assets/noise/*.wav to match the layered, distinct cafe / street / office / airport ambience (plus the babble sample used by the multiple_voices effect) now shipping on TS in PR #561. Closes the parity gap in backgroundNoise(). Generated with the same deterministic seeded generator as the TS assets (which ship on feat(typescript-sdk): voice agent testing — consolidated clean stack #561, not yet on main), so the two are reproducible from one seed; a single canonical generator that writes both targets is tracked as follow-up voice: fold to one canonical noise-sample generator (single source-of-truth) #588.

Test sanity

• Python voice unit + capability + recording suites pass with 0 regressions (see CI). Live-LLM / integration tests are deselected under CI=true (they require API keys).
• The capability error-message refactor keeps the existing "capability matrix" in str(err) assertion green; the recordings rename is path-only, so the recording artifact contract is unchanged.

Out of scope (kept as one follow-up issue)

• voice: fold to one canonical noise-sample generator (single source-of-truth) #588 — fold to a single canonical noise-sample generator (one script that writes both python/scenario/voice/assets/noise/*.wav AND javascript/src/voice/assets/noise/*.wav). Architectural change; deferred.

Closes

Closes #571.

Also carries to main the work tracked by #587, #589, and #590 — those issues were already closed on 2026-05-29; this PR lands their changes. (GitHub auto-closes only the still-open #571 on merge.)

🤖 Generated with Claude Code

[drewdrewthis]

/prove-it: PASS + /review: clean (re-verified at 06489d8, after addressing review findings).

All ACs across #571 / #587 / #589 / #590 + PR-body claims map to first-hand evidence:

• ci: evaluate workflow hard-fails on PRs >20k-line diff instead of its oversized path #571 — evaluate 406/oversized: specific-grep catch routes the GitHub 20k-line diff cap → oversized path (exit 0); genuine auth/network errors still exit 1; oversized_reason passed via env: (shell-injection-hardened). evaluate job is green on this head. ✅
• voice(python): noise-sample parity with TS + rename recordings → outputs #587 — noise WAVs refreshed to 3.00s / 24kHz (was 0.5s placeholder); python/recordings/ → python/outputs/recordings/ rename complete (helper points there, no stale refs); LICENSES.md updated. ✅
• docs(voice): publish or demote orphan voice docs (capability-matrix, happy-path-*) #589 / docs(voice): reduce 3 capability-matrix files to 1 source-of-truth + 1 published #590 — 3 capability-matrix files folded to 1 published .mdx; py + ts error messages point at https://scenario-docs.langwatch.ai/voice/capability-matrix. ✅
• Docs/infra — 2 orphan docs deleted; LOW_RISK_PULL_REQUESTS.md → .github/ (workflow regex + validator + spec changed in coordination); tsconfig.json duplicate target key fixed; stale AC-1.11 assertion removed. ✅
• Tests — voice unit 315 passed, 35 deselected (CI-equivalent), capabilities 5/5, recording 11/11. ✅

Review findings addressed (commit 06489d8):

1. (blocking) scripts/validate-pr-auto-approve.sh AC-1.11 block asserted two workflows exist that were deleted in PR feat: scenario events #4 → validator exited 1 despite the workflow being correct. The PR body cited this script as verification. Fixed — stale block removed, validator now exits 0 (mirrors the spec's own AC-1.11 removal).
2. LICENSES.md regen instruction pointed at generate-noise-samples.mjs, which ships on feat(typescript-sdk): voice agent testing — consolidated clean stack #561 and isn't on main yet. Fixed — reworded to reference feat(typescript-sdk): voice agent testing — consolidated clean stack #561 + follow-up voice: fold to one canonical noise-sample generator (single source-of-truth) #588.
3. PR-body "byte-identical to the TS asset bundle" softened — no TS bundle on main to compare against; assets are reproducible from the same seed.

Non-fixes (deliberate): spec Background line listing the two now-deleted workflows is the pre-sequence (t0) baseline every scenario references — not a current-state claim — so it's correct as-is. Filed #592 for the systemic gap that the validator is never run in CI.

_{🤖 /prove-it + /review via Claude Code}

[drewdrewthis]

📣 Slack PR-review request posted to #dev — thread. (CI 🟢 on 06489d8, /prove-it + /review clean.) Label slack-requested may be absent due to the org OAuth-App restriction on this token; this comment is the dedup marker.

[github-actions]

Automated low-risk assessment

This PR was evaluated against the repository's Low-Risk Pull Requests procedure and does not qualify as low risk.

This PR's diff exceeds the size limit for automated low-risk evaluation. Manual review required.

This PR requires a manual review before merging.