Plataforma - Matriz de Uso dos Scripts¶

Objetivo¶

Esta pagina responde a pergunta operacional mais importante antes de apagar qualquer script:

quem chama, quando roda e qual o risco de remover?

A leitura correta desta matriz evita limpeza por intuicao e ajuda a manter o repositorio menor sem quebrar:

aplicacao;
agentes;
CI/CD;
release/readiness;
bootstrap local.

Como interpretar¶

Campo	Significado
`Chamado por`	principal entrypoint humano, `make target`, workflow ou script encadeador
`Quando roda`	manual, CI, runtime dos agentes ou operacao eventual
`Remocao`	`manter`, `revisar depois`, `nao remover agora`
`Risco`	impacto operacional caso o arquivo suma sem substituicao

1. Scripts do runtime dos agentes¶

Script	Chamado por	Quando roda	Remocao	Risco	Leitura
`scripts/agents_cli.py`	`make agents`	manual	manter	alto	wizard principal para humanos
`scripts/next_task_cli.py`	`./next-task`	manual	manter	alto	wrapper canônico do fluxo repo-aware
`scripts/ai-next-task.sh`	`./next-task`, `make next-task*`	manual/agentes	manter	alto	entrypoint real do fluxo agêntico
`scripts/run-task-block.sh`	`make next-task-block*`	manual	manter	médio/alto	execução de blocos fechados
`scripts/run_agent_runtime_pilot.py`	`make agent-runtime-pilot`	manual/diagnóstico	manter	médio	piloto determinístico do runtime
`scripts/prepare-repo-for-agent-run.sh`	`scripts/ai-next-task.sh`	runtime dos agentes	manter	alto	normaliza checkout e preflight
`scripts/agent-lock.sh`	`scripts/ai-next-task.sh`, uso interno	runtime/manual	manter	alto	impede concorrência perigosa no repo alvo
`scripts/check-agent-runtime-readiness.py`	`make agent-runtime-doctor`, `scripts/ai-next-task.sh`, `scripts/run-doctors.sh weekly`	manual/runtime	manter	alto	gate de quota, empty response e checkout
`scripts/agent_telemetry_summary.py`	`make agent-telemetry-summary`	manual	revisar depois	baixo/médio	útil para investigação, mas não bloqueia fluxo

2. Governança, board e docs¶

Script	Chamado por	Quando roda	Remocao	Risco	Leitura
`scripts/check-context-integrity.py`	`make context-integrity`, `make docs-build`, CI guardrails, `run-doctors.sh`	manual/CI	manter	alto	guarda canônica do repositório
`scripts/docs_governance_audit.py`	`make docs-governance-*`, auditorias locais	manual/CI	manter	médio	principal ferramenta de limpeza segura
`scripts/run-doctors.sh`	`make doctors-*`	manual/CI	manter	alto	agregador dos doctors
`scripts/sync_github_projects.py`	`make gh-project-*`, `make taskboard-catalog`, tools do `ai_squad`, workflows do projeto	manual/CI	manter	alto	entrypoint canônico de Projects; também cobre o catálogo legado
`scripts/run-doctors.sh`	`make governance-weekly-check`, `make doctors-*`	manual/CI	manter	alto	agregador único dos doctors, incluindo o ritual semanal
`scripts/install-git-hooks.sh`	`make install-hooks`	manual	manter	médio	garante enforcement local
`scripts/validate-branch-name.sh`	`make validate-branch-name`, `.githooks/pre-push`	manual/hook	manter	alto	protege branching policy
`scripts/check_github_rulesets.py`	`make github-ruleset-doctor`, CI guardrails	manual/CI	manter	alto	detecta drift remoto invisível
`scripts/apply-branch-protection.sh`	uso operacional pontual, `governance/github/README.md`	manual	manter	medio/alto	ferramenta manual de recuperacao/governanca; nao fica no caminho critico, mas ainda e a forma versionada de aplicar branch protection
`scripts/sync_github_wiki.py`	`make docs-sync-wiki`, workflow `sync-github-wiki`	manual/CI	manter	médio	mantém Wiki e docs sincronizados

3. Release, deploy e readiness¶

Script	Chamado por	Quando roda	Remocao	Risco	Leitura
`scripts/release_governance_doctor.py`	`make release-governance-doctor`, workflows de release	manual/CI	manter	alto	valida baseline multi-repo
`scripts/generate_release_evidence_pack.py`	`make release-evidence-pack`, workflow dedicado	manual/CI	manter	alto	gera evidência operacional
`scripts/release_tag_bootstrap.py`	`make release-tag-bootstrap-*`, workflow dedicado	manual	manter	médio/alto	baseline de tags e rastreabilidade
`scripts/frontend_deploy_baseline_doctor.py`	`make frontend-deploy-baseline-doctor`, `run-doctors.sh`	manual/CI	manter	médio/alto	valida baseline do web/app
`scripts/generate_frontend_deploy_readiness_report.py`	`make frontend-deploy-readiness-report`	manual	manter	médio	evidência de readiness
`scripts/public_release_readiness_doctor.py`	`make public-release-readiness-doctor`, workflows	manual/CI	manter	alto	gate de release pública
`scripts/generate_public_release_readiness_report.py`	`make public-release-readiness-report`, workflow	manual/CI	manter	médio/alto	relatório público por escopo
`scripts/g1_web_official_readiness_doctor.py`	`make g1-web-official-doctor`, workflow	manual/CI	manter	médio	gate do canal web oficial
`scripts/generate_g1_web_official_readiness_report.py`	`make g1-web-official-report`, workflow	manual/CI	manter	médio	relatório do G1
`scripts/frontend_deploy_baseline_lib.py`	doctors/reports de PLT5	interno	nao remover agora	alto	biblioteca compartilhada
`scripts/public_release_readiness_lib.py`	doctors/reports de PLT2	interno	nao remover agora	alto	biblioteca compartilhada
`scripts/release_governance_lib.py`	doctors/reports de release	interno	nao remover agora	alto	biblioteca compartilhada
`scripts/g1_web_official_readiness_lib.py`	doctors/reports de G1	interno	nao remover agora	alto	biblioteca compartilhada

