Implementa recomendação formal com adopção e conferência independente

docs/exemplos-orquestracao-compras.md

@@ -5,9 +5,10 @@ planeamento acrescenta itens por empresa, responsáveis, marcos e datas
 previstas/realizadas, com ligação posterior às requisições. O registo documental
 opcional da abertura e actas por versão também foi implementado. Seguiram-se
 qualificação documental, relatório de conferência e admissão/exclusão por
-adopção expressa (`d020be5`). A recomendação formal está proposta para validação
-em `docs/proposta-recomendacao.md`, com demonstração em
-`/proposta/recomendacao`; não está activa na base de negócio. Avaliação em
+adopção expressa (`d020be5`). O âmbito de recomendação formal foi depois
+validado e implementado com política própria, adopção opcional e conferência
+independente antes da adjudicação, sem activar políticas reais. A demonstração
+`/proposta/recomendacao` continua separada do circuito autenticado. Avaliação em
 novas modalidades continua por implementar. Estes avanços não importam os
 processos históricos nem aprovam as regras de cancelamento de ordens emitidas.
 
@@ -73,8 +74,8 @@ comportamento dos processos existentes.
 
 A visão do processo, o planeamento e os marcos, a abertura, a qualificação
 documental e a admissão/exclusão já foram entregues como incrementos próprios.
-O próximo circuito proposto é a recomendação formal antes da adjudicação,
-sujeita à validação de âmbito e sem alterar a comparação ponderada existente.
+A recomendação formal antes da adjudicação também foi entregue após validação,
+sem alterar a comparação ponderada existente.
 Novas modalidades, métodos de classificação, correcções de preços e dispensas
 continuam a exigir definição explícita.
 

docs/proposta-recomendacao.md

@@ -1,10 +1,12 @@
 # Proposta de âmbito para recomendação antes da adjudicação
 
-Estado: proposta para validação após a entrega de admissão/exclusão em
-`d020be5`. A demonstração `/proposta/recomendacao` não implementa uma nova
-decisão na base de negócio. Data: 28 de Outubro de 2026.
+Estado: âmbito validado pelo utilizador e implementado em 28 de Outubro de
+2026, após a entrega de admissão/exclusão em `d020be5`. O circuito real é
+opcional por empresa e por processo. A demonstração `/proposta/recomendacao`
+continua separada dos registos autenticados; nenhuma política real foi
+publicada nesta entrega.
 
-## Resultado preparado para revisão
+## Demonstração preparada antes da validação
 
 Uma proposta navegável, com cabeçalho, rodapé e menus partilhados do Sistema
 de Gestão de Compras (SGC), permite simular:
@@ -25,7 +27,7 @@ página não autentica outra pessoa e não demonstra segregação efectiva. As
 pontuações ilustram decisões de interface; não constituem um novo algoritmo
 de comparação. Não se reutilizam nomes ou valores dos exemplos históricos.
 
-## Circuito inicial proposto para o produto
+## Circuito inicial validado para o produto
 
 1. Administração da empresa activa uma política de recomendação versionada,
    com fundamento, perfis autorizados e quantidade de pessoas distintas.
@@ -98,7 +100,7 @@ decisões empresariais continuam a pertencer a cada aderente.
 - Tornar a recomendação obrigatória em todos os processos ou activar
   políticas reais por conta das empresas durante o desenvolvimento.
 
-## Verificações exigidas para a futura implementação
+## Verificações da implementação
 
 Isolamento e privacidade, identidade relida no servidor, autoria, segregação,
 perfil/departamento revogado, quórum sem duplicações, conflitos, matriz
@@ -108,20 +110,24 @@ rollback de auditoria, vínculo à adjudicação/emissão e concorrência
 PostgreSQL com processos independentes. Uma demonstração local não substitui
 estas verificações do circuito autenticado.
 
-## Validação necessária antes de implementar o circuito real
+## Validação recebida e activação
 
-Validar **recomendação manual por Compras, conferências independentes em
+O utilizador validou **recomendação manual por Compras, conferências independentes em
 quantidade/perfis definidos pela empresa, regime opcional por adopção
 expressa após admissão e vínculo à adjudicação da proposta recomendada**.
 
-A orientação de continuidade determina: «definir com a empresa o próximo
-âmbito pendente antes de o implementar», em
-`docs/orientacoes-continuidade.md`. A validação anterior autorizou admissão
-e exclusão; não definiu uma etapa de recomendação com estes efeitos. A
-implementação do circuito real aguarda a validação deste âmbito. As
-alterações locais dos três documentos de continuidade ficam preservadas.
+A Administração pode configurar `/politica-recomendacao`; Compras adopta a
+versão activa em `/requisicoes/{requisition}/recomendacao`, após adopção do
+regime de admissão e antes da adjudicação. Perfis e quantidade são escolhas
+expressas da empresa. O limite de 50 no formulário é técnico, sem quórum
+empresarial predefinido. A empresa deve assegurar pessoas elegíveis em número
+suficiente. Consultar `docs/validacao-tecnica.md` para resultados e limitações.
 
