Mapa de governação GoCore

Visão humana da cadeia normativa (Factory → mainframe → app), inventário por local, sistemas de verificação e automações. Os caminhos assumem o monorepo com pastas irmãs factory.gocore.solutions/ e gocore.solutions/.

URLs para validação (norma de entrega)

Regra: indicar primeiro o URL do servidor onde o trabalho foi feito ou testado (dev local, staging, ou o mesmo host que serve o teu clone). O URL de produção (instance.domain em config/factory.json) só como linha principal de validação após deploy confirmado — antes disso presume-se que produção pode não ter o ficheiro.

Document root da Factory = public/. Hosts de referência no JSON: instance.local_dev_host (dev), instance.domain (produção).

  • 1 — Desenvolvimento local (prioridade para validar alterações no clone): https://factory.local.gocore.solutions/governance.html — requer nginx/cert conforme TEAM_DISCIPLINE_AND_SDLC.md / mainframe. Não assumir que abre sem curl 200 ou teste em browser externo.
  • 2 — Mesmo host da sessão (landing/login): se já estiveres na Factory no browser, usa o mesmo esquema e host (ex.: /governance.html na raíz pública) — coerente com landing.php.
  • 3 — Ficheiro no disco (prova no Git, sem servidor): factory.gocore.solutions/public/governance.html (relativo à raíz do monorepo).
  • 4 — Produção (só após deploy): https://factory.gocore.solutions/governance.html — só garantido quando o artefacto tiver sido publicado nesse vhost.

Não abre? ERR_NAME_NOT_RESOLVED ou ERR_CONNECTION_REFUSED

Porta correcta: o fallback php -S / composer run dashboard:dev da Factory usa só a porta 9089, não 9000 nem 8080. ERR_CONNECTION_REFUSED em 127.0.0.1:9000 = porta errada ou outro projecto — usa http://127.0.0.1:9089/governance.html com o servidor a correr.

O browser não consegue traduzir factory.local.gocore.solutions para um IP — falta configuração no Mac (ou o nginx não está a correr). Não é defeito da página; é DNS / hosts local.

  • A — Entrada em /etc/hosts (recomendado com HTTPS local): uma linha 127.0.0.1 factory.local.gocore.solutions (precisa de permissão de administrador para editar). Depois: certificado TLS e nginx conforme TEAM_DISCIPLINE_AND_SDLC.md e gocore.solutions/scripts/nginx/20-public-https.conf.
  • B — Sem DNS local (fallback imediato): na pasta factory.gocore.solutions/ (onde está o composer.json), no terminal: composer run dashboard:dev — serve public/ em http://127.0.0.1:9089/governance.html (HTTP, porta 9089). Equivale a php -S 127.0.0.1:9089 -t public. Ver AGENT_RULES.md §1.2.
  • C — Hostname local + porta 9089 (com /etc/hosts): com 127.0.0.1 factory.local.gocore.solutions e dashboard:dev a correr, também serve: http://factory.local.gocore.solutions:9089/governance.html#resolver-dns. Com nginx + TLS em 443, o mesmo ficheiro costuma estar em https://factory.local.gocore.solutions/governance.html (sem porta) — testado com HTTP 200 neste ambiente.
  • Domínio local.gocore.solutions (mainframe): o vhost https://local.gocore.solutions/ aponta para outro docroot — não há /governance.html da Factory aí (esperado 404). Para este mapa, usa sempre factory.local.gocore.solutions ou 127.0.0.1:9089.

Encadeamento normativo (prevalência)

Fonte canónica: factory.gocore.solutions/governance/GOVERNANCE_HIERARCHY.md

Ordem Camada O quê cobre Onde está Recomendação
1.º A — Geral IAs, MCP, supervisão, locking, segurança, modo auto, colocação de ficheiros na Factory. governance/AGENT_RULES.md, governance/AGENT_AUTONOMOUS_EXECUTION.md Fonte única para agentes; evita regras paralelas por ferramenta.
2.º B — Mainframe Estrutura httpdocs, contrato de app, login único, tenants, routing, deploy. gocore.solutions/sites/gocore.solutions/current/docs/APP_GOVERNANCE_RULES.md, Tier 1 em docs/README.md Manter registo APP_GOVERNANCE_REGISTRY.md alinhado ao disco.
3.º C — App Só delta específico da app, compatível com A+B (sem copiar Constituição). gocore.solutions/apps/<id>/docs/GOVERNANCE_DELTA.md Portal/marketplace: obriga COMPONENT_REGISTRY.md ou justificativa no PR.

Conflitos

Factory — documentos e artefactos (camada A)