4. Infra, bootstrap e suporte¶

Script	Chamado por	Quando roda	Remocao	Risco	Leitura
`scripts/setup-local-runtime.sh`	`make runtime-setup`	manual	manter	médio/alto	bootstrap local com paridade de CI
`scripts/setup-submodules.sh`	execução direta, `check-platform-orchestrator-readiness.sh`, `check-health.sh --session`	manual/diagnóstico	manter	medio	bootstrap explicito de submodules; ainda cobre onboarding e checks de sessao
`scripts/bootstrap-feature-flag-provider.sh`	`scripts/ai-next-task.sh`, `scripts/check-health.sh`, docs de feature flags	runtime/manual	manter	alto	bootstrap central de feature flags
`scripts/export-openapi-snapshot.sh`	`make openapi-snapshot`, docs OpenAPI	manual	manter	médio	snapshot canônico da API
`scripts/check-health.sh`	uso direto, `make agent-session-check`, docs de bootstrap	manual	manter	médio	útil para diagnóstico amplo; implementação interna modularizada em `scripts/lib/check_health_workspace.sh` e `scripts/lib/check_health_session.sh`
`scripts/check-platform-orchestrator-readiness.sh`	`make platform-doctor`, CI, `run-doctors.sh`	manual/CI	manter	alto	gate do repositório-orquestrador
`scripts/check-bootstrap-parity.sh`	`make bootstrap-parity-doctor`, CI, `run-doctors.sh`	manual/CI	manter	alto	protege paridade local/CI
`scripts/check-support-email-readiness.sh`	`make support-email-doctor`	manual	manter	médio	evidência operacional do canal de suporte
`scripts/setup-aws-ssm-devx.sh`	`make aws-ssm-setup`	manual	manter	médio	instala aliases de acesso remoto
`scripts/setup-aws-ssm-ssh-config.sh`	`make aws-ssm-setup`	manual	manter	médio	gera config SSH/SSM
`scripts/check-aws-ssm-devx.sh`	`make aws-ssm-doctor`	manual	manter	médio	doctor do acesso remoto AWS/SSM

5. DX e automações auxiliares¶

Script	Chamado por	Quando roda	Remocao	Risco	Leitura
`scripts/auraxis_toolbox.py`	`make context-pack`, `make fake-data`, `make postman-collection*`	manual	manter	médio/alto	toolbox DX ativa
`scripts/dependency_automation_health_report.py`	`make dependency-automation-health-report`, workflow recorrente	manual/CI	manter	médio	observabilidade da automação de dependências
`scripts/feature_flag_lifecycle_report.py`	`make feature-flag-lifecycle-report`	manual	manter	médio	relatório cross-repo de flags
`scripts/generate_task_lead_time_report.py`	`make lead-time-report`, workflow de métricas	manual/CI	manter	médio	relatório de lead time

Scripts preservados por contrato operacional¶

Os itens abaixo podem parecer "quietos" ou menos frequentes, mas continuam fazendo parte do contrato operacional do repositorio e nao entram mais na fila curta de limpeza:

Script	Motivo para preservar
`scripts/run-doctors.sh`	entrypoint unico dos doctors e do ritual semanal
`scripts/check-health.sh --session`	diagnostico canonico de preflight de sessao
`scripts/apply-branch-protection.sh`	ferramenta manual versionada de recuperacao/governanca
`scripts/setup-submodules.sh`	bootstrap explicito de submodules em onboarding e checks

Scripts que nao devem entrar em limpeza agressiva¶

Enquanto a arquitetura atual estiver em uso, estes arquivos sao nao negociaveis:

scripts/ai-next-task.sh
scripts/prepare-repo-for-agent-run.sh
scripts/agent-lock.sh
scripts/check-context-integrity.py
scripts/sync_github_projects.py
scripts/run-doctors.sh
scripts/bootstrap-feature-flag-provider.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

Conclusao¶

Hoje, a melhor decisao nao e sair apagando scripts. O melhor passo e:

manter os entrypoints e libraries que ainda sustentam runtime, release e governanca;
tratar a tabela de "revisao futura" como backlog de simplificacao;
remover scripts so quando a substituicao estiver clara e validada.