-## Verificações desta preparação
+A validação é do âmbito do produto; não publica políticas por conta das
+aderentes. As alterações locais dos três documentos de continuidade foram
+preservadas.
+
+## Histórico: verificações da preparação da demonstração
 
 Passaram os 18 testes de entrada e consulta pública, com 290 asserções,
 PHPStan, Pint, TypeScript, build e lint/formatação do âmbito. O acesso HTTP

docs/recomendacao-concorrencia-postgresql.json

@@ -0,0 +1,81 @@
+{
+    "tested_at_utc": "2026-10-28T18:42:31+00:00",
+    "separate_database": true,
+    "transport": "Independent PHP service transactions and PostgreSQL connections",
+    "scenarios": [
+        {
+            "name": "same_person",
+            "passed": true,
+            "overlapping_lock_waits": 2,
+            "reviews": 1,
+            "state": "pending",
+            "attempts": 1,
+            "awards": 0
+        },
+        {
+            "name": "distinct_people",
+            "passed": true,
+            "overlapping_lock_waits": 2,
+            "reviews": 2,
+            "state": "confirmed",
+            "attempts": 1,
+            "awards": 0
+        },
+        {
+            "name": "opposing_reviews",
+            "passed": true,
+            "overlapping_lock_waits": 2,
+            "reviews": 1,
+            "state": "pending",
+            "attempts": 1,
+            "awards": 0
+        },
+        {
+            "name": "revoked_role",
+            "passed": true,
+            "overlapping_lock_waits": 2,
+            "reviews": 0,
+            "state": "pending",
+            "attempts": 1,
+            "awards": 0
+        },
+        {
+            "name": "changed_basis",
+            "passed": true,
+            "overlapping_lock_waits": 2,
+            "reviews": 0,
+            "state": "pending",
+            "attempts": 1,
+            "awards": 0
+        },
+        {
+            "name": "new_adoption",
+            "passed": true,
+            "overlapping_lock_waits": 2,
+            "reviews": 0,
+            "state": "pending",
+            "attempts": 1,
+            "awards": 0
+        },
+        {
+            "name": "competing_attempts",
+            "passed": true,
+            "overlapping_lock_waits": 2,
+            "reviews": 0,
+            "state": "pending",
+            "attempts": 2,
+            "awards": 0
+        },
+        {
+            "name": "recommendation_versus_award",
+            "passed": true,
+            "overlapping_lock_waits": 2,
+            "reviews": 2,
+            "state": "confirmed",
+            "attempts": 2,
+            "awards": 0
+        }
+    ],
+    "passed": true,
+    "test_database_dropped": true
+}

docs/recomendacao-migracao-000020.json

@@ -0,0 +1,16 @@
+{
+    "verified_at_utc": "2026-10-28T18:45:44+00:00",
+    "migration": "2026_10_28_000020_create_formal_recommendations",
+    "batch": 21,
+    "backup_created": true,
+    "backup_bytes": 326150,
+    "restore_verified": true,
+    "restored_tables": 61,
+    "restore_database_dropped": true,
+    "business_records_unchanged": true,
+    "existing_constraints_preserved": true,
+    "env_unchanged": true,
+    "recommendation_policies_count": 0,
+    "recommendation_adoptions_count": 0,
+    "operational_validation": false
+}

docs/validacao-tecnica.md

@@ -1,5 +1,103 @@
 # Validação técnica do SGC — 28 de Outubro de 2026
 