Local / ficheiro Papel Recomendação
governance/AGENT_RULES.md Única fonte normativa completa para todas as IAs; §0.2 checkpoint A→B→C. Editar só aqui; depois php tools/build-agent-rules.php --apply.
governance/GOVERNANCE_HIERARCHY.md Definição das camadas e obrigações A/B/C. Leitura obrigatória antes de mudanças estruturais.
governance/DOCUMENTATION_GOVERNANCE.md Política Markdown na Factory; anti-proliferação. Cruzar com DOCUMENTATION_POLICY.md na plataforma (B).
governance/AGENT_AUTONOMOUS_EXECUTION.md Modo auto até conclusão, paralelismo, quando discutir. Reduz deriva em tarefas longas.
governance/TEAM_DISCIPLINE_AND_SDLC.md Git, branches, servidores, onboarding. Complementa A/B sem substituir hierarquia.
governance/GOVERNANCE_PRODUCT_AND_DEPLOYMENT.md Cenários de implantação Factory; §2.3 híbrido. §2.3 liga a MULTI_TENANT_CANONICAL.md (runtime).
governance/CONSTITUTION.md, IP_POLICY.md, ai-compatibility-policy.md Princípios e políticas transversais. Não duplicar em deltas de app (C).
governance/rules.json Regras para automação / compliance máquina-legível. Manter coerente com brigada e rules-sync-check.
config/compliance-matrix.json Matriz de compliance. Alterações = rever CI Factory e testes associados.
protocols/decision-supervision.md (e guias MCP) Supervisão, MCP, briefings. Suporte ao fluxo «parar e discutir».
Espelhos: raíz AGENTS.md, CLAUDE.md, .cursorrules Gerados por build-agent-rules.php. Não editar espelhos à mão — risco de deriva face à fonte.

Plataforma gocore.solutions — camada B (extracto)

Local Papel Recomendação
sites/.../current/docs/MAINFRAME_DOCS.md Mapa único de leitura da mainframe + TL;DR. Primeira porta de entrada humana na plataforma.
sites/.../current/docs/README.md Tiers 1 / 2 / 3 por domínio. Tier 1 prevalece sobre 2 e 3 em conflito.
sites/.../current/docs/DOCUMENTATION_POLICY.md Onde criar .md, scaffold, hooks e CI de doc. Respeitar lista branca da raíz do repo.
sites/.../current/docs/APP_GOVERNANCE_RULES.md Contrato de pasta app, routing, tenants, portal COMPONENT_REGISTRY. Nova app portal: usar new_app_scaffold.sh --portal.
sites/.../current/docs/APP_GOVERNANCE_REGISTRY.md Registo de apps vs GOVERNANCE_DELTA.md. Desalinhamento gera falha no delta-audit.
sites/.../current/docs/*_CANONICAL.md, leis GOCORE_*_V1.md Canónicos transversais e leis de engenharia. Um tema → um ficheiro canónico; actualizar índice.
sites/.../current/docs/DEPLOY_RULES.md Deploy, scaffold, smoke, satélite parceiro (princípios). Runbook detalhado de vendor só após decisão de produto.
sites/.../current/scripts/new_app_scaffold.sh Scaffold app; flag --portal gera stub COMPONENT_REGISTRY.md. Depois: rotas em index.php + registo.
gocore.solutions/AGENTS.md, sites/.../current/AGENTS.md Contexto Git / docroot para humanos e IAs. Não substituem AGENT_RULES.md (A).

Apps — camada C

Artefacto Regra Recomendação
apps/<id>/docs/GOVERNANCE_DELTA.md Obrigatório por app; compatível com A+B. Só delta; remeter canónicos na sites/.../docs/.
apps/<id>/docs/COMPONENT_REGISTRY.md Obrigatório para composição tipo portal (regra B). Modelo: app Horizon (apps/horizon/current/docs/COMPONENT_REGISTRY.md).
Múltiplos AGENTS.md dentro da app Convenção de contexto por pasta (ex. legado). Evitar contradizer GOVERNANCE_DELTA.md central.

Sistemas de verificação (local e CI)

Local / fluxo O quê faz Recomendação
gocore.solutions/scripts/pre-commit-documentation-guard.sh Bloqueia .md indevidos na raíz; aviso narrativa fora de docs/. Corre no hook Git e em pre-commit run.
gocore.solutions/.pre-commit-config.yaml Invoca o guard acima. Instalar com composer pre-commit:install na máquina dev.
gocore.solutions/scripts/ci/pr-hygiene.sh + workflow commit-hygiene.yml Guard sobre intervalo de commits em PR. Reduz merges com docs mal colocadas.
governance-brigade.yml → php scripts/governance-delta-audit.php Compara registo com GOVERNANCE_DELTA.md no disco. Correr antes de PR quando se mexer em apps.
php scripts/governance-registry-audit.php Coerência registo vs canónico ∪ espelho docroot. Avisos sobre apps só no espelho: migrar para gocore.solutions/apps/ quando possível.
composer run governance:delta-audit / governance:registry-audit Atalhos no composer.json da plataforma. Checklist no PR template da plataforma.
gocore.solutions/.github/pull_request_template.md Checkpoint A→B→C; portal / COMPONENT_REGISTRY. Reforço humano antes do merge.
Factory: .github/workflows/factory-ci.yml, documentation-placement.yml, factory-governance-pulse.yml, factory-tests.yml CI da Factory (secrets, regras, testes). Alterações em governance/ ou rules.json devem passar CI Factory.
gocore.solutions/scripts/predeploy_guardrails.sh Validação antes de concluir deploy (root limpa, permissões docs, etc.). Obrigatório após deploy (DEPLOY_RULES.md).

Automações Factory (ferramentas)

Ferramenta / script Função Recomendação
php tools/build-agent-rules.php --check / --apply Sincroniza espelhos IDE a partir de AGENT_RULES.md. Correr --check em PR que toque em regras.
php tools/rules-sync-check.php Verifica alinhamento de regras distribuídas. Parte do ritmo de release de governação.
php governance/brigade-audit.php (quando aplicável) Auditoria brigada Factory. Documentado em CLAUDE.md da Factory.
tools/task-manager.php, session-context.php Locks e contexto entre agentes. Não substituem decisão humana nem Git como fonte de verdade.

Observações gerais