Plataforma - Scripts Operacionais

Objetivo

Este catálogo concentra os scripts operacionais do repositório auraxis-platform. A ideia é reduzir a ambiguidade entre scripts ativos, scripts de suporte e bibliotecas internas.

Ver também:

• Plataforma-Scripts-Matriz-de-Uso.md

Como ler este catálogo

• Entrypoint significa script pensado para execução direta por humano, CI ou automação.
• Library significa módulo auxiliar consumido por outros scripts e que não deve ser tratado como comando principal.
• Quando existir um make target, ele deve ser preferido ao invés de chamar o arquivo diretamente.

Entry points mais frequentes

Script	Via recomendada	Papel
scripts/agents_cli.py	make agents	Wizard interativo para operar o runtime dos agentes
scripts/ai-next-task.sh	./next-task ou make next-task	Entry point do fluxo agêntico repo-aware
scripts/check-context-integrity.py	make context-integrity	Guarda de integridade da documentação canônica
scripts/sync_github_projects.py	make gh-project-*	Fonte operacional do sync com GitHub Projects
scripts/run-doctors.sh	make doctors-*	Agregador dos doctors locais/CI
scripts/sync_github_wiki.py	make docs-sync-wiki	Publica docs/wiki/ na GitHub Wiki

1. Agentes e runtime

Script	Tipo	Via recomendada	Papel
scripts/agents_cli.py	Entrypoint	make agents	Wizard interativo de escolha de projeto, modo e briefing
scripts/next_task_cli.py	Entrypoint	./next-task	Wrapper CLI do fluxo next-task
scripts/ai-next-task.sh	Entrypoint	./next-task / make next-task	Orquestra preflight, gate, prepare do repo e kickoff do ai_squad
scripts/run-task-block.sh	Entrypoint	make next-task-block	Executa blocos fechados de tasks por repo
scripts/run_agent_runtime_pilot.py	Entrypoint	make agent-runtime-pilot	Piloto determinístico do runtime sem side effects reais
scripts/check-health.sh --session	Entrypoint	make agent-session-check ou execução direta	Verifica precondições de sessão do agente
scripts/agent-lock.sh	Entrypoint	uso interno	Mutex para impedir agentes concorrentes no mesmo repo
scripts/prepare-repo-for-agent-run.sh	Entrypoint	chamado por ai-next-task.sh	Normaliza checkout e preflight do repo alvo
scripts/check-agent-runtime-readiness.py	Entrypoint	make agent-runtime-doctor	Doctor de quota, empty response, circuit breaker e estado do checkout
scripts/agent_telemetry_summary.py	Entrypoint	make agent-telemetry-summary	Sumário rápido da telemetria local dos agentes

2. Governança, board e integridade

Script	Tipo	Via recomendada	Papel
scripts/check-context-integrity.py	Entrypoint	make context-integrity	Detecta drift, referências quebradas e inconsistência canônica
scripts/docs_governance_audit.py	Entrypoint	make docs-governance-audit	Auditoria de sprawl documental
scripts/run-doctors.sh	Entrypoint	make doctors-all, make doctors-ci, make doctors-quick	Orquestra doctors locais/CI
scripts/check-health.sh	Entrypoint	execução direta ou make agent-session-check	Diagnóstico amplo do workspace e preflight de sessão de agente; internamente modularizado em scripts/lib/check_health_workspace.sh e scripts/lib/check_health_session.sh
scripts/check-platform-orchestrator-readiness.sh	Entrypoint	make platform-doctor	Doctor do orquestrador da plataforma
scripts/check-bootstrap-parity.sh	Entrypoint	make bootstrap-parity-doctor	Paridade bootstrap local/CI
scripts/check_github_rulesets.py	Entrypoint	make github-ruleset-doctor	Detecta rulesets remotos fora da governança versionada
scripts/sync_github_projects.py	Entrypoint	make gh-project-*, make taskboard-catalog	Push, pull, drift, doctor, reconcile, conversão de drafts e catálogo legado de taskboards markdown
scripts/run-doctors.sh	Entrypoint	make governance-weekly-check	Ritual semanal de governança (modo weekly)
scripts/install-git-hooks.sh	Entrypoint	make install-hooks	Configura hooks locais do repo
scripts/validate-branch-name.sh	Entrypoint	make validate-branch-name	Valida branch contra conventional branching
scripts/apply-branch-protection.sh	Entrypoint	uso operacional pontual	Ferramenta manual preservada para aplicar a branch protection versionada em recuperacoes operacionais
scripts/generate_task_lead_time_report.py	Entrypoint	make lead-time-report	Relatório local de lead time por task

3. Release, deploy e readiness

