hardening: fix 5 Gemini findings before promoting v0.3.0 → @latest

[kokevidaurre]

Context

Surfaced during Gemini review of #756 (the develop→main release PR for v0.3.0-rc.1). All findings are in code shipped via PR #743 to main last night — not introduced by #756. Listed here as a single consolidated hardening track.

rc.1 ships to @next for burn-in without blocking on these. Fixing #1 is a P1 blocker before promoting rc.1 → 0.3.0 stable under @latest.

Findings

P1 — blocks @latest promotion

• Hardcoded telemetry API key — src/lib/telemetry.ts:34
  Write-only key stored in source. Violates previously-stated engineering guidelines. Even write-only keys can be abused (flooding, polluting analytics) and can't be rotated without a code change. Move to env var: process.env.SQUADS_TELEMETRY_KEY with a build-time inject if needed for the public binary.

P2 — fix in v0.3.1

• Broad catch block swallows auth errors — src/commands/credentials.ts:149
  Current catch swallows gcloud auth expired, leading to confusing downstream failures when the tool assumes the API is enabled. Re-throw auth errors explicitly.

• Aggressive YAML comment stripping — src/lib/config.ts:75
  Strips any # character, truncating URLs with fragments or string values like "C#". Per YAML spec, a comment must be preceded by a space — use /\s+#/ to locate the comment start.

• Brittle LLM task-assignment parsing — src/lib/workflow.ts:559
  Regex + includes() matching on agent names fails when names share substrings (e.g. lead matches team-lead). Switch the LLM prompt to request JSON-structured task assignments for reliable parsing.

P3 — fix when it becomes a problem

• Unbounded Promise.all over squads — src/commands/run.ts:240
  Running many squads in parallel without concurrency control risks 429 rate limits and local resource exhaustion. Add a concurrency limiter (p-limit or similar) when squad count > 8.

Release sequencing

1. 0.3.0-rc.1 → @next (ship now, burn-in)
2. Fix P1 (telemetry key) → 0.3.0-rc.2 or 0.3.0 → @latest
3. Bundle P2 items into 0.3.1
4. P3 when telemetry or user reports indicate scale is triggering it

[kokevidaurre]

Superseded by v0.3.1 release (npm @latest, 2026-04-24). Gemini findings addressed across PRs #748, #749, #750 in the v0.3.x cycle.