GitHub Expert — Calculadora BMC

Operational guide for all GitHub work on matiasportugau-ui/Calculadora-BMC (default branch: main).

Tooling

• Claude Code on the web / remote sessions: use the GitHub MCP tools (mcp__github__*) for PRs, comments, CI status, and logs. gh CLI is NOT available there.
• Local sessions: gh CLI works if installed; MCP tools are the fallback.
• Never call the GitHub REST API directly with tokens from .env.

Branch & commit conventions

• Branch names: feat/..., fix/..., chore/..., docs/... (or the session-designated claude/* branch). Never commit directly to main.
• Commit messages: concise, English, type: prefix — feat, fix, refactor, docs, chore. Scope in parentheses is common: feat(ci): ..., fix(deps): ....
• If a branch's PR was already merged, never stack new commits on it — restart the branch from origin/main and open a new PR.

PR workflow (Definition of Done — docs/team/AGILE.md §3)

1. npm run gate:local green (lint + test + test:api). For large UI/build changes: npm run gate:local:full (adds build).
2. Fill the PR template (.github/PULL_REQUEST_TEMPLATE.md): Qué cambia, Closes #, Tipo checkbox, DoD checklist, Notas para el reviewer.
3. PR > 500 LOC adds → DRAFT obligatorio and split into atomic commits before marking ready (branch protection can't enforce this; we do).
4. If the change alters behavior, append a line under "Cambios recientes" in docs/team/PROJECT-STATE.md in the same PR.
5. Bot/agent-created PRs always start as draft.

CI — what runs and when

ci.yml ("CI — Panelin Calculadora BMC") on push + PR:

Job	What it does
validate	npm test (offline suite) + build
lint	ESLint on src/
env-drift	.env.example vs config drift check
smoke	Prod smoke (push to main only; MATRIZ CSV is the critical check)
channels_pipeline / voice_health / knowledge_antenna	Channel + voice + KB health checks

Other notable workflows:

• deploy-calc-api.yml / deploy-vercel.yml — Cloud Run (panelin-calc, us-central1) and Vercel deploys.
• catalog-diff.yml — Catalog ↔ MATRIZ diff; upserts a PR comment, fails on regression/S1.
• codeql.yml, dependency-review.yml — security gates.
• gemini-*.yml — Gemini review/triage bots (dispatch, review, scheduled triage).
• smoke-prod-scheduled.yml — scheduled prod smoke; failures open/refresh an auto-managed tracking issue.
• wa-canonical-cutover.yml — dispatchable WA migrate/flip/soak.
• labels-sync.yml — label catalogue is code-managed; don't hand-edit labels in the UI.

Red CI playbook

1. Identify the failing job (pull_request_read / actions_get), then pull job logs (get_job_logs, failed_only: true).
2. Reproduce locally: npm run gate:local (or the specific script the job runs).
3. Native midi build failures on Linux → missing ALSA headers (libasound2-dev); CI installs them, local containers may not.
4. Disk precheck false-fails on cloud FS → BMC_DISK_PRECHECK_SKIP=1.
5. Fix → commit → push; CI re-runs automatically. Use actions_run_trigger only for dispatchable workflows.
6. Several re-kicks with no progress → stop and report the diagnosis instead of looping.

Issues & board

• Backlog lives in GitHub Issues / Project BMC Dev; offline mirror docs/team/BACKLOG.md; board rules docs/team/AGILE.md.
• Priority labels: priority:P0 (drop everything) → priority:P1 → lower. Surface P0/P1 first in any triage.
• Search for duplicates before opening an issue; set state_reason when closing.

Guardrails

• npm audit fix --force is forbidden without explicit approval (it has broken Vite here).
• Secrets only in .env / Secret Manager — never in code, workflow files, or PR bodies.
• Never force-push main; force-with-lease on feature branches only when rebasing your own unshared work.
• Be frugal with bot comments on PRs — comment only when it genuinely adds signal.

Language

Respond in Spanish when the user writes in Spanish. Commands, file paths, and technical terms stay in English.