+## Incremento: recomendação formal antes da adjudicação
+
+O âmbito de `docs/proposta-recomendacao.md` foi validado pelo utilizador e
+implementado. A Administração configura uma política própria de recomendação
+em `/politica-recomendacao`, com perfis Finanças e/ou chefia do departamento,
+quantidade de pessoas distintas, activação e fundamento expressos. Não há
+perfis ou quantidade inicialmente seleccionados. O máximo de 50 confirmações
+é um limite técnico e não define um quórum empresarial.
+
+Compras adopta a versão activa em `/requisicoes/{requisition}/recomendacao`,
+num pedido aprovado que já adoptou o regime de admissão, antes de adjudicar.
+Sem essa adopção, mantém-se o circuito existente. Uma versão geral nova ou
+desactivada não reescreve processos; a desactivação impede novas adopções.
+Trocar a versão aplicável exige adopção expressa e novas tentativas e
+conferências. Uma política de admissão não autoriza, por si, a recomendação.
+
+A recomendação exige matriz pronta, admissões confirmadas na base actual,
+três fornecedores distintos elegíveis e duas avaliações por proposta, sem
+alteração do cálculo ponderado existente. Compras, diferente do solicitante,
+escolhe expressamente entre as maiores pontuações e fundamenta, incluindo em
+empate. Não há desempate automático, dispensa do mínimo, escolha abaixo da
+maior pontuação ou autorização para corrigir preços.
+
+Cada tentativa preserva matriz, propostas/linhas, avaliações, referências e
+bases das admissões/requisitos/análises, conferências, política e proponente.
+Os dados de contacto ou documentos privados dos fornecedores não entram na
+matriz preservada. Uma nova tentativa é imutável e não herda confirmações.
+Uma devolução encerra a tentativa sem excluir o concorrente ou cancelar o
+processo. Conferências repetidas idênticas são idempotentes e contam uma vez.
+Identidades, empresa, perfil, departamento, segregação e conflitos são
+revalidados dentro da transacção, após o bloqueio da empresa. As confirmações
+anteriores são revalidadas até concluir o quórum; a história concluída conserva
+a elegibilidade verificada na sua data, sem autorizar futuras operações com
+perfil revogado. Uma pessoa não conta duas vezes após mudar de perfil.
+
+Nos processos com adopção, a adjudicação só selecciona a mesma proposta de
+uma recomendação confirmada na base actual. A referência e a base ficam
+preservadas na adjudicação e na ordem; são revalidadas antes de aprovar/emitir.
+Uma alteração de avaliação ou uma nova admissão pode invalidar a recomendação
+mesmo mantendo preços e pontuações. Não se reescrevem adjudicações/ordens
+anteriores. Existindo adjudicação, a adopção e as tentativas/conferências
+ficam fechadas; alterações exigem o circuito de revisão já suportado, quando
+autorizado. A repetição de uma emissão concluída devolve a mesma ordem.
+Recomendar não movimenta orçamento nem substitui as aprovações do valor final,
+regras de investimento, conflitos, facturas ou pagamentos.
+
+As páginas usam o cabeçalho, rodapé, menus e identificação Sistema de Gestão
+de Compras (SGC). Comparação, adjudicação e processo completo ligam ao novo
+circuito; o processo apresenta os eventos de auditoria. O relatório de
+conferência assinala a adopção e remete para o relatório preservado da
+recomendação. A impressão autenticada em `/recomendacoes/{attempt}/imprimir`
+mostra matriz/base originais, candidata, fundamentos, conferências, devoluções
+e tentativas anteriores da mesma adopção, distinguindo dados históricos da
+situação actual. As restantes adopções são consultáveis na página do processo.
+O conteúdo é escapado e a resposta é `private, no-store`. Em PostgreSQL, a
+impressão usa `REPEATABLE READ, READ ONLY`, relendo o operador; não cria
+auditoria nem outros registos. Não é uma assinatura digital ou certificação
+das evidências. A revisão visual da paginação continua pendente.
+
+Resultado da bateria completa: **498 testes aprovados, 2 ignorados, 4141
+asserções**. Inclui **17 cenários de recomendação**, com percurso genuíno até
+adjudicação/emissão, empate e escolha da proposta empatada, escolha abaixo
+da maior pontuação, matriz incompleta, admissão pendente/nova, mudanças de
+base, devolução, repetição, perfis/departamentos revogados, mesma identidade
+em perfis diferentes, política preservada, circuito sem adopção, segregação,
+isolamento, relatório histórico sem escrita, escape de conteúdo e rollback
+de auditoria de tentativa/conferência.
+
+Passaram **8 cenários PostgreSQL**, com processos PHP e ligações independentes
+e dois bloqueios simultâneos observados em cada cenário: mesma pessoa,
+pessoas distintas, respostas opostas, perfil revogado, avaliação alterada,
+nova adopção durante a espera, tentativas concorrentes e nova recomendação
+versus adjudicação. Conferiram-se quórum, versões, auditoria e vínculo à
+tentativa; a base de teste foi eliminada. O resultado está em
+`docs/recomendacao-concorrencia-postgresql.json`. Não se afirma que foram
+observadas todas as ordens possíveis de escalonamento ou testada corrida de
+impressão/emissão nesta bateria.
+
+Migração `000020`, lote **21**, aplicada em `compras_dev` após backup privado
+de **326150 bytes**, verificado por restauro numa base separada e eliminada
+depois da conferência. As **61 tabelas anteriores**, os registos de negócio
+por projecção das colunas originais, restrições existentes, histórico de
+migrações e `.env` foram preservados. São quatro tabelas novas e um campo
+JSON anulável na adjudicação. As quatro tabelas reais de recomendação estão
+vazias; não houve publicação de políticas, seeds ou compras reais. O relatório
+sanitizado está em `docs/recomendacao-migracao-000020.json`; backup e manifesto
+continuam privados e fora do Git. O rollback destrutivo automático é impedido.
+
+Pint, PHPStan, TypeScript, build e lint/formatação do âmbito passaram. A
+formatação global de `docs/compatibilidade.md`, alteração local alheia, continua
+pendente e fora do commit, juntamente com as alterações de desenvolvimento e
+continuidade preservadas. O navegador voltou a devolver `The browser access
+host is unavailable`: permanecem pendentes revisão visual pública, autenticada,
+de impressão e interacções no navegador. Validação operacional integral das
+empresas, novas modalidades/métodos de avaliação, dispensas, comunicação
+externa, cancelamento de ordens emitidas, estornos/devoluções e agregação por
+projecto/fraccionamento não são declarados concluídos por esta entrega.
+
 ## Preparação: proposta de recomendação formal
 
 Após `d020be5`, foi preparada `/proposta/recomendacao`, ligada ao menu