Script	Tipo	Via recomendada	Papel
scripts/release_governance_doctor.py	Entrypoint	make release-governance-doctor	Doctor multi-repo de release
scripts/generate_release_evidence_pack.py	Entrypoint	make release-evidence-pack ENVIRONMENT=...	Evidence pack de release por ambiente
scripts/release_tag_bootstrap.py	Entrypoint	make release-tag-bootstrap-*	Planejamento/aplicação da primeira baseline de tags
scripts/frontend_deploy_baseline_doctor.py	Entrypoint	make frontend-deploy-baseline-doctor	Doctor do baseline mínimo de deploy web/app
scripts/generate_frontend_deploy_readiness_report.py	Entrypoint	make frontend-deploy-readiness-report	Relatório do baseline mínimo de deploy
scripts/public_release_readiness_doctor.py	Entrypoint	make public-release-readiness-doctor	Doctor de readiness pública oficial
scripts/generate_public_release_readiness_report.py	Entrypoint	make public-release-readiness-report	Relatório de readiness pública
scripts/g1_web_official_readiness_doctor.py	Entrypoint	make g1-web-official-doctor	Doctor do sub-bloco G1 (web oficial)
scripts/generate_g1_web_official_readiness_report.py	Entrypoint	make g1-web-official-report	Relatório do sub-bloco G1

4. Bibliotecas internas de operação

Script	Tipo	Consumido por	Papel
scripts/release_governance_lib.py	Library	release_governance_doctor.py, generate_release_evidence_pack.py	Shared lib do baseline de release
scripts/frontend_deploy_baseline_lib.py	Library	doctors/reports de PLT5	Shared lib do baseline de deploy frontend
scripts/public_release_readiness_lib.py	Library	doctors/reports de PLT2	Shared lib de readiness pública
scripts/g1_web_official_readiness_lib.py	Library	doctors/reports de G1	Shared lib do fluxo de web oficial

5. Infra, acesso remoto e suporte

Script	Tipo	Via recomendada	Papel
scripts/setup-aws-ssm-devx.sh	Entrypoint	make aws-ssm-setup	Instala aliases para AWS SSO/SSM
scripts/setup-aws-ssm-ssh-config.sh	Entrypoint	make aws-ssm-setup	Gera config SSH via SSM para IDE
scripts/check-aws-ssm-devx.sh	Entrypoint	make aws-ssm-doctor	Doctor de acesso remoto AWS/SSM
scripts/check-support-email-readiness.sh	Entrypoint	make support-email-doctor	Verifica DNS e readiness do canal suporte@auraxis.com.br

6. Bootstrap, docs e toolbox

Script	Tipo	Via recomendada	Papel
scripts/setup-local-runtime.sh	Entrypoint	make runtime-setup	Bootstrap local com defaults de paridade com CI
scripts/setup-submodules.sh	Entrypoint	execução direta	Inicializa/sincroniza submodules em onboarding e checks de sessao
scripts/bootstrap-feature-flag-provider.sh	Entrypoint	chamado por ai-next-task.sh ou manual	Bootstrap do provider de feature flags por ambiente
scripts/export-openapi-snapshot.sh	Entrypoint	make openapi-snapshot	Exporta snapshot canônico da OpenAPI
scripts/auraxis_toolbox.py	Entrypoint	make context-pack, make fake-data, make postman-collection*	Toolbox DX para Postman, fake data e context packs
scripts/sync_github_wiki.py	Entrypoint	make docs-sync-wiki	Sincroniza docs/wiki/ com a GitHub Wiki
scripts/dependency_automation_health_report.py	Entrypoint	make dependency-automation-health-report	Saúde da automação de dependências
scripts/feature_flag_lifecycle_report.py	Entrypoint	make feature-flag-lifecycle-report	Relatório contínuo de lifecycle de feature flags

Regras práticas

1. Prefira sempre o alvo make quando existir.
2. Se um script tiver par doctor e report, o doctor é para bloqueio/diagnóstico e o report para evidência.
3. Scripts *_lib.py não são comandos de uso humano; são bibliotecas internas.
4. Antes de remover qualquer script, validar:
5. se há target no Makefile;
6. se há workflow em .github/workflows/;
7. se há referência em .context/ ou docs/wiki/.

O que ainda não deve ser limpo agressivamente

Os scripts abaixo continuam sensíveis e não devem ser removidos sem matriz de uso explícita:

• scripts/prepare-repo-for-agent-run.sh
• scripts/ai-next-task.sh
• scripts/agent-lock.sh
• scripts/bootstrap-feature-flag-provider.sh
• scripts/setup-submodules.sh
• scripts/release_governance_lib.py
• scripts/frontend_deploy_baseline_lib.py
• scripts/public_release_readiness_lib.py
• scripts/g1_web_official_readiness_lib.py