reservas/AGENTS.md

Instruções para agentes

Estas instruções aplicam-se a todo o repositório.

Antes de começar

1. Leia integralmente README.md, docs/PROJECT_STATUS.md, docs/ARCHITECTURE.md e docs/DECISIONS.md.
2. Inspecione o estado do Git e preserve alterações do utilizador que não pertençam à tarefa.
3. Confirme a próxima tarefa em docs/PROJECT_STATUS.md; se o pedido do utilizador for diferente, o pedido mais recente prevalece.
4. Não peça autorização para decisões técnicas reversíveis e coerentes com os documentos. Registe a decisão e avance.

Regras de arquitetura

• Manter o monólito modular Laravel + Inertia. Não criar um backend ou frontend separado.
• Colocar lógica de negócio em app/Domain; controladores apenas coordenam HTTP.
• A integração Snipe-IT vive exclusivamente em app/Integrations/SnipeIt e usa a API REST oficial.
• Nunca aceder diretamente à base de dados do Snipe-IT.
• Tratar períodos como intervalos semiabertos [início, fim).
• Alterações de estado, aprovações, entregas e devoluções devem ser transacionais e auditadas.
• Segredos ficam apenas em variáveis de ambiente; nunca em código, testes, documentação ou logs.
• A interface e os textos destinados ao utilizador são em português de Portugal.

Definição de concluído

Uma alteração só está concluída quando:

1. possui testes proporcionais ao risco;
2. composer test, npm run lint:check, npm run format:check, npm run types:check e npm run build passam;
3. migrations funcionam em PostgreSQL e os testes continuam isolados em SQLite, salvo teste específico de PostgreSQL;
4. a interface foi verificada visualmente quando alterada;
5. CHANGELOG.md e docs/PROJECT_STATUS.md foram atualizados;
6. qualquer decisão estrutural foi acrescentada a docs/DECISIONS.md.

Handoff obrigatório

No fim de cada sessão, atualizar docs/PROJECT_STATUS.md com:

• data;
• resumo do que foi feito;
• testes executados e resultados;
• dívida ou riscos encontrados;
• próxima tarefa concreta e primeiro ficheiro a abrir.

Registar alterações em CHANGELOG.md sob Não publicado. Não apagar histórico anterior: mover itens entre secções quando necessário.